essentially a rewrite

.env.example

···
 NEXTAUTH_SECRET=
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
+GITHUB_OAUTH_CLIENT_ID=
+GITHUB_OAUTH_CLIENT_SECRET=
 GITHUB_WEBHOOK_SECRET=
 TURSO_TOKEN=
 NEXT_PUBLIC_GITHUB_APP_SLUG=
 GITHUB_APP_ID=
 GITHUB_APP_PRIVATE_KEY=
-APP_URL=
-NEXTAUTH_URL=
+APP_URL=http://localhost:3000
+NEXTAUTH_URL=http://localhost:3000
 TURSO_URL=

.gitignore

···
 # typescript
 *.tsbuildinfo
 next-env.d.ts
-envbackup.txt
+envbackup.txt
+refactor.md

ARCHITECTURE_REFACTOR.md

···
-# Architecture Refactoring Plan: From Conditional Spaghetti to Clean Architecture
-
-## Problem Statement
-
-The current codebase has conditional logic scattered throughout, checking for demo mode at multiple levels:
-- API routes checking environment variables
-- Components handling different data sources
-- Auth system with conditional mock data
-- Database queries with fallbacks
-
-This violates the **Single Responsibility Principle** and **Dependency Inversion Principle**, making the code:
-- Hard to maintain
-- Prone to bugs
-- Difficult to test
-- Inconsistent in behavior
-
-## Proposed Solution: Hexagonal Architecture (Ports & Adapters)
-
-### Why Hexagonal Architecture?
-
-1. **Clear separation of concerns**: Business logic is isolated from infrastructure
-2. **Testability**: Easy to test with mock adapters
-3. **Flexibility**: Switch between implementations without changing core logic
-4. **Consistency**: Same code paths for all modes
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Presentation Layer                    │
-│                  (React Components, API Routes)          │
-└─────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────┐
-│                    Application Layer                     │
-│                    (Use Cases/Services)                  │
-└─────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────┐
-│                      Domain Layer                        │
-│              (Business Logic, Entities, Ports)           │
-└─────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────┐
-│                   Infrastructure Layer                   │
-│                        (Adapters)                        │
-│  ┌────────────┐  ┌────────────┐  ┌────────────┐       │
-│  │   Demo     │  │   Turso    │  │   GitHub   │       │
-│  │  Adapter   │  │  Adapter   │  │  Adapter   │       │
-│  └────────────┘  └────────────┘  └────────────┘       │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Implementation Plan
-
-### Phase 1: Define Core Interfaces (Ports)
-
-Create interfaces that define what our application needs, regardless of implementation:
-
-```typescript
-// lib/core/ports/repository.port.ts
-export interface IPullRequestRepository {
-  getRecent(orgId: string, limit?: number): Promise<PullRequest[]>
-  getByCategory(orgId: string, timeRange?: TimeRange): Promise<CategoryDistribution>
-  getTimeSeries(orgId: string, days: number): Promise<TimeSeriesData>
-}
-
-// lib/core/ports/metrics.port.ts
-export interface IMetricsService {
-  getSummary(orgId: string): Promise<MetricsSummary>
-  getRecommendations(orgId: string): Promise<Recommendations>
-  getTeamPerformance(orgId: string): Promise<TeamPerformance>
-}
-
-// lib/core/ports/auth.port.ts
-export interface IAuthService {
-  getSession(): Promise<Session | null>
-  getUserOrganizations(userId: string): Promise<Organization[]>
-}
-```
-
-### Phase 2: Implement Adapters
-
-Create concrete implementations for each environment:
-
-```typescript
-// lib/infrastructure/adapters/demo/pull-request.adapter.ts
-export class DemoPullRequestRepository implements IPullRequestRepository {
-  private demoData = loadDemoData()
-  
-  async getRecent(orgId: string, limit = 10): Promise<PullRequest[]> {
-    return this.demoData.pullRequests.slice(0, limit)
-  }
-  
-  async getByCategory(orgId: string, timeRange?: TimeRange): Promise<CategoryDistribution> {
-    return generateDemoCategoryDistribution(timeRange)
-  }
-  
-  async getTimeSeries(orgId: string, days: number): Promise<TimeSeriesData> {
-    return generateDemoTimeSeries(days)
-  }
-}
-
-// lib/infrastructure/adapters/turso/pull-request.adapter.ts
-export class TursoPullRequestRepository implements IPullRequestRepository {
-  constructor(private db: TursoClient) {}
-  
-  async getRecent(orgId: string, limit = 10): Promise<PullRequest[]> {
-    return this.db.query(`SELECT * FROM pull_requests WHERE org_id = ? LIMIT ?`, [orgId, limit])
-  }
-  
-  async getByCategory(orgId: string, timeRange?: TimeRange): Promise<CategoryDistribution> {
-    // Real database query
-  }
-  
-  async getTimeSeries(orgId: string, days: number): Promise<TimeSeriesData> {
-    // Real database query
-  }
-}
-```
-
-### Phase 3: Dependency Injection Container
-
-Create a container that provides the right implementations based on configuration:
-
-```typescript
-// lib/core/container.ts
-export class DIContainer {
-  private static instance: DIContainer
-  private services: Map<string, any> = new Map()
-  
-  static getInstance(): DIContainer {
-    if (!DIContainer.instance) {
-      DIContainer.instance = new DIContainer()
-      DIContainer.instance.initialize()
-    }
-    return DIContainer.instance
-  }
-  
-  private initialize() {
-    const config = this.loadConfiguration()
-    
-    // Register services based on configuration
-    if (config.isDemoMode) {
-      this.registerDemoServices()
-    } else {
-      this.registerProductionServices()
-    }
-  }
-  
-  private registerDemoServices() {
-    this.services.set('PullRequestRepository', new DemoPullRequestRepository())
-    this.services.set('MetricsService', new DemoMetricsService())
-    this.services.set('AuthService', new DemoAuthService())
-  }
-  
-  private registerProductionServices() {
-    const db = new TursoClient(process.env.TURSO_URL!, process.env.TURSO_TOKEN!)
-    this.services.set('PullRequestRepository', new TursoPullRequestRepository(db))
-    this.services.set('MetricsService', new TursoMetricsService(db))
-    this.services.set('AuthService', new GitHubAuthService())
-  }
-  
-  get<T>(serviceName: string): T {
-    return this.services.get(serviceName)
-  }
-}
-```
-
-### Phase 4: Simplify API Routes
-
-API routes become thin controllers that delegate to services:
-
-```typescript
-// app/api/pull-requests/recent/route.ts
-import { DIContainer } from '@/lib/core/container'
-import { IPullRequestRepository } from '@/lib/core/ports'
-
-export async function GET(request: NextRequest) {
-  const container = DIContainer.getInstance()
-  const prRepository = container.get<IPullRequestRepository>('PullRequestRepository')
-  const authService = container.get<IAuthService>('AuthService')
-  
-  try {
-    const session = await authService.getSession()
-    if (!session) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-    }
-    
-    const data = await prRepository.getRecent(session.orgId)
-    return NextResponse.json(data)
-  } catch (error) {
-    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
-  }
-}
-```
-
-### Phase 5: Update Components
-
-Components don't need to know about demo mode:
-
-```typescript
-// components/actionable-recommendations.tsx
-export function ActionableRecommendations() {
-  const [recommendations, setRecommendations] = useState<Recommendations | null>(null)
-  
-  useEffect(() => {
-    // Just fetch data - no knowledge of demo vs production
-    fetch('/api/metrics/recommendations')
-      .then(res => res.json())
-      .then(setRecommendations)
-      .catch(console.error)
-  }, [])
-  
-  // Same rendering logic for all modes
-  return <div>{/* ... */}</div>
-}
-```
-
-## Migration Strategy ✅ **COMPLETED**
-
-### Step 1: Create Port Interfaces ✅ **COMPLETED**
-- ✅ Define all port interfaces (`IPullRequestRepository`, `IMetricsService`, `IAuthService`, etc.)
-- ✅ Document expected data structures (Domain entities with proper TypeScript types)
-- ✅ Create TypeScript types for all entities (`PullRequest`, `Organization`, `User`, etc.)
-
-### Step 2: Implement Demo Adapters ✅ **COMPLETED**
-- ✅ Create demo adapter for each port (`DemoPullRequestRepository`, `DemoMetricsService`, etc.)
-- ✅ Move existing demo data generation to adapters (Clean separation from business logic)
-- ✅ Test demo adapters in isolation (Functional demo mode verified)
-
-### Step 3: Implement Production Adapters ⚠️ **PARTIALLY COMPLETED**
-- ✅ Create Turso database adapter (Full production database integration implemented)
-- ⚠️ Create GitHub API adapter (Demo wrapper implemented, real GitHub API integration needed)
-- ✅ Create NextAuth adapter (Production auth service with proper database integration)
-
-### Step 4: Build DI Container ✅ **COMPLETED**
-- ✅ Implement container with service registration (`DIContainer` with environment-based service registration)
-- ✅ Add configuration loading (`EnvironmentConfig` singleton with feature detection)
-- ✅ Add environment detection (Automatic demo vs production mode detection)
-
-### Step 5: Refactor API Routes ✅ **COMPLETED** + **ENHANCED**
-- ✅ Update each API route to use DI container (`ServiceLocator` pattern implemented)
-- ✅ Remove all conditional logic (Clean, single-path execution)
-- ✅ Add consistent error handling (Enterprise-grade error boundaries)
-- 🚀 **BONUS**: Implemented advanced authentication middleware architecture
-  - ✅ `withAuth` middleware for authenticated routes
-  - ✅ `withOptionalAuth` middleware for flexible authentication
-  - ✅ `ApplicationContext` for clean dependency injection
-  - ✅ Migrated all API routes to new authentication pattern
-
-### Step 6: Clean Up Components ✅ **COMPLETED**
-- ✅ Remove demo mode checks from components (Components now mode-agnostic)
-- ✅ Ensure consistent data fetching (All components use standard API calls)
-- ✅ Update error boundaries (Robust error handling implemented)
-- 🧹 **BONUS**: Complete legacy code cleanup
-  - ✅ Deleted 5 obsolete files (`demo-mode.ts`, `demo-fallback.ts`, etc.)
-  - ✅ Removed ~400+ lines of conditional logic
-  - ✅ Updated all files to use clean `EnvironmentConfig` pattern
-
-### Step 7: Testing & Documentation ⚠️ **IN PROGRESS**
-- ✅ Architecture documentation updated (This file)
-- ✅ Build verification completed (Clean TypeScript compilation)
-- ✅ Demo mode functional testing completed
-- [ ] Unit tests for adapters (Recommended for production readiness)
-- [ ] Integration tests for API routes (Recommended for production readiness)
-- ✅ Update documentation (Architecture docs updated, implementation complete)
-
-## 🎉 **REFACTORING COMPLETE - STATUS REPORT**
-
-### **📊 Final Results**
-
-**Original Goals vs Achieved:**
-- ✅ **Single code path**: Achieved - Zero conditional demo logic in components/routes
-- ✅ **Clean separation**: Achieved - Perfect hexagonal architecture implementation
-- ✅ **Maintainability**: Achieved - 50% reduction in code complexity
-- ✅ **Type safety**: Achieved - Full TypeScript coverage with proper interfaces
-- 🚀 **EXCEEDED**: Added enterprise-grade authentication architecture
-
-### **📈 Measurable Improvements**
-
-| Metric | Before | After | Improvement |
-|--------|--------|--------|-------------|
-| **Conditional Logic** | ~50+ scattered checks | 0 in business logic | ✅ **100% elimination** |
-| **Code Duplication** | High (demo vs prod paths) | Zero (single adapters) | ✅ **70%+ reduction** |
-| **Files with Demo Conditionals** | 15+ files | 2 files (auth only) | ✅ **87% reduction** |
-| **Lines of Legacy Code** | ~400+ lines | 0 lines | ✅ **100% cleanup** |
-| **Build Success** | ✅ Clean | ✅ Clean | ✅ **Maintained** |
-| **Architecture Compliance** | 30% hexagonal | 100% hexagonal | ✅ **Enterprise-grade** |
-
-### **🏗️ Architecture Accomplishments**
-
-**Core Implementation:**
-1. ✅ **Hexagonal Architecture** - Complete ports & adapters pattern
-2. ✅ **Dependency Injection** - Full DI container with service locator
-3. ✅ **Domain-Driven Design** - Proper domain entities matching business needs
-4. ✅ **Environment Configuration** - Clean, centralized config management
-5. ✅ **Adapter Pattern** - Seamless demo ↔ production switching
-
-**Advanced Features:**
-1. 🚀 **Authentication Middleware** - `withAuth`/`withOptionalAuth` pattern
-2. 🚀 **Application Context** - Clean context passing for authenticated operations  
-3. 🚀 **Service Locator** - Type-safe service access throughout application
-4. 🚀 **Legacy Code Elimination** - Complete removal of technical debt
-5. 🚀 **Enterprise Patterns** - Production-ready architectural patterns
-
-### **🎯 Beyond Original Scope**
-
-**Major enhancements delivered:**
-- **Authentication Architecture Revolution** - Moved from scattered auth checks to clean middleware pattern
-- **Domain Entity Accuracy** - Fixed DDD implementation to match actual business needs
-- **Complete Legacy Cleanup** - Systematic removal of all obsolete conditional logic
-- **Build System Integrity** - Maintained clean TypeScript compilation throughout
-
-### **📋 Production Readiness Status**
-
-| Component | Status | Production Score | Notes |
-|-----------|---------|------------------|-------|
-| **Core Architecture** | ✅ **Production Ready** | 100% | Full hexagonal implementation |
-| **Database Layer (Turso)** | ✅ **Production Ready** | 100% | Real SQL queries, proper joins, full CRUD |
-| **Authentication** | ✅ **Production Ready** | 100% | NextAuth + database integration |
-| **Demo Mode** | ✅ **Production Ready** | 100% | Zero-config deployment verified |
-| **API Routes & Middleware** | ✅ **Production Ready** | 100% | All migrated to new auth pattern |
-| **UI Components** | ✅ **Production Ready** | 100% | Mode-agnostic, clean interfaces |
-| **Build System** | ✅ **Production Ready** | 100% | Clean TypeScript compilation |
-| **Documentation** | ✅ **Production Ready** | 100% | Architecture docs complete |
-| **GitHub API Integration** | ❌ **Demo Data Only** | 0% | Still using demo adapter wrapper |
-| **Webhook Processing** | ❌ **Demo Data Only** | 0% | No real GitHub webhook handling |
-| **Testing** | ⚠️ **Recommended** | 30% | Basic architecture, needs comprehensive tests |
-
-**🎯 Overall Production Score: 75%**
-
-### **🔍 What Works Today in Production**
-
-With proper environment variables configured:
-```bash
-# Required for production mode
-TURSO_URL=your-turso-database-url
-TURSO_TOKEN=your-turso-auth-token
-GITHUB_CLIENT_ID=your-github-oauth-app-id  
-GITHUB_CLIENT_SECRET=your-github-oauth-secret
-NEXTAUTH_SECRET=your-nextauth-secret-key
-```
-
-**✅ Fully Functional:**
-- User authentication & session management
-- Organization & team management  
-- Database persistence & queries
-- Dashboard analytics (with real stored data)
-- Clean architecture patterns
-- Mode-agnostic UI components
-
-**❌ Still Using Demo Data:**
-- Pull request data from GitHub
-- Repository information from GitHub
-- GitHub webhook processing
-- Real-time GitHub API synchronization
-
-### **🛠️ Critical Next Steps (Complete Production Readiness)**
-
-**Priority 1: Real GitHub API Integration** 🎯
-1. **Implement `RealGitHubAPIService`** - Replace demo wrapper with actual GitHub API calls
-   ```typescript
-   // lib/infrastructure/adapters/github/real-github.adapter.ts
-   export class RealGitHubAPIService implements IGitHubService {
-     private octokit: Octokit
-     
-     async getRepositoryPullRequests(owner: string, repo: string) {
-       const response = await this.octokit.pulls.list({
-         owner, repo, state: 'all', per_page: 100
-       })
-       return response.data.map(mapGitHubPRToDomain)
-     }
-     
-     async processWebhookEvent(event: string, payload: any) {
-       // Real webhook processing logic
-     }
-     // ... other real implementations
-   }
-   ```
-
-2. **Add Octokit Integration** - Install and configure GitHub API client
-3. **Map GitHub Data to Domain Entities** - Transform GitHub API responses to domain objects
-4. **Implement Real Webhook Processing** - Handle actual GitHub webhook events
-5. **Add GitHub App Authentication** - Use GitHub App credentials for API access
-
-**Priority 2: Production Hardening** 🔧
-1. **Unit Testing** - Add adapter-level unit tests for business logic validation
-2. **Integration Testing** - Add API route integration tests for contract verification  
-3. **Performance Testing** - Benchmark adapter performance under load
-4. **Monitoring** - Add observability for adapter switching and performance
-5. **Error Handling** - Robust error handling for GitHub API rate limits & failures
-
-**Priority 3: Optional Enhancements** 🚀
-1. **Additional Adapters** - PostgreSQL, Redis, or other data sources as needed
-2. **Caching Layer** - Add Redis caching for GitHub API responses
-3. **Background Jobs** - Queue system for webhook processing and data sync
-4. **Metrics & Monitoring** - Application performance monitoring and alerting
-
-### **📝 Deployment Guide**
-
-**To deploy 75% functional production app today:**
-1. Configure environment variables (Turso DB + GitHub OAuth)
-2. Deploy to your preferred platform (Vercel, Railway, etc.)  
-3. **Result**: Fully functional app with real auth, database, and demo data for GitHub features
-
-**To achieve 100% production readiness:**
-1. Complete steps above
-2. Implement `RealGitHubAPIService` (Priority 1 tasks)
-3. **Result**: Fully functional app with real GitHub data integration
-
-**Current Status: ✅ ARCHITECTURE REFACTORING COMPLETE + ⚠️ GITHUB API INTEGRATION NEEDED**
-- **All planned hexagonal architecture phases completed**
-- **Major authentication enhancements delivered beyond scope**  
-- **Zero technical debt remaining**
-- **75% production ready** - Database, auth, and architecture fully functional
-- **25% remaining** - Real GitHub API integration needed for 100% production readiness
-
-## Benefits After Refactoring ✅ **DELIVERED**
-
-1. **Single code path**: No more conditional logic scattered throughout
-2. **Easy testing**: Mock adapters for unit tests
-3. **Clear boundaries**: Business logic separated from infrastructure
-4. **Extensibility**: Easy to add new data sources (e.g., PostgreSQL, Redis)
-5. **Maintainability**: Changes to one adapter don't affect others
-6. **Type safety**: Interfaces ensure consistent contracts
-7. **Performance**: Can optimize each adapter independently
-8. **Developer experience**: Clear where to make changes
-
-## File Structure After Refactoring
-
-```
-lib/
-├── core/
-│   ├── domain/
-│   │   ├── entities/
-│   │   │   ├── pull-request.ts
-│   │   │   ├── organization.ts
-│   │   │   └── user.ts
-│   │   └── value-objects/
-│   │       ├── time-range.ts
-│   │       └── category.ts
-│   ├── ports/
-│   │   ├── repository.port.ts
-│   │   ├── metrics.port.ts
-│   │   ├── auth.port.ts
-│   │   └── github.port.ts
-│   ├── services/
-│   │   ├── metrics.service.ts
-│   │   ├── recommendation.service.ts
-│   │   └── team.service.ts
-│   └── container.ts
-├── infrastructure/
-│   ├── adapters/
-│   │   ├── demo/
-│   │   │   ├── pull-request.adapter.ts
-│   │   │   ├── metrics.adapter.ts
-│   │   │   ├── auth.adapter.ts
-│   │   │   └── data/
-│   │   │       └── demo-data.json
-│   │   ├── turso/
-│   │   │   ├── pull-request.adapter.ts
-│   │   │   ├── metrics.adapter.ts
-│   │   │   └── client.ts
-│   │   └── github/
-│   │       ├── auth.adapter.ts
-│   │       ├── api.adapter.ts
-│   │       └── client.ts
-│   └── config/
-│       ├── environment.ts
-│       └── container.config.ts
-└── shared/
-    ├── errors/
-    │   └── domain.errors.ts
-    └── utils/
-        └── date.utils.ts
-```
-
-## Success Metrics ✅ **ACHIEVED & EXCEEDED**
-
-**Target vs Actual Results:**
-- **Code duplication**: ✅ **Reduced by 70%+** (Single adapter pattern eliminated all demo vs prod duplication)
-- **Conditional statements**: ✅ **Reduced by 100%** (Zero demo conditionals in business logic - exceeded 90% target)
-- **Test coverage**: ⚠️ **Current state maintained** (Architecture supports 80%+ coverage with adapter mocking)
-- **API response time**: ✅ **Maintained** (Clean service locator pattern, no performance regression)  
-- **Development velocity**: ✅ **Increased 50%+** (Clear patterns, no more conditional debugging - exceeded 40% target)
-- **Bug reports**: ✅ **Reduced 80%+** (Eliminated entire class of demo mode bugs - exceeded 60% target)
-
-**Additional Unexpected Gains:**
-- **Technical Debt**: ✅ **Eliminated 100%** (Complete legacy code cleanup)
-- **Architecture Compliance**: ✅ **100% Hexagonal** (Enterprise-grade patterns)  
-- **Type Safety**: ✅ **100% Coverage** (Full TypeScript interface contracts)
-- **Authentication Quality**: ✅ **Production-grade** (Clean middleware architecture)
-- **Documentation**: ✅ **Complete** (Living architecture documentation)
-
-## Risks and Mitigations ✅ **SUCCESSFULLY MITIGATED**
-
-| Risk | Original Mitigation | Actual Outcome |
-|------|---------------------|----------------|
-| Large refactoring breaking existing features | Incremental migration with feature flags | ✅ **No breaking changes** - Clean build maintained throughout |
-| Team learning curve for new architecture | Documentation and pair programming sessions | ✅ **Well-documented** - Clear patterns with comprehensive docs |
-| Performance regression | Benchmark before and after each phase | ✅ **No regression** - Clean service locator pattern maintains performance |
-| Increased initial complexity | Clear documentation and examples | ✅ **Reduced complexity** - Single-path execution simpler than conditionals |
-
-## Next Steps ✅ **ORIGINAL PLAN COMPLETED**
-
-**✅ Completed Steps:**
-1. ~~Review and approve this plan with the team~~ - **COMPLETED**: Plan executed successfully
-2. ~~Set up feature flags for gradual rollout~~ - **NOT NEEDED**: Clean incremental migration achieved  
-3. ~~Create a new branch for refactoring~~ - **COMPLETED**: All changes integrated to main
-4. ~~Start with Phase 1: Port interfaces~~ - **COMPLETED**: All 7 phases completed
-5. ~~Daily progress reviews and adjustments~~ - **COMPLETED**: Iterative development successful
-
-**🚀 Recommended Next Steps (Optional Enhancements):**
-1. **Production Hardening**: Add comprehensive unit/integration test suite
-2. **Performance Optimization**: Benchmark and optimize adapter performance 
-3. **Monitoring**: Add observability for service switching and performance metrics
-4. **Scaling**: Add additional adapters (PostgreSQL, Redis, etc.) as needed
-5. **Documentation**: Create developer onboarding guide for the new architecture
-
-## Conclusion ✅ **MISSION ACCOMPLISHED**
-
-**✅ TRANSFORMATION COMPLETE**: This refactoring **successfully transformed** the codebase from a conditional-heavy, tightly-coupled system to a **clean, enterprise-grade hexagonal architecture**. The investment in proper architecture has **delivered measurable dividends**:
-
-**🎯 Achieved Benefits:**
-- ✅ **Faster feature development** - 50%+ velocity increase through clear patterns
-- ✅ **Fewer bugs** - 80%+ reduction by eliminating conditional logic bugs  
-- ✅ **Easier onboarding** - Clean architecture with comprehensive documentation
-- ✅ **Better testability** - Mock adapters enable isolated unit testing
-- ✅ **Clearer code ownership** - Well-defined boundaries and responsibilities
-
-**🚀 Beyond Original Goals:**
-- ✅ **Enterprise-grade authentication architecture** with middleware patterns
-- ✅ **100% legacy code elimination** - Complete technical debt cleanup  
-- ✅ **Domain-driven design accuracy** - Entities match business requirements
-- ✅ **Zero breaking changes** - Seamless migration without disruption
-- ✅ **Production-ready architecture** - Ready for enterprise deployment
-
-**🎯 Core Principle Achieved:** 
-> **"Write code once, run it everywhere with different adapters."**
-
-**Final Status: ✅ ARCHITECTURE REFACTORING COMPLETE**
-- **All hexagonal architecture objectives achieved and exceeded**  
-- **Zero technical debt remaining**
-- **75% production deployment ready** (Database + Auth + Architecture)
-- **Enterprise architecture standards met**
-- **Next milestone: Complete GitHub API integration for 100% production readiness**
-
----
-
-*This document serves as both the original plan and the final completion report for the Hexagonal Architecture refactoring initiative.*

ENVIRONMENT_SETUP.md

···
 - **Authorization callback URL**: `https://prcat.vercel.app/api/auth/callback/github`
 
 After creation, you'll get:
-- `Client ID` → Use as `GITHUB_CLIENT_ID`
-- Generate a `Client Secret` → Use as `GITHUB_CLIENT_SECRET`
+- `Client ID` → Use as `GITHUB_OAUTH_CLIENT_ID`
+- Generate a `Client Secret` → Use as `GITHUB_OAUTH_CLIENT_SECRET`
 
 ### 2. Create a GitHub App
 
···
 NEXTAUTH_URL=               # http://localhost:3000 (local) or https://prcat.vercel.app (production)
 
 # GitHub OAuth App (for user authentication)
-GITHUB_CLIENT_ID=           # From OAuth App
-GITHUB_CLIENT_SECRET=       # From OAuth App
+GITHUB_OAUTH_CLIENT_ID=           # From OAuth App
+GITHUB_OAUTH_CLIENT_SECRET=       # From OAuth App
 
 # GitHub App (for repository access)
 GITHUB_APP_ID=              # Numeric ID from GitHub App
···
 APP_URL=http://localhost:3000
 
 # From your local GitHub OAuth App
-GITHUB_CLIENT_ID=your-oauth-client-id
-GITHUB_CLIENT_SECRET=your-oauth-client-secret
+GITHUB_OAUTH_CLIENT_ID=your-oauth-client-id
+GITHUB_OAUTH_CLIENT_SECRET=your-oauth-client-secret
 
 # From your GitHub App
 GITHUB_APP_ID=123456
···
 **Cause**: Mismatched OAuth callback URL
 **Solution**: 
 - Verify the callback URL in your GitHub OAuth App matches exactly: `${NEXTAUTH_URL}/api/auth/callback/github`
-- Check that you're using the correct `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` pair
+- Check that you're using the correct `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET` pair
 
 #### 2. Organizations Not Appearing
 **Cause**: Organizations not synced to database

README.md

···
 **Required:** **Nothing!** All secrets auto-generated securely 🎉
 
 ### Option 2: Basic Mode (5 minutes setup)
-[![Deploy Basic](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,NEXTAUTH_SECRET&envDescription=Basic%20GitHub%20integration&envLink=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat%23environment-setup&project-name=pr-cat-basic&repository-name=pr-cat)
+[![Deploy Basic](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET,NEXTAUTH_SECRET&envDescription=Basic%20GitHub%20integration&envLink=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat%23environment-setup&project-name=pr-cat-basic&repository-name=pr-cat)
 
 **What you get:**
 - ✅ GitHub OAuth authentication
···
 **Required:** 3 environment variables (GitHub OAuth + NextAuth secret)
 
 ### Option 3: Full Installation (15 minutes setup)
-[![Deploy Full](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,GITHUB_WEBHOOK_SECRET,GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY,NEXT_PUBLIC_GITHUB_APP_SLUG,TURSO_URL,TURSO_TOKEN,NEXTAUTH_SECRET&envDescription=Complete%20setup%20with%20all%20features&envLink=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat%23environment-setup&project-name=pr-cat&repository-name=pr-cat)
+[![Deploy Full](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET,GITHUB_WEBHOOK_SECRET,GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY,NEXT_PUBLIC_GITHUB_APP_SLUG,TURSO_URL,TURSO_TOKEN,NEXTAUTH_SECRET&envDescription=Complete%20setup%20with%20all%20features&envLink=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat%23environment-setup&project-name=pr-cat&repository-name=pr-cat)
 
 **What you get:**
 - ✅ All features enabled
···
 
 ```bash
 # GitHub OAuth Configuration (Required)
-GITHUB_CLIENT_ID=your_github_client_id
-GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_OAUTH_CLIENT_ID=your_github_client_id
+GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret
 GITHUB_WEBHOOK_SECRET=your_github_webhook_secret
 
 # GitHub App Configuration (Required for advanced features)

VERCEL_TEMPLATE_ISSUES.md

···
 **Problem**: The Vercel deploy button requires **12 environment variables** upfront.
 **Impact**: This is overwhelming and creates a high barrier to entry.
 **Current Requirements**:
-- GITHUB_CLIENT_ID
-- GITHUB_CLIENT_SECRET
+- GITHUB_OAUTH_CLIENT_ID
+- GITHUB_OAUTH_CLIENT_SECRET
 - GITHUB_WEBHOOK_SECRET
 - GITHUB_APP_ID
 - GITHUB_APP_PRIVATE_KEY
···
 
 #### Minimal Deploy Button (3-4 variables only):
 ```markdown
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,NEXTAUTH_SECRET&envDescription=Minimal%20setup%20for%20PR%20Cat&project-name=pr-cat&demo=1)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvorcigernix%2Fpr_cat&env=GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET,NEXTAUTH_SECRET&envDescription=Minimal%20setup%20for%20PR%20Cat&project-name=pr-cat&demo=1)
 ```
 
 #### Progressive Enhancement Strategy:
···
   "env": {
     "required": ["NEXTAUTH_SECRET"],
     "optional": [
-      "GITHUB_CLIENT_ID",
-      "GITHUB_CLIENT_SECRET",
+      "GITHUB_OAUTH_CLIENT_ID",
+      "GITHUB_OAUTH_CLIENT_SECRET",
       "TURSO_URL",
       "TURSO_TOKEN"
     ]

app/api/demo-status/route.ts

···
     const missingServices = [];
     const hasDatabase = environmentConfig.hasFeature('database');
     const hasGitHub = environmentConfig.hasFeature('github');
-    const hasGitHubAuth = Boolean(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET);
+    const hasGitHubAuth = Boolean(process.env.GITHUB_OAUTH_CLIENT_ID && process.env.GITHUB_OAUTH_CLIENT_SECRET);
     
     if (!hasDatabase) missingServices.push('Database (Turso)');
     if (!hasGitHub) missingServices.push('GitHub App');

app/api/github-app/installations/[installationId]/route.ts

···
+/**
+ * GitHub App Installation Management API
+ * Manages individual GitHub App installations
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { auth } from '@/auth'
+import { getService } from '@/lib/core/container/di-container'
+import { IGitHubAppService } from '@/lib/core/ports'
+
+export const runtime = 'nodejs'
+
+/**
+ * GET /api/github-app/installations/[installationId]
+ * Get details for a specific installation
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ installationId: string }> }
+) {
+  try {
+    const { installationId } = await params
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const installationIdNum = parseInt(installationId)
+    if (isNaN(installationIdNum)) {
+      return NextResponse.json({ error: 'Invalid installation ID' }, { status: 400 })
+    }
+
+    console.log(`[GitHubApp API] Fetching installation ${installationIdNum}...`)
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Get installation details
+    const installation = await githubAppService.getInstallation(installationIdNum)
+    
+    // Get repositories if requested
+    const includeRepos = request.nextUrl.searchParams.get('include_repositories') === 'true'
+    let repositories: any[] | undefined = undefined
+    
+    if (includeRepos) {
+      try {
+        repositories = await githubAppService.getInstallationRepositories(installationIdNum)
+        console.log(`[GitHubApp API] Found ${repositories.length} repositories for installation ${installationIdNum}`)
+      } catch (error) {
+        console.warn(`[GitHubApp API] Could not fetch repositories for installation ${installationIdNum}:`, error)
+        repositories = undefined
+      }
+    }
+
+    return NextResponse.json({
+      installation,
+      repositories,
+      repositoryCount: repositories?.length
+    })
+
+  } catch (error) {
+    console.error(`[GitHubApp API] Error fetching installation:`, error)
+    
+    if (error instanceof Error && error.message.includes('Not Found')) {
+      return NextResponse.json({ error: 'Installation not found' }, { status: 404 })
+    }
+    
+    return NextResponse.json(
+      { 
+        error: 'Failed to fetch installation',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}
+
+/**
+ * POST /api/github-app/installations/[installationId]/sync
+ * Sync a specific installation with database
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ installationId: string }> }
+) {
+  try {
+    const { installationId } = await params
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const installationIdNum = parseInt(installationId)
+    if (isNaN(installationIdNum)) {
+      return NextResponse.json({ error: 'Invalid installation ID' }, { status: 400 })
+    }
+
+    console.log(`[GitHubApp API] Syncing installation ${installationIdNum}...`)
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Sync the installation
+    const syncResult = await githubAppService.syncInstallation(installationIdNum)
+
+    console.log(`[GitHubApp API] Sync completed for installation ${installationIdNum}: org=${syncResult.organization.name}, repos=${syncResult.repositories.length}, errors=${syncResult.errors.length}`)
+
+    return NextResponse.json({
+      success: true,
+      organization: {
+        id: syncResult.organization.id,
+        name: syncResult.organization.name,
+        login: syncResult.organization.login
+      },
+      repositories: {
+        count: syncResult.repositories.length,
+        items: syncResult.repositories.map(repo => ({
+          id: repo.id,
+          name: repo.name,
+          fullName: repo.fullName,
+          isPrivate: repo.isPrivate
+        }))
+      },
+      errors: syncResult.errors.length > 0 ? syncResult.errors : undefined
+    })
+
+  } catch (error) {
+    console.error(`[GitHubApp API] Error syncing installation:`, error)
+    
+    if (error instanceof Error && error.message.includes('Not Found')) {
+      return NextResponse.json({ error: 'Installation not found' }, { status: 404 })
+    }
+    
+    return NextResponse.json(
+      { 
+        error: 'Failed to sync installation',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}
+
+/**
+ * DELETE /api/github-app/installations/[installationId]/cache
+ * Clear cached tokens for an installation
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ installationId: string }> }
+) {
+  try {
+    const { installationId } = await params
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const installationIdNum = parseInt(installationId)
+    if (isNaN(installationIdNum)) {
+      return NextResponse.json({ error: 'Invalid installation ID' }, { status: 400 })
+    }
+
+    console.log(`[GitHubApp API] Clearing token cache for installation ${installationIdNum}...`)
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Clear the token cache
+    await githubAppService.clearTokenCache(installationIdNum)
+
+    return NextResponse.json({
+      success: true,
+      message: `Token cache cleared for installation ${installationIdNum}`
+    })
+
+  } catch (error) {
+    console.error(`[GitHubApp API] Error clearing token cache:`, error)
+    return NextResponse.json(
+      { 
+        error: 'Failed to clear token cache',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}

app/api/github-app/installations/route.ts

···
+/**
+ * GitHub App Installations API
+ * Lists and manages GitHub App installations
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { auth } from '@/auth'
+import { getService } from '@/lib/core/container/di-container'
+import { IGitHubAppService } from '@/lib/core/ports'
+
+export const runtime = 'nodejs'
+
+/**
+ * GET /api/github-app/installations
+ * List all GitHub App installations
+ */
+export async function GET() {
+  try {
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    console.log('[GitHubApp API] Fetching installations...')
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Validate GitHub App configuration first
+    const config = await githubAppService.validateConfiguration()
+    if (!config.isValid) {
+      console.warn('[GitHubApp API] GitHub App not properly configured:', config.errors)
+      return NextResponse.json({
+        installations: [],
+        configured: false,
+        errors: config.errors
+      })
+    }
+
+    // Get all installations
+    const installations = await githubAppService.listInstallations()
+    
+    // Filter to only organizations (if needed)
+    const organizationInstallations = installations.filter(
+      installation => installation.account.type === 'Organization'
+    )
+
+    console.log(`[GitHubApp API] Found ${organizationInstallations.length} organization installations`)
+
+    return NextResponse.json({
+      installations: organizationInstallations,
+      configured: true,
+      total: organizationInstallations.length
+    })
+
+  } catch (error) {
+    console.error('[GitHubApp API] Error fetching installations:', error)
+    return NextResponse.json(
+      { 
+        error: 'Failed to fetch installations',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}
+
+/**
+ * POST /api/github-app/installations
+ * Sync all installations with database
+ */
+export async function POST() {
+  try {
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    console.log('[GitHubApp API] Starting installation sync...')
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Validate configuration
+    const config = await githubAppService.validateConfiguration()
+    if (!config.isValid) {
+      return NextResponse.json({
+        error: 'GitHub App not properly configured',
+        details: config.errors
+      }, { status: 400 })
+    }
+
+    // Get all installations
+    const installations = await githubAppService.listInstallations()
+    const organizationInstallations = installations.filter(
+      installation => installation.account.type === 'Organization'
+    )
+
+    // Sync each installation
+    const results = []
+    const errors = []
+
+    for (const installation of organizationInstallations) {
+      try {
+        console.log(`[GitHubApp API] Syncing installation ${installation.id} for org ${installation.account.login}`)
+        
+        const syncResult = await githubAppService.syncInstallation(installation.id)
+        results.push({
+          installationId: installation.id,
+          organization: syncResult.organization.name,
+          repositoriesCount: syncResult.repositories.length,
+          errors: syncResult.errors
+        })
+        
+        if (syncResult.errors.length > 0) {
+          errors.push(...syncResult.errors)
+        }
+      } catch (error) {
+        const errorMsg = `Failed to sync installation ${installation.id}: ${error instanceof Error ? error.message : 'Unknown error'}`
+        errors.push(errorMsg)
+        console.error(`[GitHubApp API] ${errorMsg}`)
+      }
+    }
+
+    console.log(`[GitHubApp API] Sync completed. Processed ${results.length} installations, ${errors.length} errors`)
+
+    return NextResponse.json({
+      success: true,
+      synced: results,
+      totalInstallations: organizationInstallations.length,
+      totalErrors: errors.length,
+      errors: errors.length > 0 ? errors : undefined
+    })
+
+  } catch (error) {
+    console.error('[GitHubApp API] Error syncing installations:', error)
+    return NextResponse.json(
+      { 
+        error: 'Failed to sync installations',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}

app/api/github-app/status/route.ts

···
+/**
+ * GitHub App Status API
+ * Provides configuration and status information for GitHub App
+ */
+
+import { NextResponse } from 'next/server'
+import { auth } from '@/auth'
+import { getService } from '@/lib/core/container/di-container'
+import { IGitHubAppService } from '@/lib/core/ports'
+
+export const runtime = 'nodejs'
+
+/**
+ * GET /api/github-app/status
+ * Get GitHub App configuration and status
+ */
+export async function GET() {
+  try {
+    const session = await auth()
+    
+    if (!session || !session.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    console.log('[GitHubApp API] Checking GitHub App status...')
+
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
+    
+    // Validate configuration
+    const config = await githubAppService.validateConfiguration()
+    
+    let installationCount = 0
+    let organizationCount = 0
+    let lastError = null
+
+    // If configured, get installation info
+    if (config.isValid) {
+      try {
+        const installations = await githubAppService.listInstallations()
+        installationCount = installations.length
+        organizationCount = installations.filter(
+          inst => inst.account.type === 'Organization'
+        ).length
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : 'Failed to fetch installations'
+        console.warn('[GitHubApp API] Error fetching installations for status:', error)
+      }
+    }
+
+    const status = {
+      configured: config.isValid,
+      appId: config.appId,
+      hasPrivateKey: config.hasPrivateKey,
+      errors: config.errors.length > 0 ? config.errors : undefined,
+      installations: {
+        total: installationCount,
+        organizations: organizationCount
+      },
+      lastError: lastError || undefined,
+      environment: {
+        hasAppId: !!process.env.GITHUB_APP_ID,
+        hasPrivateKey: !!process.env.GITHUB_APP_PRIVATE_KEY,
+        hasWebhookSecret: !!process.env.GITHUB_WEBHOOK_SECRET,
+        hasClientId: !!process.env.GITHUB_OAUTH_CLIENT_ID,
+        hasClientSecret: !!process.env.GITHUB_OAUTH_CLIENT_SECRET
+      },
+      requiredEnvVars: [
+        'GITHUB_APP_ID',
+        'GITHUB_APP_PRIVATE_KEY'
+      ],
+      optionalEnvVars: [
+        'GITHUB_WEBHOOK_SECRET',
+        'GITHUB_OAUTH_CLIENT_ID', 
+        'GITHUB_OAUTH_CLIENT_SECRET'
+      ]
+    }
+
+    console.log(`[GitHubApp API] Status check complete: configured=${config.isValid}, installations=${installationCount}`)
+
+    return NextResponse.json(status)
+
+  } catch (error) {
+    console.error('[GitHubApp API] Error checking GitHub App status:', error)
+    return NextResponse.json(
+      { 
+        error: 'Failed to check GitHub App status',
+        details: error instanceof Error ? error.message : 'Unknown error'
+      }, 
+      { status: 500 }
+    )
+  }
+}

app/api/github/organizations/[orgName]/repositories/route.ts

···
 import { NextRequest, NextResponse } from 'next/server';
 import { auth } from '@/auth';
-import { GitHubService } from '@/lib/services';
+import { getService } from '@/lib/core/container/di-container';
+import { IGitHubService } from '@/lib/core/ports';
 
 // Use the context object directly with proper typing for Next.js route handler
 export async function GET(
···
   }
   
   try {
-    const githubService = new GitHubService(session.accessToken);
-    const repositories = await githubService.syncOrganizationRepositories(orgName);
+    const githubService = await getService<IGitHubService>('GitHubService');
+    const result = await githubService.syncOrganizationRepositories(orgName);
     
-    return NextResponse.json({ repositories });
+    return NextResponse.json({ 
+      repositories: result.synced,
+      errors: result.errors 
+    });
   } catch (error) {
     console.error('GitHub API error:', error);
     return NextResponse.json(

app/api/github/organizations/installation-status/route.ts

···
 import { NextRequest, NextResponse } from 'next/server';
 import { auth } from '@/auth';
-import { GitHubClient } from '@/lib/github';
-import { generateAppJwt } from '@/lib/github-app';
-import { Octokit } from '@octokit/rest';
+import { getService } from '@/lib/core/container/di-container';
+import { IGitHubAppService } from '@/lib/core/ports';
 
 export const runtime = 'nodejs';
 
···
       return NextResponse.json({ installations: [] });
     }
     
-    // For GitHub App installation status, we need to use the GitHub App JWT
-    // because the user OAuth token doesn't have permission to list installations
-    console.log('Organizations installation-status: Generating GitHub App JWT');
-    const appJwt = await generateAppJwt();
-    const appOctokit = new Octokit({ auth: appJwt });
+    // Get GitHub App service
+    const githubAppService = await getService<IGitHubAppService>('GitHubAppService');
+    
+    // Validate GitHub App configuration
+    const config = await githubAppService.validateConfiguration();
+    if (!config.isValid) {
+      console.log('Organizations installation-status: GitHub App not properly configured');
+      return NextResponse.json({ 
+        installations: [],
+        configured: false,
+        errors: config.errors
+      });
+    }
     
     // Get all app installations
     console.log('Organizations installation-status: Fetching app installations');
-    const { data: installationsData } = await appOctokit.apps.listInstallations();
+    const installationsData = await githubAppService.listInstallations();
     console.log(`Organizations installation-status: Found ${installationsData.length} app installations`);
     
     // Map organizations to include installation status

app/api/github/organizations/route.ts

···
 import { NextResponse } from 'next/server';
 import { auth } from '@/auth';
-import { GitHubService } from '@/lib/services';
+import { getService } from '@/lib/core/container/di-container';
+import { IGitHubService } from '@/lib/core/ports';
 
 export async function GET() {
   const session = await auth();
···
   }
   
   try {
-    const githubService = new GitHubService(session.accessToken);
-    const organizations = await githubService.syncUserOrganizations(session.user.id);
+    const githubService = await getService<IGitHubService>('GitHubService');
+    const organizations = await githubService.getUserOrganizations(session.accessToken);
     
     return NextResponse.json({ organizations });
   } catch (error) {

app/api/github/user/route.ts

···
 import { NextResponse } from 'next/server';
 import { auth } from '@/auth';
-import { GitHubService } from '@/lib/services';
+import { getService } from '@/lib/core/container/di-container';
+import { IGitHubService } from '@/lib/core/ports';
 
 export async function GET() {
   const session = await auth();
···
   }
   
   try {
-    const githubService = new GitHubService(session.accessToken);
-    const user = await githubService.getCurrentUser();
+    const githubService = await getService<IGitHubService>('GitHubService');
+    const user = await githubService.getUser(session.accessToken);
     
     return NextResponse.json({ user });
   } catch (error) {

app/api/health/route.ts

···
       // Don't expose actual env vars, just check if they exist
       envVarsConfigured: {
         turso: !!process.env.TURSO_URL && !!process.env.TURSO_TOKEN,
-        github: !!process.env.GITHUB_CLIENT_ID && !!process.env.GITHUB_CLIENT_SECRET,
+        github: !!process.env.GITHUB_OAUTH_CLIENT_ID && !!process.env.GITHUB_OAUTH_CLIENT_SECRET,
         nextauth: !!process.env.NEXTAUTH_SECRET,
       }
     };

app/api/webhook/github/route.ts

···
-import { NextRequest, NextResponse } from 'next/server';
-import crypto from 'crypto';
-import { findRepositoryByFullName } from '@/lib/repositories';
-import { findOrCreateRepository } from '@/lib/repositories';
-import { 
-  createPullRequest, 
-  findPullRequestByNumber, 
-  updatePullRequest,
-  createPullRequestReview,
-  findReviewByGitHubId,
-  updatePullRequestReview,
-  updatePullRequestCategory,
-  getOrganizationCategories,
-  getOrganizationAiSettings,
-  getOrganizationApiKey,
-  findCategoryByNameAndOrg as findCategoryByNameAndOrgFromRepo,
-  findOrCreateUserByGitHubId,
-  findOrganizationById
-} from '@/lib/repositories';
-import { findOrganizationByNameAndUser } from '@/lib/repositories/organization-repository';
-import { GitHubClient } from '@/lib/github';
-import { createInstallationClient } from '@/lib/github-app';
-import { PRReview, Category, Organization } from '@/lib/types';
-import { openai } from '@ai-sdk/openai';
-import { generateText, CoreTool } from 'ai';
-import { createOpenAI } from '@ai-sdk/openai';
-import { createGoogleGenerativeAI } from '@ai-sdk/google';
-import { createAnthropic } from '@ai-sdk/anthropic';
-import { allModels } from '@/lib/ai-models'; // Import shared models
-import * as OrganizationRepository from '@/lib/repositories/organization-repository';
-import { Octokit } from '@octokit/rest';
-import * as PullRequestRepository from '@/lib/repositories/pr-repository';
-import * as UserRepository from '@/lib/repositories/user-repository';
-import { User } from '@/lib/types';
-
-export const runtime = 'nodejs';
-
-// Helper to log operations that might involve foreign keys
-function logOperation(operation: string, params: any) {
-  console.log(`WEBHOOK DB OPERATION: ${operation}`, JSON.stringify(params, null, 2));
-}
-
-// Verify GitHub webhook signature
-function verifyGitHubSignature(payload: string, signature: string, secret: string): boolean {
-  if (!signature || !secret) {
-    return false;
-  }
-  
-  const expectedSignature = crypto
-    .createHmac('sha256', secret)
-    .update(payload, 'utf8')
-    .digest('hex');
-  
-  const expectedSignatureWithPrefix = `sha256=${expectedSignature}`;
-  
-  // Use crypto.timingSafeEqual to prevent timing attacks
-  if (signature.length !== expectedSignatureWithPrefix.length) {
-    return false;
-  }
-  
-  return crypto.timingSafeEqual(
-    Buffer.from(signature, 'utf8'),
-    Buffer.from(expectedSignatureWithPrefix, 'utf8')
-  );
-}
+/**
+ * GitHub Webhook Handler
+ * Processes GitHub webhook events using hexagonal architecture
+ */
 
-// Helper to safely log errors with full stack trace and context
-function logError(context: string, error: any, extraData?: any) {
-  console.error(`WEBHOOK ERROR in ${context}:`, error);
-  if (error instanceof Error) {
-    console.error(`  Message: ${error.message}`);
-    console.error(`  Stack: ${error.stack}`);
-  }
-  if (extraData) {
-    console.error(`  Context data:`, JSON.stringify(extraData, null, 2));
-  }
-}
+import { NextRequest, NextResponse } from 'next/server'
+import { validateWebhook } from '@/lib/webhook-security'
+import { getService } from '@/lib/core/container/di-container'
+import { IGitHubService } from '@/lib/core/ports'
 
-// GitHub webhook payload types
-interface GitHubWebhookPayload {
-  action: string;
-  installation?: {
-    id: number;
-    // Add account details for installation events
-    account?: {
-      id: number;
-      login: string;
-      type: string; // "Organization" or "User"
-      avatar_url?: string;
-    };
-  };
-  repository: {
-    id: number;
-    name: string;
-    full_name: string;
-    owner: {
-      id: number;
-      login: string;
-    };
-    installation?: {
-      id: number;
-    };
-  };
-  sender: {
-    id: number;
-    login: string;
-  };
-}
-
-interface PullRequestPayload extends GitHubWebhookPayload {
-  pull_request: {
-    id: number;
-    number: number;
-    title: string;
-    body: string | null;
-    state: string;
-    created_at: string;
-    updated_at: string;
-    closed_at: string | null;
-    merged_at: string | null;
-    draft: boolean;
-    user: {
-      id: number;
-      login: string;
-    };
-    additions?: number;
-    deletions?: number;
-    changed_files?: number;
-  };
-}
-
-interface PullRequestReviewPayload extends GitHubWebhookPayload {
-  pull_request: {
-    id: number;
-    number: number;
-    title: string;
-  };
-  review: {
-    id: number;
-    user: {
-      id: number;
-      login: string;
-    };
-    body: string | null;
-    state: string;
-    submitted_at: string;
-    commit_id: string;
-  };
-}
-
-// Interface for Installation event payload
-interface InstallationPayload extends GitHubWebhookPayload {
-  action: 'created' | 'deleted' | 'suspend' | 'unsuspend' | 'new_permissions_accepted';
-  installation: {
-    id: number;
-    account: {
-      id: number; // This is the GitHub ID of the organization or user
-      login: string;
-      type: string; // "Organization" or "User"
-      avatar_url?: string;
-      // ... other account details if needed
-    };
-    // ... other installation details if needed
-  };
-  // repositories field might be present if action is 'created' and it's a selective installation
-  repositories?: Array<{
-    id: number;
-    name: string;
-    full_name: string;
-    private: boolean;
-  }>;
-}
+export const runtime = 'nodejs'
 
 export async function POST(request: NextRequest) {
-  console.log("WEBHOOK: Received GitHub webhook event");
+  console.log('[Webhook] Received GitHub webhook event')
   
   try {
-    // Get headers first
-    const signature = request.headers.get('x-hub-signature-256');
-    const webhookSecret = process.env.GITHUB_WEBHOOK_SECRET ?? process.env.GITHUB_CLIENT_SECRET;
-    const eventType = request.headers.get('x-github-event');
-    
-    console.log(`Received GitHub webhook event type: ${eventType}`);
-    
-    // Read the body as text first (for signature verification)
-    const bodyText = await request.text();
+    // Get webhook secret from environment
+    const webhookSecret = process.env.GITHUB_WEBHOOK_SECRET ?? process.env.GITHUB_OAUTH_CLIENT_SECRET
     
-    // Verify webhook signature for security
     if (!webhookSecret) {
-      if (process.env.NODE_ENV !== 'production') {
-        console.warn("WEBHOOK: GITHUB_WEBHOOK_SECRET not configured - skipping signature verification in non-production environment");
+      if (process.env.NODE_ENV === 'production') {
+        console.error('[Webhook] GITHUB_WEBHOOK_SECRET not configured in production')
+        return NextResponse.json(
+          { error: 'Webhook secret not configured' }, 
+          { status: 500 }
+        )
       } else {
-        console.error("WEBHOOK: GITHUB_WEBHOOK_SECRET not configured");
-        return NextResponse.json({ error: 'Webhook secret not configured' }, { status: 500 });
-      }
-    }
-    
-    if (!signature && webhookSecret) {
-      console.error("WEBHOOK: Missing X-Hub-Signature-256 header");
-      return NextResponse.json({ error: 'Missing signature' }, { status: 401 });
-    }
-    
-    if (webhookSecret && signature && !verifyGitHubSignature(bodyText, signature, webhookSecret)) {
-      console.error("WEBHOOK: Invalid signature");
-      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
-    }
-    
-    console.log("WEBHOOK: Signature verified successfully");
-    
-    let bodyJson;
-    
-    try {
-      bodyJson = JSON.parse(bodyText);
-      
-      // Log installation data from the webhook payload
-      console.log("WEBHOOK: Full installation data in payload:", 
-                 JSON.stringify(bodyJson.installation, null, 2));
-      console.log("WEBHOOK: Repository installation data:", 
-                 JSON.stringify(bodyJson.repository?.installation, null, 2));
-      
-      // Log event type
-      console.log(`WEBHOOK: Event type ${bodyJson.action} on ${bodyJson.repository?.full_name}`);
-    } catch (parseError) {
-      console.error("WEBHOOK: Error parsing webhook body as JSON:", parseError);
-      return NextResponse.json({ error: 'Invalid JSON payload' }, { status: 400 });
-    }
-    
-    if (webhookSecret && signature) {
-      const hmac = crypto.createHmac('sha256', webhookSecret);
-      const digest = 'sha256=' + hmac.update(bodyText).digest('hex');
-      
-      if (signature !== digest) {
-        console.warn('GitHub webhook signature verification failed');
-        return NextResponse.json({ error: 'Invalid signature' }, { status: 403 });
-      }
-      
-      return handleWebhookEvent(bodyJson, eventType || 'unknown');
-    } else {
-      // If no secret is configured (dev) or GitHub didn't send a signature, process without verification
-      return handleWebhookEvent(bodyJson, eventType || 'unknown');
-    }
-  } catch (error) {
-    console.error('Error handling webhook:', error);
-    return NextResponse.json(
-      { error: `Failed to process webhook: ${error instanceof Error ? error.message : 'Unknown error'}` }, 
-      { status: 500 }
-    );
-  }
-}
-
-async function handleWebhookEvent(payload: any, eventType: string) {
-  const action = payload.action;
-  
-  console.log(`Processing GitHub webhook event: ${eventType}.${action}`);
-  
-  try {
-    switch (eventType) {
-      case 'pull_request':
-        await handlePullRequestEvent(payload as PullRequestPayload);
-        break;
-      case 'pull_request_review':
-        await handlePullRequestReviewEvent(payload as PullRequestReviewPayload);
-        break;
-      case 'installation': // Add new case for installation events
-        await handleInstallationEvent(payload as InstallationPayload);
-        break;
-      case 'ping':
-        // This is a test ping from GitHub when setting up the webhook
-        console.log('Received ping from GitHub webhook configuration');
-        break;
-      default:
-        console.log(`Unhandled event type: ${eventType}`);
-    }
-    
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    console.error('Error handling webhook:', error);
-    return NextResponse.json(
-      { error: `Failed to process webhook: ${error instanceof Error ? error.message : 'Unknown error'}` }, 
-      { status: 500 }
-    );
-  }
-}
-
-async function handlePullRequestEvent(payload: PullRequestPayload) {
-  const { action, repository, pull_request: pr } = payload;
-  
-  console.log(`WEBHOOK PROCESSING: PR #${pr.number} action=${action} repo=${repository.full_name}`);
-  
-  try {
-    // Find or create the repository in our database
-    const repoInDb = await findRepositoryByFullName(repository.full_name);
-    
-    console.log(`WEBHOOK REPOSITORY CHECK: ${repository.full_name} found in DB? ${!!repoInDb}`, 
-                repoInDb ? `id=${repoInDb.id}, org_id=${repoInDb.organization_id}` : "NOT FOUND");
-    
-    if (!repoInDb) {
-      console.log(`Repository ${repository.full_name} not found in database, skipping webhook processing`);
-      return;
-    }
-    
-    // Map GitHub PR state to our state format
-    const prState = pr.merged_at 
-      ? 'merged' 
-      : pr.state === 'closed' ? 'closed' : 'open';
-    
-    // Check if PR already exists in our database
-    const existingPR = await findPullRequestByNumber(repoInDb.id, pr.number);
-    
-    console.log(`WEBHOOK PR CHECK: PR #${pr.number} in repo ${repository.full_name} exists in DB? ${!!existingPR}`,
-                existingPR ? `id=${existingPR.id}, author_id=${existingPR.author_id}` : "NOT FOUND");
-    
-    if (existingPR) {
-      // Update existing PR
-      const updateParams = {
-        id: existingPR.id,
-        title: pr.title,
-        description: pr.body,
-        state: prState,
-        updated_at: pr.updated_at,
-        closed_at: pr.closed_at,
-        merged_at: pr.merged_at,
-        draft: pr.draft,
-        additions: pr.additions,
-        deletions: pr.deletions,
-        changed_files: pr.changed_files
-      };
-      
-      logOperation("updatePullRequest", updateParams);
-      
-      try {
-        await updatePullRequest(existingPR.id, {
-          title: pr.title,
-          description: pr.body,
-          state: prState,
-          updated_at: pr.updated_at,
-          closed_at: pr.closed_at,
-          merged_at: pr.merged_at,
-          draft: pr.draft,
-          additions: pr.additions,
-          deletions: pr.deletions,
-          changed_files: pr.changed_files
-        });
-        
-        console.log(`WEBHOOK PR UPDATED: PR #${pr.number} in ${repository.full_name}`);
-        
-      } catch (updateError) {
-        logError("updatePullRequest", updateError, { 
-          pr_id: existingPR.id, 
-          repo_id: repoInDb.id, 
-          author_id: existingPR.author_id 
-        });
-        throw updateError; // Re-throw to halt further processing
-      }
-      
-      // Conditionally call fetchAdditionalPRData ONLY if action is 'opened' 
-      if (action === 'opened') {
-        console.log(`WEBHOOK ADDITIONAL DATA: PR #${pr.number} action is 'opened'. Preparing to fetch additional data.`);
-        if (repoInDb.organization_id !== null) {
-          try {
-            await fetchAdditionalPRData(repository, pr, existingPR.id, repoInDb.organization_id, payload);
-          } catch (additionalDataError) {
-            logError("fetchAdditionalPRData for existing PR", additionalDataError, { 
-              pr_id: existingPR.id, 
-              repo_id: repoInDb.id, 
-              org_id: repoInDb.organization_id 
-            });
-            // Don't re-throw, allow webhook to complete even if additional data fails
-          }
-        } else {
-          console.warn(`WEBHOOK WARNING: Organization ID is null for repository ${repoInDb.full_name}. Skipping AI categorization.`);
-        }
+        console.warn('[Webhook] GITHUB_WEBHOOK_SECRET not configured - skipping signature verification in development')
       }
-    } else {
-      // Create new PR
-      console.log(`WEBHOOK PR CREATE: Creating new PR #${pr.number} in ${repository.full_name}`);
-
-      // Ensure the author exists in our database
-      const authorGitHubData = pr.user;
-      console.log(`WEBHOOK AUTHOR CHECK: PR author GitHub data: id=${authorGitHubData.id}, login=${authorGitHubData.login}`);
- 
-      try {
-        const dbUser = await findOrCreateUserByGitHubId({
-          id: authorGitHubData.id.toString(),
-          login: authorGitHubData.login,
-          avatar_url: null,
-          name: null,
-        });
- 
-        console.log(`WEBHOOK AUTHOR RESULT: findOrCreateUserByGitHubId result for GH ID ${authorGitHubData.id}:`, 
-                    dbUser ? `User DB ID ${dbUser.id}` : 'null');
- 
-        if (!dbUser) {
-          console.error(`WEBHOOK ERROR: Could not find or create user for GitHub ID: ${authorGitHubData.id}. Skipping PR creation.`);
-          return;
-        }
- 
-        // Properly type the state to match the enum expected by createPullRequest
-        const typedState = prState as "open" | "closed" | "merged";
-        
-        const newPrParams = {
-          github_id: pr.id,
-          repository_id: repoInDb.id,
-          number: pr.number,
-          title: pr.title,
-          description: pr.body,
-          author_id: dbUser.id,
-          state: typedState, // Use the properly typed state
-          created_at: pr.created_at,
-          updated_at: pr.updated_at,
-          closed_at: pr.closed_at,
-          merged_at: pr.merged_at,
-          draft: pr.draft,
-          additions: pr.additions || null,
-          deletions: pr.deletions || null,
-          changed_files: pr.changed_files || null,
-          category_id: null,
-          category_confidence: null
-        };
- 
-        logOperation("createPullRequest", newPrParams);
- 
-        let newPR;
-        try {
-          newPR = await createPullRequest(newPrParams);
-          console.log(`WEBHOOK PR CREATED: New PR #${pr.number} in ${repository.full_name} with DB ID ${newPR.id}`);
-        } catch (prCreateError: any) {
-          // If UNIQUE constraint error, fallback to update
-          if (prCreateError.message && prCreateError.message.includes('UNIQUE constraint failed: pull_requests.repository_id, pull_requests.number')) {
-            console.warn(`WEBHOOK PR CREATE: PR already exists (race condition). Falling back to update for PR #${pr.number} in ${repository.full_name}`);
-            const fallbackExistingPR = await findPullRequestByNumber(repoInDb.id, pr.number);
-            if (fallbackExistingPR) {
-              await updatePullRequest(fallbackExistingPR.id, {
-                title: pr.title,
-                description: pr.body,
-                state: typedState,
-                updated_at: pr.updated_at,
-                closed_at: pr.closed_at,
-                merged_at: pr.merged_at,
-                draft: pr.draft,
-                additions: pr.additions,
-                deletions: pr.deletions,
-                changed_files: pr.changed_files
-              });
-              newPR = fallbackExistingPR;
-              console.log(`WEBHOOK PR UPDATED (fallback): PR #${pr.number} in ${repository.full_name}`);
-            } else {
-              throw prCreateError;
-            }
-          } else {
-            logError("PR Creation", prCreateError, { 
-              repo_full_name: repository.full_name, 
-              repo_id: repoInDb?.id, 
-              pr_number: pr.number,
-              author_github_id: authorGitHubData.id
-            });
-            throw prCreateError;
-          }
-        }
-        
-        // Fetch additional data for new PRs IFF the action was 'opened'
-        if (action === 'opened') {
-          console.log(`WEBHOOK ADDITIONAL DATA: New PR #${pr.number} action is 'opened'. Preparing to fetch additional data.`);
-          if (repoInDb.organization_id !== null) {
-            try {
-              await fetchAdditionalPRData(repository, pr, newPR.id, repoInDb.organization_id, payload);
-            } catch (additionalDataError) {
-              logError("fetchAdditionalPRData for new PR", additionalDataError, { 
-                pr_id: newPR.id, 
-                repo_id: repoInDb.id, 
-                org_id: repoInDb.organization_id 
-              });
-              // Don't re-throw, allow webhook to complete even if additional data fails
-            }
-          } else {
-            console.warn(`WEBHOOK WARNING: Organization ID is null for new PR in repository ${repoInDb.full_name}. Skipping AI categorization.`);
-          }
-        } else {
-          console.log(`WEBHOOK INFO: New PR #${pr.number} created, but action was '${action}', not 'opened'. Skipping fetchAdditionalPRData.`);
-        }
-      } catch (prCreateError) {
-        logError("PR Creation", prCreateError, { 
-          repo_full_name: repository.full_name, 
-          repo_id: repoInDb?.id, 
-          pr_number: pr.number,
-          author_github_id: authorGitHubData.id
-        });
-        throw prCreateError;
-      }
-    }
-  } catch (error) {
-    logError("handlePullRequestEvent", error, { 
-      repo_full_name: repository.full_name, 
-      pr_number: pr.number
-    });
-    throw error; // Re-throw to be handled by the main handler
-  }
-}
-
-async function handlePullRequestReviewEvent(payload: PullRequestReviewPayload) {
-  const { repository, pull_request, review } = payload;
-  
-  console.log(`WEBHOOK REVIEW PROCESSING: Review for PR #${pull_request.number} repo=${repository.full_name} by user=${review.user.login}`);
-  
-  try {
-    // Find repository in our database
-    const repoInDb = await findRepositoryByFullName(repository.full_name);
-    
-    console.log(`WEBHOOK REPOSITORY CHECK FOR REVIEW: ${repository.full_name} found in DB? ${!!repoInDb}`, 
-                repoInDb ? `id=${repoInDb.id}` : "NOT FOUND");
-    
-    if (!repoInDb) {
-      console.log(`Repository ${repository.full_name} not found in database, skipping review webhook processing`);
-      return;
     }
     
-    // Find the PR in our database
-    const existingPR = await findPullRequestByNumber(repoInDb.id, pull_request.number);
-    
-    console.log(`WEBHOOK PR CHECK FOR REVIEW: PR #${pull_request.number} found in DB? ${!!existingPR}`,
-                existingPR ? `id=${existingPR.id}` : "NOT FOUND");
-    
-    if (!existingPR) {
-      console.log(`PR #${pull_request.number} not found in database for ${repository.full_name}, skipping review processing`);
-      return;
-    }
-    
-    // Map GitHub review state to our enum
-    const reviewState = mapReviewState(review.state);
-    
-    // Check if the review already exists
-    const existingReview = await findReviewByGitHubId(review.id);
-    
-    console.log(`WEBHOOK REVIEW CHECK: Review ${review.id} exists in DB? ${!!existingReview}`,
-                existingReview ? `id=${existingReview.id}, state=${existingReview.state}` : "NOT FOUND");
-    
-    if (existingReview) {
-      // Update existing review
-      const updateParams = {
-        id: existingReview.id,
-        state: reviewState
-      };
+    // Validate webhook signature and payload
+    let validation
+    if (webhookSecret) {
+      validation = await validateWebhook(request, webhookSecret)
       
-      logOperation("updatePullRequestReview", updateParams);
-      
-      try {
-        await updatePullRequestReview(existingReview.id, {
-          state: reviewState
-        });
-        
-        console.log(`WEBHOOK REVIEW UPDATED: Review for PR #${pull_request.number} in ${repository.full_name}`);
-      } catch (updateError) {
-        logError("updatePullRequestReview", updateError, { 
-          review_id: existingReview.id, 
-          pr_id: existingPR.id
-        });
-        throw updateError;
+      if (!validation.valid) {
+        console.error(`[Webhook] Validation failed: ${validation.error}`)
+        return NextResponse.json(
+          { error: validation.error }, 
+          { status: 400 }
+        )
       }
     } else {
-      // Create new review
-      const newReviewParams = {
-        github_id: review.id,
-        pull_request_id: existingPR.id,
-        reviewer_id: review.user.id.toString(),
-        state: reviewState,
-        submitted_at: review.submitted_at
-      };
-      
-      logOperation("createPullRequestReview", newReviewParams);
+      // In development, read the payload manually
+      const eventType = request.headers.get('x-github-event')
+      const bodyText = await request.text()
       
       try {
-        await createPullRequestReview(newReviewParams);
-        
-        console.log(`WEBHOOK REVIEW CREATED: New review for PR #${pull_request.number} in ${repository.full_name}`);
-      } catch (createError) {
-        logError("createPullRequestReview", createError, { 
-          review_github_id: review.id,
-          pr_id: existingPR.id,
-          reviewer_id: review.user.id.toString()
-        });
-        throw createError;
-      }
-    }
-  } catch (reviewError) {
-    logError("handlePullRequestReviewEvent", reviewError, { 
-      repo_full_name: repository.full_name, 
-      pr_number: pull_request.number,
-      review_id: review.id
-    });
-    throw reviewError;
-  }
-}
-
-// New handler for installation events
-async function handleInstallationEvent(payload: InstallationPayload) {
-  const { action, installation } = payload;
-  const installationId = installation.id;
-  const account = installation.account;
-
-  // We are primarily interested in installations on Organizations
-  if (account.type !== 'Organization') {
-    console.log(`WEBHOOK INSTALLATION: Skipping installation event for non-organization account type: ${account.type}, login: ${account.login}`);
-    return;
-  }
-
-  const orgGitHubId = account.id;
-  const orgLogin = account.login;
-  const orgAvatarUrl = account.avatar_url || null;
-
-  console.log(`WEBHOOK INSTALLATION: Action: ${action} for organization ${orgLogin} (GitHub ID: ${orgGitHubId}), Installation ID: ${installationId}`);
-
-  try {
-    // Find the organization by its GitHub ID.
-    // It's possible the organization isn't in our DB yet if the app is installed on a new org.
-    // findOrCreateOrganization will handle this.
-    // It expects: github_id, name, avatar_url
-    
-    // First, ensure the org exists or create it
-    let org = await OrganizationRepository.findOrganizationByGitHubId(orgGitHubId);
-
-    if (!org && action === 'created') {
-        console.log(`WEBHOOK INSTALLATION: Organization ${orgLogin} (GitHub ID: ${orgGitHubId}) not found. Creating.`);
-        try {
-            org = await OrganizationRepository.createOrganization({
-                github_id: orgGitHubId,
-                name: orgLogin,
-                avatar_url: orgAvatarUrl
-            });
-            console.log(`WEBHOOK INSTALLATION: Created organization ${org.name} with DB ID ${org.id}`);
-        } catch (createError) {
-            logError("handleInstallationEvent - createOrganization", createError, { orgGitHubId, orgLogin });
-            return; // Stop if creation fails
+        const payload = JSON.parse(bodyText)
+        validation = {
+          valid: true,
+          eventType: eventType || 'unknown',
+          payload
         }
-    } else if (!org) {
-        console.log(`WEBHOOK INSTALLATION: Organization ${orgLogin} (GitHub ID: ${orgGitHubId}) not found for action '${action}'. Skipping update.`);
-        return;
-    }
-
-
-    if (action === 'created') {
-      // Update the organization with the new installation_id
-      const updatedOrg = await OrganizationRepository.updateOrganization(org.id, {
-        installation_id: installationId,
-        // Optionally update name/avatar if they can change and are in payload
-        name: orgLogin, 
-        avatar_url: orgAvatarUrl
-      });
-      if (updatedOrg) {
-        console.log(`WEBHOOK INSTALLATION: Stored installation_id ${installationId} for organization ${orgLogin} (DB ID: ${org.id})`);
-      } else {
-        console.error(`WEBHOOK INSTALLATION: Failed to update organization ${orgLogin} with installation_id ${installationId}`);
+      } catch (error) {
+        return NextResponse.json(
+          { error: 'Invalid JSON payload' }, 
+          { status: 400 }
+        )
       }
-
-      // If repositories are explicitly listed (e.g. selective installation)
-      if (payload.repositories && payload.repositories.length > 0) {
-        console.log(`WEBHOOK INSTALLATION: Processing ${payload.repositories.length} repositories for new installation on ${orgLogin}`);
-        for (const repoData of payload.repositories) {
-          try {
-            // Use findOrCreateRepository to add these to our system, linking them to the organization
-            // Assuming findOrCreateRepository can link to org.id if it's not already doing so.
-            // This might require findOrCreateRepository to accept org.id or for you to have a separate step.
-            // For now, just logging and ensuring findOrCreateRepository is robust.
-            await findOrCreateRepository({ 
-              github_id: repoData.id, 
-              name: repoData.name, 
-              full_name: repoData.full_name,
-              private: repoData.private,
-              organization_id: org.id, // Crucial link
-              description: null, // Default value
-              is_tracked: true   // Default value, assume tracked upon installation
-            });
-            console.log(`WEBHOOK INSTALLATION: Ensured repository ${repoData.full_name} is in DB and linked to org ${org.id}.`);
-          } catch (repoError) {
-            logError("handleInstallationEvent - findOrCreateRepository", repoError, { repo_full_name: repoData.full_name, org_id: org.id });
-          }
-        }
-      }
-
-
-    } else if (action === 'deleted') {
-      // Clear the installation_id
-      const updatedOrg = await OrganizationRepository.updateOrganization(org.id, {
-        installation_id: null,
-      });
-      if (updatedOrg) {
-        console.log(`WEBHOOK INSTALLATION: Cleared installation_id for organization ${orgLogin} (DB ID: ${org.id}) due to app uninstallation.`);
-      } else {
-        console.error(`WEBHOOK INSTALLATION: Failed to clear installation_id for organization ${orgLogin}`);
-      }
-    } else if (action === 'suspend') {
-        // Optionally handle suspension, e.g., by setting installation_id to null or a special status
-        console.log(`WEBHOOK INSTALLATION: App suspended for organization ${orgLogin}. Installation ID ${installationId} might be invalid.`);
-        await OrganizationRepository.updateOrganization(org.id, { installation_id: null }); // Example: clear it
-    } else if (action === 'unsuspend') {
-        // App unsuspended, restore installation_id
-        console.log(`WEBHOOK INSTALLATION: App unsuspended for organization ${orgLogin}. Restoring Installation ID ${installationId}.`);
-        await OrganizationRepository.updateOrganization(org.id, { installation_id: installationId });
-    } else {
-      console.log(`WEBHOOK INSTALLATION: Unhandled action '${action}' for organization ${orgLogin}.`);
     }
-  } catch (error) {
-    logError("handleInstallationEvent", error, { action, orgGitHubId, orgLogin, installationId });
-  }
-}
 
-async function fetchAdditionalPRData(
-  repository: PullRequestPayload['repository'], 
-  pr: PullRequestPayload['pull_request'], 
-  prDbId: number,
-  organizationId: number,
-  fullPayload?: PullRequestPayload
-) {
-  console.log(`WEBHOOK ADDITIONAL DATA: Fetching additional data for PR #${pr.number} in org ${organizationId}, PR DB ID=${prDbId}`);
-  console.log(`WEBHOOK DEBUG: Repository owner: ${repository.owner.login}, Repository name: ${repository.name}`);
-  
-  if (!organizationId) {
-    console.error('WEBHOOK ERROR: Organization ID not provided to fetchAdditionalPRData. Cannot proceed.');
-    return;
-  }
+    const { eventType, payload } = validation
+    console.log(`[Webhook] Processing event: ${eventType}.${payload?.action || 'unknown'}`)
 
-  try {
-    let installationIdToUse: number | undefined;
-    const orgDetails = await findOrganizationById(organizationId);
-
-    if (orgDetails) {
-      // Use the installation_id from the DB if available (this is the most reliable source)
-      installationIdToUse = orgDetails.installation_id ?? undefined; 
-      if (installationIdToUse) {
-        console.log(`WEBHOOK DEBUG: Found installation_id in DB for organization_id ${organizationId}: ${installationIdToUse}`);
-      } else {
-        console.warn(`WEBHOOK WARNING: installation_id was not found or was null in database for organization_id: ${organizationId}.`);
-      }
-    } else {
-      console.error(`WEBHOOK ERROR: Organization with ID ${organizationId} NOT FOUND in database.`);
-      // Update PR status to indicate an error if org not found
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Organization not found in DB for AI processing' });
-      return; 
-    }
-
-    // If DB didn't have it, try to get it from the current webhook payload as a fallback
-    // This might happen if the installation event is processed slightly after a PR event.
-    if (!installationIdToUse) {
-      const payloadInstallId = fullPayload?.installation?.id || repository?.installation?.id;
-      if (payloadInstallId) {
-        installationIdToUse = payloadInstallId;
-        console.log(`WEBHOOK DEBUG: Using installation_id from current payload as fallback: ${installationIdToUse} (org_id: ${organizationId})`);
-        // Optionally, you could consider updating the org record here if a payload ID is found and DB was null,
-        // but handleInstallationEvent should be the primary source of truth for storing it.
-      } else {
-        console.warn(`WEBHOOK WARNING: No installation_id in DB and no installation_id in current payload for org ${organizationId}.`);
-      }
-    }
+    // Get GitHub service from DI container
+    const githubService = await getService<IGitHubService>('GitHubService')
     
-    // 1. Get API settings (model + API key)
-    console.log(`WEBHOOK AI SETTINGS: Getting AI settings for organization ${organizationId}`);
-    const aiSettings = await getOrganizationAiSettings(organizationId);
-    const selectedModelId = aiSettings.selectedModelId;
-                
-    if (!selectedModelId || selectedModelId === '__none__') {
-      console.log(`WEBHOOK INFO: AI categorization disabled for organization ${organizationId} (no model selected).`);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'skipped', error_message: 'AI categorization disabled for organization' });
-      return;
-    }
-
-    const provider = aiSettings.provider;
-    
-    if (!provider) {
-      console.log(`WEBHOOK INFO: AI provider not set for organization ${organizationId}.`);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'skipped', error_message: 'AI provider not set for organization' });
-      return;
-    }
-    
-    console.log(`WEBHOOK MODEL: Using AI model ${selectedModelId} with provider ${provider}`);
-
-    const apiKey = await getOrganizationApiKey(organizationId, provider);
-    if (!apiKey) {
-      console.warn(`WEBHOOK WARNING: API key for provider ${provider} not set for organization ${organizationId}. Skipping AI categorization.`);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'skipped', error_message: `API key for ${provider} not set for organization` });
-      return;
-    }
-    console.log(`WEBHOOK API KEY: API key found for provider ${provider}.`);
-
-    // 2. Instantiate AI Client (using apiKey)
-    let aiClientProvider;
-    try {
-      switch (provider) {
-        case 'openai':
-          aiClientProvider = createOpenAI({ apiKey: apiKey });
-          break;
-        case 'google':
-          aiClientProvider = createGoogleGenerativeAI({ apiKey: apiKey });
-          break;
-        case 'anthropic':
-          aiClientProvider = createAnthropic({ apiKey: apiKey });
-          break;
-        default:
-          console.error(`WEBHOOK ERROR: Unsupported AI provider: ${provider} for organization ${organizationId}`);
-          await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: `Unsupported AI provider: ${provider}` });
-          return;
-      }
-    } catch (error) {
-      console.error(`WEBHOOK ERROR: Error instantiating AI client provider for ${provider}:`, error);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: `Error instantiating AI client for ${provider}` });
-      return;
-    }
-    console.log(`WEBHOOK AI CLIENT: AI client provider instantiated for: ${provider}`);
+    // Process the webhook event
+    const result = await githubService.processWebhookEvent(eventType!, payload)
     
-    const modelInstance = aiClientProvider(selectedModelId);
-    if (!modelInstance) {
-      console.error(`WEBHOOK ERROR: Could not get model instance for ${selectedModelId} from provider ${provider}`);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: `Could not get AI model instance ${selectedModelId}` });
-      return;
-    }
-
-    // 3. Create GitHub Client
-    let githubClient: GitHubClient;
-
-    if (installationIdToUse) {
-      try {
-        console.log(`WEBHOOK INSTALLATION ID: Attempting to use GitHub App installation ID: ${installationIdToUse}`);
-        githubClient = await createInstallationClient(installationIdToUse);
-        console.log(`WEBHOOK CLIENT: Successfully created GitHub client with installation ID ${installationIdToUse}`);
-      } catch (clientError) {
-        console.error(`WEBHOOK ERROR: Failed to create GitHub client with installation ID ${installationIdToUse}:`, clientError);
-        await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Failed to create GitHub client with installation ID' });
-        return;
-      }
+    if (result.processed) {
+      console.log(`[Webhook] Successfully processed ${eventType} event:`, result.actions)
+      return NextResponse.json({ 
+        success: true, 
+        actions: result.actions 
+      })
     } else {
-      console.error('WEBHOOK ERROR: No installation ID available for organization. Cannot fetch PR diff.');
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'GitHub authentication failed (no installation ID)' });
-      return;
-    }
-
-    // 4. Fetch PR Diff and Categorize (using githubClient)
-    console.log(`WEBHOOK FETCHING PR DIFF: Fetching PR diff for ${repository.full_name}#${pr.number}`);
-    
-    let diff: string | null = null;
-    try {
-      // Try to fetch the PR diff
-      diff = await githubClient.getPullRequestDiff(repository.owner.login, repository.name, pr.number);
-    } catch (diffError: any) {
-      // Check if it's a token expiration error
-      if (diffError.message && (
-          diffError.message.includes('expired') || 
-          diffError.message.includes('GitHub token expired') || 
-          diffError.message.includes('invalid') ||
-          diffError.message.includes('Bad credentials') ||
-          diffError.status === 401)
-      ) {
-        console.warn(`WEBHOOK TOKEN ERROR: Installation token for ${installationIdToUse} appears to be expired or invalid. Attempting to create a new client.`);
-        
-        // Try once more with a fresh client
-        try {
-          // Create fresh client - the token cache will return a new token since the old one was cleared
-          githubClient = await createInstallationClient(installationIdToUse);
-          console.log(`WEBHOOK CLIENT RECREATED: Successfully created new GitHub client with installation ID ${installationIdToUse}`);
-          
-          // Retry the diff fetch
-          diff = await githubClient.getPullRequestDiff(repository.owner.login, repository.name, pr.number);
-          console.log(`WEBHOOK DIFF RETRY: Successfully fetched PR diff on second attempt for ${repository.full_name}#${pr.number}`);
-        } catch (retryError) {
-          console.error(`WEBHOOK ERROR: Failed to fetch PR diff even after token refresh:`, retryError);
-          await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Failed to fetch PR diff even after token refresh' });
-          return;
-        }
-      } else {
-        console.error(`WEBHOOK ERROR: Failed to fetch PR diff for ${repository.full_name}#${pr.number}:`, diffError);
-        await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Failed to fetch PR diff' });
-        return;
-      }
-    }
-    
-    if (!diff) {
-      console.warn(`WEBHOOK WARNING: Could not fetch PR diff for ${repository.full_name}#${pr.number}. Skipping categorization.`);
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'skipped', error_message: 'Could not fetch PR diff' });
-      return;
-    }
-
-    const orgCategories = await getOrganizationCategories(organizationId);
-    const categoryNames = orgCategories.map(c => c.name);
-    console.log(`WEBHOOK CATEGORIES: Organization ${organizationId} has ${categoryNames.length} categories:`, categoryNames);
-
-    if (categoryNames.length === 0) {
-        console.warn(`WEBHOOK WARNING: No categories found for organization ${organizationId}. Skipping categorization.`);
-        await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'skipped', error_message: 'No categories configured for organization' });
-        return;
-    }
-
-    await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'processing' });
-
-    // Create a more restrictive prompt with numbered options
-    const categoryOptions = categoryNames.map((name, index) => `${index + 1}. ${name}`).join('\n');
-    
-    const systemPrompt = `You are an expert at categorizing GitHub pull requests. You MUST select EXACTLY ONE category from the numbered list below. Do not create new categories or modify the category names.
-
-AVAILABLE CATEGORIES:
-${categoryOptions}
-
-Analyze the pull request and respond in this EXACT format:
-Category: [EXACT CATEGORY NAME FROM LIST]
-Confidence: [NUMBER BETWEEN 0.0 AND 1.0]
-
-Example: Category: Bug Fix, Confidence: 0.85
-
-IMPORTANT: The category name must match EXACTLY one of the categories listed above. Do not abbreviate, modify, or create new category names.`;
-
-    const userPrompt = `Title: ${pr.title}
-Body: ${pr.body || ''}
-Diff:
-${diff}`;
-
-    console.log(`WEBHOOK GENERATING TEXT: Generating text with model ${selectedModelId} for PR #${pr.number}`);
-
-    try {
-      const { text } = await generateText({
-        model: modelInstance,
-        system: systemPrompt,
-        prompt: userPrompt,
-      });
-
-      console.log(`WEBHOOK AI RESPONSE: AI Response for PR #${pr.number}: ${text}`);
-
-      // Parse AI response - handle both comma-separated and newline-separated formats
-      const categoryMatch = text.match(/Category:\s*(.*?)(?:,|\n)\s*Confidence:\s*(\d+\.?\d*)/i);
-      if (categoryMatch && categoryMatch[1] && categoryMatch[2]) {
-        const suggestedCategoryName = categoryMatch[1].trim();
-        const confidence = parseFloat(categoryMatch[2]);
-
-        // First, try exact match
-        let category = await findCategoryByNameAndOrgFromRepo(organizationId, suggestedCategoryName);
-        console.log(`WEBHOOK CATEGORY LOOKUP: Category '${suggestedCategoryName}' found in DB? ${!!category}`,
-                    category ? `id=${category.id}, org_id=${category.organization_id}` : "NOT FOUND");
-        
-        // If no exact match, try fuzzy matching as fallback
-        if (!category) {
-          console.log(`WEBHOOK FUZZY MATCHING: Attempting fuzzy match for '${suggestedCategoryName}' in categories: ${categoryNames.join(', ')}`);
-          
-          // Simple fuzzy matching - find closest match
-          let bestMatch = null;
-          let bestScore = 0;
-          
-          for (const categoryName of categoryNames) {
-            // Calculate similarity score (simple case-insensitive contains check + length similarity)
-            const suggested = suggestedCategoryName.toLowerCase().trim();
-            const candidate = categoryName.toLowerCase().trim();
-            
-            let score = 0;
-            if (suggested === candidate) {
-              score = 1.0; // Perfect match
-            } else if (suggested.includes(candidate) || candidate.includes(suggested)) {
-              score = 0.8; // Contains match
-            } else {
-              // Levenshtein-like simple scoring
-              const maxLength = Math.max(suggested.length, candidate.length);
-              const commonChars = suggested.split('').filter(char => candidate.includes(char)).length;
-              score = commonChars / maxLength;
-            }
-            
-            if (score > bestScore && score > 0.6) { // Minimum threshold
-              bestScore = score;
-              bestMatch = categoryName;
-            }
-          }
-          
-          if (bestMatch) {
-            console.log(`WEBHOOK FUZZY MATCH: Found fuzzy match '${bestMatch}' for '${suggestedCategoryName}' with score ${bestScore}`);
-            category = await findCategoryByNameAndOrgFromRepo(organizationId, bestMatch);
-          }
-        }
-        
-        if (category) {
-          try {
-            const updateCategoryParams = {
-              pr_id: prDbId,
-              category_id: category.id,
-              confidence: confidence
-            };
-            
-            logOperation("updatePullRequestCategory", updateCategoryParams);
-            
-            await updatePullRequestCategory(prDbId, category.id, confidence);
-            await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'completed' });
-            console.log(`WEBHOOK CATEGORY ASSIGNED: PR #${pr.number} categorized as '${category.name}' (ID: ${category.id}) with confidence ${confidence}`);
-          } catch (categoryError) {
-            logError("updatePullRequestCategory", categoryError, {
-              pr_id: prDbId,
-              category_id: category.id,
-              category_name: category.name,
-              confidence: confidence
-            });
-            await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Failed to update PR with category' });
-          }
-        } else {
-          console.warn(`WEBHOOK CATEGORY ERROR: AI suggested category '${suggestedCategoryName}' not found for organization ${organizationId}.`);
-          await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: `AI suggested category '${suggestedCategoryName}' not found` });
-        }
-      } else {
-        console.warn(`WEBHOOK PARSE ERROR: Could not parse category and confidence from AI response for PR #${pr.number}: ${text}`);
-        await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Could not parse AI category response' });
-      }
-    } catch (aiError) {
-      logError("AI Text Generation", aiError, {
-         pr_id: prDbId,
-         model: selectedModelId
-      });
-      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'AI text generation failed' });
+      console.warn(`[Webhook] Failed to process ${eventType} event:`, result.errors)
+      return NextResponse.json({
+        success: false,
+        errors: result.errors
+      }, { status: 422 })
     }
 
   } catch (error) {
-    logError("fetchAdditionalPRData main try-catch", error, {
-      repo_name: repository.full_name, 
-      pr_number: pr.number,
-      pr_id: prDbId,
-      org_id: organizationId
-    });
-    // Attempt to update PR status to error if not already handled
-    try {
-        await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'error', error_message: 'Critical error in fetchAdditionalPRData' });
-    } catch (updateErr) {
-        logError("fetchAdditionalPRData - final PR status update error", updateErr, { pr_id: prDbId });
-    }
+    console.error('[Webhook] Error processing webhook:', error)
+    return NextResponse.json(
+      { 
+        error: `Failed to process webhook: ${error instanceof Error ? error.message : 'Unknown error'}` 
+      }, 
+      { status: 500 }
+    )
   }
 }
 
-// Helper to map GitHub review state to our enum
-function mapReviewState(state: string): PRReview['state'] {
-  switch (state.toLowerCase()) {
-    case 'approved':
-      return 'approved';
-    case 'changes_requested':
-      return 'changes_requested';
-    case 'commented':
-      return 'commented';
-    case 'dismissed':
-      return 'dismissed';
-    default:
-      return 'commented'; // Default fallback
-  }
-} 
+/**
+ * Health check endpoint for webhook configuration
+ */
+export async function GET() {
+  return NextResponse.json({
+    status: 'ready',
+    timestamp: new Date().toISOString(),
+    webhook_url: process.env.APP_URL ? `${process.env.APP_URL}/api/webhook/github` : 'not configured'
+  })
+}

auth.ts

···
 export const config = {
   providers: [
     GitHub({
-      clientId: process.env.GITHUB_CLIENT_ID || 'demo-client-id',
-      clientSecret: process.env.GITHUB_CLIENT_SECRET || 'demo-client-secret',
+      clientId: process.env.GITHUB_OAUTH_CLIENT_ID || 'demo-client-id',
+      clientSecret: process.env.GITHUB_OAUTH_CLIENT_SECRET || 'demo-client-secret',
       authorization: {
         params: {
           scope: 'read:user user:email repo read:org',
···
       
       // Allow dashboard access in demo mode (when no real GitHub credentials configured)
       if (pathname.startsWith("/dashboard")) {
-        const hasGitHubCredentials = process.env.GITHUB_CLIENT_ID && 
-                                     process.env.GITHUB_CLIENT_SECRET && 
-                                     process.env.GITHUB_CLIENT_ID !== 'demo-client-id';
+        const hasGitHubCredentials = process.env.GITHUB_OAUTH_CLIENT_ID && 
+                                     process.env.GITHUB_OAUTH_CLIENT_SECRET && 
+                                     process.env.GITHUB_OAUTH_CLIENT_ID !== 'demo-client-id';
         
         if (!hasGitHubCredentials) {
           // Demo mode: allow dashboard access without authentication
···
       }
 
       // Check if we're in demo mode (no real GitHub config)
-      const isDemoMode = !process.env.GITHUB_CLIENT_ID || process.env.GITHUB_CLIENT_ID === 'demo-client-id';
+      const isDemoMode = !process.env.GITHUB_OAUTH_CLIENT_ID || process.env.GITHUB_OAUTH_CLIENT_ID === 'demo-client-id';
       
       if (isDemoMode) {
         // Demo mode: use simple session without database calls
···
     },
     async signIn({ user, account, profile }) {
       // Skip database operations if GitHub credentials not properly configured (demo mode)
-      const hasGitHubCredentials = process.env.GITHUB_CLIENT_ID && 
-                                   process.env.GITHUB_CLIENT_SECRET && 
-                                   process.env.GITHUB_CLIENT_ID !== 'demo-client-id';
+      const hasGitHubCredentials = process.env.GITHUB_OAUTH_CLIENT_ID && 
+                                   process.env.GITHUB_OAUTH_CLIENT_SECRET && 
+                                   process.env.GITHUB_OAUTH_CLIENT_ID !== 'demo-client-id';
       
       if (!hasGitHubCredentials) {
         // Demo mode: allow sign-in without database operations  

components/nav-user.tsx

···
 
 import { signIn, signOut, useSession } from "next-auth/react"
 import { useTheme } from "next-themes"
+import { useState } from "react"
 import {
   SidebarMenu,
   SidebarMenuItem,
···
   DropdownMenuSubTrigger,
   DropdownMenuPortal
 } from "@/components/ui/dropdown-menu"
-import { IconBrandGithub, IconMoon, IconSun, IconDeviceDesktop } from "@tabler/icons-react"
+import { IconBrandGithub, IconMoon, IconSun, IconDeviceDesktop, IconLoader2 } from "@tabler/icons-react"
 
 export function NavUser() {
   const { } = useSidebar()
   const { data: session } = useSession()
   const { setTheme, theme } = useTheme()
+  const [isSigningIn, setIsSigningIn] = useState(false)
+
+  const handleSignIn = async () => {
+    setIsSigningIn(true)
+    try {
+      await signIn("github", { callbackUrl: "/dashboard" })
+    } catch (error) {
+      console.error("Sign in error:", error)
+      setIsSigningIn(false)
+    }
+    // Note: We don't set loading to false here because the page will redirect
+  }
 
   // If not authenticated, show GitHub login button
   if (!session) {
···
           <SidebarMenuButton 
             size="lg" 
             className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
-            onClick={() => signIn("github", { callbackUrl: "/dashboard" })}
+            onClick={handleSignIn}
+            disabled={isSigningIn}
           >
             <div className="flex items-center justify-center h-8 w-8">
-              <IconBrandGithub className="h-5 w-5" />
+              {isSigningIn ? (
+                <IconLoader2 className="h-5 w-5 animate-spin" />
+              ) : (
+                <IconBrandGithub className="h-5 w-5" />
+              )}
             </div>
             <div className="grid flex-1 text-left text-sm leading-tight">
-              <span className="truncate font-medium">Sign in</span>
+              <span className="truncate font-medium">
+                {isSigningIn ? "Signing in..." : "Sign in"}
+              </span>
               <span className="text-muted-foreground truncate text-xs">
-                with GitHub
+                {isSigningIn ? "Please wait..." : "with GitHub"}
               </span>
             </div>
           </SidebarMenuButton>

components/ui/github-signin-button.tsx

···
 
 import { signIn } from "next-auth/react";
 import { Button } from "@/components/ui/button";
-import { IconBrandGithub } from "@tabler/icons-react";
+import { IconBrandGithub, IconLoader2 } from "@tabler/icons-react";
+import { useState } from "react";
 
 export function GitHubSignInButton({ callbackUrl = "/dashboard" }) {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleSignIn = async () => {
+    setIsLoading(true);
+    try {
+      await signIn("github", { callbackUrl });
+    } catch (error) {
+      console.error("Sign in error:", error);
+      setIsLoading(false);
+    }
+    // Note: We don't set loading to false here because the page will redirect
+  };
+
   return (
     <Button
       className="w-full flex items-center justify-center gap-2"
-      onClick={() => signIn("github", { callbackUrl })}
+      onClick={handleSignIn}
+      disabled={isLoading}
     >
-      <IconBrandGithub size={20} />
-      Continue with GitHub
+      {isLoading ? (
+        <IconLoader2 size={20} className="animate-spin" />
+      ) : (
+        <IconBrandGithub size={20} />
+      )}
+      {isLoading ? "Signing in..." : "Continue with GitHub"}
     </Button>
   );
 } 

environment.example

···
 # Create at: https://github.com/settings/developers
 # Callback URL: ${NEXTAUTH_URL}/api/auth/callback/github
 
-GITHUB_CLIENT_ID=your_github_oauth_client_id
-GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
+GITHUB_OAUTH_CLIENT_ID=your_github_oauth_client_id
+GITHUB_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
 
 # ===========================================
 # GITHUB APP (Required for repository access)

jest.setup.ts

···
 // Mock environment variables for tests
 process.env.TURSO_URL = 'libsql://test.turso.io';
 process.env.TURSO_TOKEN = 'test-token';
-process.env.GITHUB_CLIENT_ID = 'test-github-client-id';
-process.env.GITHUB_CLIENT_SECRET = 'test-github-client-secret';
+process.env.GITHUB_OAUTH_CLIENT_ID = 'test-github-client-id';
+process.env.GITHUB_OAUTH_CLIENT_SECRET = 'test-github-client-secret';
 process.env.GITHUB_APP_ID = '123456';
 process.env.GITHUB_APP_PRIVATE_KEY = `-----BEGIN RSA PRIVATE KEY-----
 test-private-key

lib/core/container/di-container.ts

···
   IAuthService,
   IOrganizationRepository,
   IRepository,
-  IGitHubService
+  IGitHubService,
+  IGitHubAppService
 } from '../ports'
 
 // Service registry types
···
   | 'OrganizationRepository'
   | 'Repository'
   | 'GitHubService'
+  | 'GitHubAppService'
 
 export type ServiceInstance = 
   | IPullRequestRepository
···
   | IOrganizationRepository
   | IRepository
   | IGitHubService
+  | IGitHubAppService
 
 export interface ServiceFactory<T = ServiceInstance> {
   (): T | Promise<T>
···
       const { DemoGitHubService } = await import('../../infrastructure/adapters/demo')
       return new DemoGitHubService()
     }, true)
+
+    this.register('GitHubAppService', async () => {
+      const { GitHubAppService } = await import('../../infrastructure/adapters/github')
+      return new GitHubAppService()
+    }, true)
   }
 
   /**
···
           return new DemoGitHubService()
         }, true)
       }
+
+      // Always register GitHub App service - it handles its own configuration validation
+      this.register('GitHubAppService', async () => {
+        const { GitHubAppService } = await import('../../infrastructure/adapters/github')
+        return new GitHubAppService()
+      }, true)
 
       console.log('[DI Container] Production services registered successfully')
     } catch (error) {

lib/core/ports/github-app.port.ts

···
+/**
+ * GitHub App Service Port
+ * Defines the contract for GitHub App operations
+ */
+
+import { Organization } from '../domain/entities/organization'
+import { Repository } from '../domain/entities/repository'
+
+export interface InstallationInfo {
+  id: number
+  account: {
+    id: number
+    login: string
+    type: 'Organization' | 'User'
+    avatarUrl?: string
+  }
+  permissions: Record<string, string>
+  repositorySelection: 'all' | 'selected'
+  repositoryCount?: number
+  suspendedAt?: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface InstallationToken {
+  token: string
+  expiresAt: Date
+  permissions: Record<string, string>
+}
+
+export interface IGitHubAppService {
+  /**
+   * Generate a JWT token for GitHub App authentication
+   */
+  generateAppJWT(): Promise<string>
+
+  /**
+   * Get an installation access token for a specific installation ID
+   * This method handles caching and automatic refresh
+   */
+  getInstallationToken(installationId: number): Promise<string>
+
+  /**
+   * Get installation information for a specific installation ID
+   */
+  getInstallation(installationId: number): Promise<InstallationInfo>
+
+  /**
+   * List all installations for the GitHub App
+   */
+  listInstallations(): Promise<InstallationInfo[]>
+
+  /**
+   * Get installation for a specific organization by GitHub ID
+   */
+  getOrganizationInstallation(orgGitHubId: number): Promise<InstallationInfo | null>
+
+  /**
+   * Get repositories accessible by an installation
+   */
+  getInstallationRepositories(installationId: number): Promise<Repository[]>
+
+  /**
+   * Check if GitHub App is installed for an organization
+   */
+  isInstalledForOrganization(orgLogin: string): Promise<{
+    isInstalled: boolean
+    installationId?: number
+    permissions?: Record<string, string>
+  }>
+
+  /**
+   * Sync installation data with database
+   */
+  syncInstallation(installationId: number): Promise<{
+    organization: Organization
+    repositories: Repository[]
+    errors: string[]
+  }>
+
+  /**
+   * Clear cached tokens for an installation (useful when tokens are revoked)
+   */
+  clearTokenCache(installationId?: number): Promise<void>
+
+  /**
+   * Validate if the GitHub App is properly configured
+   */
+  validateConfiguration(): Promise<{
+    isValid: boolean
+    errors: string[]
+    appId?: string
+    hasPrivateKey: boolean
+  }>
+}

lib/core/ports/index.ts

···
 export * from './auth.port'
 export * from './organization.port'
 export * from './github.port'
+export * from './github-app.port'
 export * from './repository.port'

lib/env-validation.ts

···
   TURSO_POOL_SIZE: z.string().regex(/^\d+$/).optional(),
   
   // GitHub OAuth (optional for demo mode)
-  GITHUB_CLIENT_ID: z.string().optional(),
-  GITHUB_CLIENT_SECRET: z.string().optional(),
+  GITHUB_OAUTH_CLIENT_ID: z.string().optional(),
+  GITHUB_OAUTH_CLIENT_SECRET: z.string().optional(),
   
   // GitHub App (optional for demo mode)
   GITHUB_APP_ID: z.string().optional(),
   GITHUB_APP_PRIVATE_KEY: z.string().optional(),
-  // If you don't use a separate webhook secret, we will fallback to GITHUB_CLIENT_SECRET at runtime
+  // If you don't use a separate webhook secret, we will fallback to GITHUB_OAUTH_CLIENT_SECRET at runtime
   GITHUB_WEBHOOK_SECRET: z.string().optional(),
   NEXT_PUBLIC_GITHUB_APP_SLUG: z.string().optional(),
   

lib/github-app.ts

···
-import jwt from 'jsonwebtoken';
-import { GitHubClient } from './github';
-
-// Token cache to store installation tokens with expiration times
-interface CachedToken {
-  token: string;
-  expiresAt: number; // Unix timestamp in ms when token expires
-}
-
-// In-memory cache for installation tokens
-// In a production environment, you might want to use a distributed cache like Redis
-const tokenCache: Map<number, CachedToken> = new Map();
-
 /**
- * Generate a GitHub App JWT token used for authenticating as the GitHub App
+ * GitHub App Legacy API
+ * Backward compatibility layer for existing GitHub App functionality
+ * 
+ * @deprecated Use the new GitHubAppService from DI container instead:
+ * const githubAppService = await getService<IGitHubAppService>('GitHubAppService')
  */
-export async function generateAppJwt(): Promise<string> {
-  const appId = process.env.GITHUB_APP_ID;
-  
-  if (!appId) {
-    throw new Error('GitHub App ID (GITHUB_APP_ID) is not configured');
-  }
 
-  // For debugging purposes, explicitly define the format of the private key
-  // This shows exactly what format is expected
-  
-  // First try to get the key from environment
-  let privateKey = process.env.GITHUB_APP_PRIVATE_KEY;
-  
-  // Debug only - log length of private key
-  console.log(`Private key from env length: ${privateKey?.length || 0}`);
-  
-  if (privateKey) {
-    // Remove any quotes that might have been included
-    privateKey = privateKey.replace(/^["']|["']$/g, '');
-    
-    // Replace escaped newlines with actual newlines
-    privateKey = privateKey.replace(/\\n/g, '\n');
-  
-    console.log('Using private key from environment variables');
-  } else {
-    console.error('No private key found in environment variables');
-    throw new Error('GitHub App private key (GITHUB_APP_PRIVATE_KEY) is not configured');
-  }
-  
-  // JWT expiration (10 minutes maximum)
-  const now = Math.floor(Date.now() / 1000);
-  
-  // Create JWT payload
-  const payload = {
-    // Issued at time, 60 seconds in the past to allow for clock drift
-    iat: now - 60,
-    // Expiration time (10 minutes from now)
-    exp: now + (10 * 60),
-    // GitHub App ID
-    iss: appId
-  };
+// Re-export functions from the new adapter for backward compatibility
+export { 
+  generateAppJwt,
+  getInstallationToken,
+  createInstallationClient,
+  clearTokenFromCache,
+  clearTokenCache
+} from './infrastructure/adapters/github/github-app.adapter'
 
-  // Sign the JWT with the GitHub App private key
-  try {
-    // Log the first and last few characters of the key for debugging
-    console.log('Key format check:');
-    console.log('Starts with:', privateKey.substring(0, 40));
-    console.log('Ends with:', privateKey.substring(privateKey.length - 40));
-    
-    return jwt.sign(payload, privateKey, { algorithm: 'RS256' });
-  } catch (error) {
-    console.error('Error generating GitHub App JWT:', error);
-    throw new Error('Failed to generate GitHub App JWT: ' + (error instanceof Error ? error.message : 'Unknown error'));
-  }
-}
-
-/**
- * Get an installation access token for a specific installation ID
- * This implementation includes token caching and revalidation
- */
-export async function getInstallationToken(installationId: number): Promise<string> {
-  try {
-    // Check if we have a valid cached token
-    const cachedToken = tokenCache.get(installationId);
-    const bufferTimeMs = 5 * 60 * 1000; // 5 minute buffer before expiration
-    const now = Date.now();
-    
-    // Use cached token if it exists and isn't close to expiring
-    if (cachedToken && (cachedToken.expiresAt - now > bufferTimeMs)) {
-      console.log(`Using cached token for installation ${installationId}, expires in ${Math.floor((cachedToken.expiresAt - now) / 1000 / 60)} minutes`);
-      return cachedToken.token;
-    }
-
-    // Need to generate a new token
-    if (cachedToken) {
-      console.log(`Cached token for installation ${installationId} is expired or expiring soon. Generating new token.`);
-    } else {
-      console.log(`No cached token for installation ${installationId}. Generating new token.`);
-    }
-
-    // Generate a new JWT for GitHub App authentication
-    const appJwt = await generateAppJwt();
-    
-    // Create a temporary GitHub client using the app JWT
-    const appClient = new GitHubClient(appJwt);
-    
-    // Exchange the JWT for an installation token
-    const token = await appClient.createInstallationAccessToken(installationId);
-    
-    // Cache the token with its expiration time (GitHub tokens expire in 1 hour)
-    const expiresAt = now + (60 * 60 * 1000); // Current time + 1 hour
-    tokenCache.set(installationId, {
-      token,
-      expiresAt
-    });
-    
-    console.log(`Generated and cached new token for installation ${installationId}, expires in 60 minutes`);
-    return token;
-  } catch (error) {
-    console.error('Error getting installation token:', error);
-    throw new Error('Failed to get installation token: ' + (error instanceof Error ? error.message : 'Unknown error'));
-  }
-}
-
-/**
- * Create a GitHub client authenticated with an installation token
- */
-export async function createInstallationClient(installationId: number): Promise<GitHubClient> {
-  const token = await getInstallationToken(installationId);
-  return new GitHubClient(token, installationId);
-}
-
-/**
- * Clear a specific token from the cache if needed
- */
-export function clearTokenFromCache(installationId: number): void {
-  tokenCache.delete(installationId);
-  console.log(`Cleared token cache for installation ${installationId}`);
-}
-
-/**
- * Clear all tokens from the cache
- */
-export function clearTokenCache(): void {
-  tokenCache.clear();
-  console.log('Cleared all installation tokens from cache');
-} 
+// Legacy type exports for backward compatibility
+export interface CachedToken {
+  token: string
+  expiresAt: number // Unix timestamp in ms when token expires
+}

lib/github.ts

···
   }
 
   /**
+   * Get direct access to the Octokit client for advanced operations
+   */
+  get octokitClient(): Octokit {
+    return this.octokit;
+  }
+
+  /**
    * Execute a GitHub API request with automatic token expiration handling
    * @param apiCall Function that executes the actual API call
    * @returns Result of the API call
···
         config: {
           url: webhookUrl,
           content_type: 'json',
-          secret: process.env.GITHUB_WEBHOOK_SECRET ?? process.env.GITHUB_CLIENT_SECRET,
+          secret: process.env.GITHUB_WEBHOOK_SECRET ?? process.env.GITHUB_OAUTH_CLIENT_SECRET,
         },
         events: ['pull_request', 'pull_request_review']
       });

lib/infrastructure/adapters/github/github-app.adapter.ts

···
+/**
+ * GitHub App Service Adapter
+ * Implements IGitHubAppService using GitHub App authentication
+ */
+
+import jwt from 'jsonwebtoken'
+import { IGitHubAppService, InstallationInfo, InstallationToken } from '../../../core/ports/github-app.port'
+import { Organization } from '../../../core/domain/entities/organization'
+import { Repository } from '../../../core/domain/entities/repository'
+import { GitHubClient } from '../../../github'
+import { 
+  findOrCreateOrganization,
+  findOrCreateRepository,
+  findOrganizationById,
+  findRepositoryByGitHubId
+} from '../../../repositories'
+import * as OrganizationRepository from '../../../repositories/organization-repository'
+
+// Token cache to store installation tokens with expiration times
+interface CachedToken {
+  token: string
+  expiresAt: number // Unix timestamp in ms when token expires
+  permissions: Record<string, string>
+}
+
+// In-memory cache for installation tokens
+// In production, consider using Redis for distributed caching
+const tokenCache: Map<number, CachedToken> = new Map()
+
+export class GitHubAppService implements IGitHubAppService {
+
+  /**
+   * Generate a JWT token for GitHub App authentication
+   */
+  async generateAppJWT(): Promise<string> {
+    const appId = process.env.GITHUB_APP_ID
+    
+    if (!appId) {
+      throw new Error('GitHub App ID (GITHUB_APP_ID) is not configured')
+    }
+
+    // Get private key from environment
+    let privateKey = process.env.GITHUB_APP_PRIVATE_KEY
+    
+    if (!privateKey) {
+      throw new Error('GitHub App private key (GITHUB_APP_PRIVATE_KEY) is not configured')
+    }
+
+    // Clean up the private key format
+    privateKey = privateKey.replace(/^["']|["']$/g, '') // Remove quotes
+    privateKey = privateKey.replace(/\\n/g, '\n') // Replace escaped newlines
+    
+    // JWT expiration (10 minutes maximum per GitHub requirements)
+    const now = Math.floor(Date.now() / 1000)
+    
+    const payload = {
+      iat: now - 60, // Issued at time, 60 seconds in the past for clock drift
+      exp: now + (10 * 60), // Expiration time (10 minutes from now)
+      iss: appId // GitHub App ID
+    }
+
+    try {
+      return jwt.sign(payload, privateKey, { algorithm: 'RS256' })
+    } catch (error) {
+      console.error('Error generating GitHub App JWT:', error)
+      throw new Error('Failed to generate GitHub App JWT: ' + (error instanceof Error ? error.message : 'Unknown error'))
+    }
+  }
+
+  /**
+   * Get an installation access token for a specific installation ID
+   */
+  async getInstallationToken(installationId: number): Promise<string> {
+    try {
+      // Check for cached token
+      const cachedToken = tokenCache.get(installationId)
+      const bufferTimeMs = 5 * 60 * 1000 // 5 minute buffer before expiration
+      const now = Date.now()
+      
+      // Use cached token if valid and not expiring soon
+      if (cachedToken && (cachedToken.expiresAt - now > bufferTimeMs)) {
+        console.log(`[GitHubApp] Using cached token for installation ${installationId}, expires in ${Math.floor((cachedToken.expiresAt - now) / 1000 / 60)} minutes`)
+        return cachedToken.token
+      }
+
+      // Generate new token
+      console.log(`[GitHubApp] Generating new token for installation ${installationId}`)
+      
+      const appJwt = await this.generateAppJWT()
+      const appClient = new GitHubClient(appJwt)
+      
+      // Exchange JWT for installation token
+      const token = await appClient.createInstallationAccessToken(installationId)
+      
+      // Cache token with expiration (GitHub tokens expire in 1 hour)
+      const expiresAt = now + (60 * 60 * 1000)
+      tokenCache.set(installationId, {
+        token,
+        expiresAt,
+        permissions: {} // TODO: Get actual permissions from installation
+      })
+      
+      console.log(`[GitHubApp] Generated and cached new token for installation ${installationId}`)
+      return token
+    } catch (error) {
+      console.error(`[GitHubApp] Error getting installation token for ${installationId}:`, error)
+      throw new Error('Failed to get installation token: ' + (error instanceof Error ? error.message : 'Unknown error'))
+    }
+  }
+
+  /**
+   * Get installation information for a specific installation ID
+   */
+  async getInstallation(installationId: number): Promise<InstallationInfo> {
+    try {
+      const appJwt = await this.generateAppJWT()
+      const appClient = new GitHubClient(appJwt)
+      
+      // Get installation details  
+      const response = await appClient.octokitClient.apps.getInstallation({
+        installation_id: installationId
+      })
+      
+      const installation = response.data
+      
+      return {
+        id: installation.id,
+        account: {
+          id: installation.account!.id,
+          login: (installation.account as any).login,
+          type: (installation.account as any).type as 'Organization' | 'User',
+          avatarUrl: installation.account!.avatar_url || undefined
+        },
+        permissions: (installation as any).permissions || {},
+        repositorySelection: (installation as any).repository_selection as 'all' | 'selected',
+        repositoryCount: (installation as any).repository_count || undefined,
+        suspendedAt: (installation as any).suspended_at ? new Date((installation as any).suspended_at) : null,
+        createdAt: new Date(installation.created_at),
+        updatedAt: new Date(installation.updated_at)
+      }
+    } catch (error) {
+      console.error(`[GitHubApp] Error getting installation ${installationId}:`, error)
+      throw new Error('Failed to get installation: ' + (error instanceof Error ? error.message : 'Unknown error'))
+    }
+  }
+
+  /**
+   * List all installations for the GitHub App
+   */
+  async listInstallations(): Promise<InstallationInfo[]> {
+    try {
+      const appJwt = await this.generateAppJWT()
+      const appClient = new GitHubClient(appJwt)
+      
+      const response = await appClient.octokitClient.apps.listInstallations()
+      
+      return response.data.map(installation => ({
+        id: installation.id,
+        account: {
+          id: installation.account!.id,
+          login: (installation.account as any).login,
+          type: (installation.account as any).type as 'Organization' | 'User',
+          avatarUrl: installation.account!.avatar_url || undefined
+        },
+        permissions: (installation as any).permissions || {},
+        repositorySelection: (installation as any).repository_selection as 'all' | 'selected',
+        repositoryCount: (installation as any).repository_count || undefined,
+        suspendedAt: (installation as any).suspended_at ? new Date((installation as any).suspended_at) : null,
+        createdAt: new Date(installation.created_at),
+        updatedAt: new Date(installation.updated_at)
+      }))
+    } catch (error) {
+      console.error('[GitHubApp] Error listing installations:', error)
+      throw new Error('Failed to list installations: ' + (error instanceof Error ? error.message : 'Unknown error'))
+    }
+  }
+
+  /**
+   * Get installation for a specific organization by GitHub ID
+   */
+  async getOrganizationInstallation(orgGitHubId: number): Promise<InstallationInfo | null> {
+    try {
+      const installations = await this.listInstallations()
+      return installations.find(installation => 
+        installation.account.id === orgGitHubId && 
+        installation.account.type === 'Organization'
+      ) || null
+    } catch (error) {
+      console.error(`[GitHubApp] Error getting organization installation for ${orgGitHubId}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * Get repositories accessible by an installation
+   */
+  async getInstallationRepositories(installationId: number): Promise<Repository[]> {
+    try {
+      const token = await this.getInstallationToken(installationId)
+      const client = new GitHubClient(token, installationId)
+      
+      const response = await client.octokitClient.apps.listReposAccessibleToInstallation()
+      
+      return response.data.repositories.map(repo => ({
+        id: repo.id.toString(),
+        name: repo.name,
+        fullName: repo.full_name,
+        description: repo.description || null,
+        htmlUrl: repo.html_url,
+        defaultBranch: repo.default_branch || 'main',
+        isPrivate: repo.private,
+        isTracked: false,
+        isArchived: repo.archived || false,
+        language: repo.language || null,
+        size: repo.size || 0,
+        stargazersCount: repo.stargazers_count || 0,
+        forksCount: repo.forks_count || 0,
+        openIssuesCount: repo.open_issues_count || 0,
+        organizationId: repo.owner.id.toString(),
+        createdAt: new Date(repo.created_at || Date.now()),
+        updatedAt: new Date(repo.updated_at || Date.now()),
+        pushedAt: repo.pushed_at ? new Date(repo.pushed_at) : null
+      }))
+    } catch (error) {
+      console.error(`[GitHubApp] Error getting installation repositories for ${installationId}:`, error)
+      throw new Error('Failed to get installation repositories: ' + (error instanceof Error ? error.message : 'Unknown error'))
+    }
+  }
+
+  /**
+   * Check if GitHub App is installed for an organization
+   */
+  async isInstalledForOrganization(orgLogin: string): Promise<{
+    isInstalled: boolean
+    installationId?: number
+    permissions?: Record<string, string>
+  }> {
+    try {
+      const installations = await this.listInstallations()
+      const installation = installations.find(inst => 
+        inst.account.login === orgLogin && 
+        inst.account.type === 'Organization'
+      )
+
+      if (installation) {
+        return {
+          isInstalled: true,
+          installationId: installation.id,
+          permissions: installation.permissions
+        }
+      }
+
+      return { isInstalled: false }
+    } catch (error) {
+      console.error(`[GitHubApp] Error checking installation for org ${orgLogin}:`, error)
+      return { isInstalled: false }
+    }
+  }
+
+  /**
+   * Sync installation data with database
+   */
+  async syncInstallation(installationId: number): Promise<{
+    organization: Organization
+    repositories: Repository[]
+    errors: string[]
+  }> {
+    const errors: string[] = []
+    
+    try {
+      // Get installation info
+      const installation = await this.getInstallation(installationId)
+      
+      if (installation.account.type !== 'Organization') {
+        throw new Error('Only organization installations are supported')
+      }
+
+      console.log(`[GitHubApp] Syncing installation ${installationId} for org ${installation.account.login}`)
+
+      // Create or update organization in database
+      let organization: Organization
+      try {
+        const dbOrg = await OrganizationRepository.findOrganizationByGitHubId(installation.account.id)
+        
+        if (dbOrg) {
+          // Update existing organization
+          const updatedOrg = await OrganizationRepository.updateOrganization(dbOrg.id, {
+            installation_id: installationId,
+            name: installation.account.login,
+            avatar_url: installation.account.avatarUrl || null
+          })
+          organization = this.mapDbOrgToDomain(updatedOrg!)
+        } else {
+          // Create new organization
+          const newOrg = await OrganizationRepository.createOrganization({
+            github_id: installation.account.id,
+            name: installation.account.login,
+            avatar_url: installation.account.avatarUrl || null,
+            installation_id: installationId
+          })
+          organization = this.mapDbOrgToDomain(newOrg)
+        }
+      } catch (error) {
+        const errorMsg = `Failed to sync organization: ${error instanceof Error ? error.message : 'Unknown error'}`
+        errors.push(errorMsg)
+        throw new Error(errorMsg)
+      }
+
+      // Get and sync repositories
+      const repositories: Repository[] = []
+      try {
+        const installationRepos = await this.getInstallationRepositories(installationId)
+        
+        for (const repo of installationRepos) {
+          try {
+            await findOrCreateRepository({
+              github_id: parseInt(repo.id),
+              organization_id: parseInt(organization.id),
+              name: repo.name,
+              full_name: repo.fullName,
+              description: repo.description,
+              private: repo.isPrivate,
+              is_tracked: true // Mark as tracked since it's accessible by the app
+            })
+            repositories.push(repo)
+          } catch (repoError) {
+            const errorMsg = `Failed to sync repository ${repo.fullName}: ${repoError instanceof Error ? repoError.message : 'Unknown error'}`
+            errors.push(errorMsg)
+            console.error(`[GitHubApp] ${errorMsg}`)
+          }
+        }
+      } catch (error) {
+        const errorMsg = `Failed to get installation repositories: ${error instanceof Error ? error.message : 'Unknown error'}`
+        errors.push(errorMsg)
+        console.error(`[GitHubApp] ${errorMsg}`)
+      }
+
+      console.log(`[GitHubApp] Synced installation ${installationId}: org=${organization.name}, repos=${repositories.length}, errors=${errors.length}`)
+      
+      return {
+        organization,
+        repositories,
+        errors
+      }
+    } catch (error) {
+      const errorMsg = `Failed to sync installation ${installationId}: ${error instanceof Error ? error.message : 'Unknown error'}`
+      errors.push(errorMsg)
+      console.error(`[GitHubApp] ${errorMsg}`)
+      throw new Error(errorMsg)
+    }
+  }
+
+  /**
+   * Clear cached tokens for an installation
+   */
+  async clearTokenCache(installationId?: number): Promise<void> {
+    if (installationId) {
+      tokenCache.delete(installationId)
+      console.log(`[GitHubApp] Cleared token cache for installation ${installationId}`)
+    } else {
+      tokenCache.clear()
+      console.log('[GitHubApp] Cleared all installation tokens from cache')
+    }
+  }
+
+  /**
+   * Validate if the GitHub App is properly configured
+   */
+  async validateConfiguration(): Promise<{
+    isValid: boolean
+    errors: string[]
+    appId?: string
+    hasPrivateKey: boolean
+  }> {
+    const errors: string[] = []
+    const appId = process.env.GITHUB_APP_ID
+    const privateKey = process.env.GITHUB_APP_PRIVATE_KEY
+
+    if (!appId) {
+      errors.push('GITHUB_APP_ID environment variable is not set')
+    }
+
+    if (!privateKey) {
+      errors.push('GITHUB_APP_PRIVATE_KEY environment variable is not set')
+    } else {
+      // Validate private key format
+      try {
+        await this.generateAppJWT()
+      } catch (error) {
+        errors.push('Invalid GitHub App private key format')
+      }
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      appId: appId || undefined,
+      hasPrivateKey: !!privateKey
+    }
+  }
+
+  /**
+   * Helper method to map database organization to domain entity
+   */
+  private mapDbOrgToDomain(dbOrg: any): Organization {
+    return {
+      id: dbOrg.id.toString(),
+      login: dbOrg.name, // GitHub login name
+      name: dbOrg.display_name || dbOrg.name,
+      description: dbOrg.description || null,
+      avatarUrl: dbOrg.avatar_url || '',
+      type: 'Organization' as const,
+      htmlUrl: `https://github.com/${dbOrg.name}`,
+      isInstalled: !!dbOrg.installation_id,
+      installationId: dbOrg.installation_id?.toString() || null,
+      createdAt: new Date(dbOrg.created_at || Date.now()),
+      updatedAt: new Date(dbOrg.updated_at || Date.now())
+    }
+  }
+}
+
+/**
+ * Legacy compatibility functions - these wrap the new service
+ */
+
+let githubAppService: GitHubAppService | null = null
+
+function getGitHubAppService(): GitHubAppService {
+  if (!githubAppService) {
+    githubAppService = new GitHubAppService()
+  }
+  return githubAppService
+}
+
+export async function generateAppJwt(): Promise<string> {
+  return getGitHubAppService().generateAppJWT()
+}
+
+export async function getInstallationToken(installationId: number): Promise<string> {
+  return getGitHubAppService().getInstallationToken(installationId)
+}
+
+export async function createInstallationClient(installationId: number): Promise<GitHubClient> {
+  const token = await getInstallationToken(installationId)
+  return new GitHubClient(token, installationId)
+}
+
+export function clearTokenFromCache(installationId: number): void {
+  getGitHubAppService().clearTokenCache(installationId)
+}
+
+export function clearTokenCache(): void {
+  getGitHubAppService().clearTokenCache()
+}

lib/infrastructure/adapters/github/index.ts

···
  * Exports all GitHub API adapter implementations
  */
 
-export { SimpleGitHubAPIService as GitHubAPIService } from './simple-github.adapter'
+export { SimpleGitHubAPIService } from './simple-github.adapter'
+export { RealGitHubAPIService } from './real-github.adapter'
+export { GitHubAppService } from './github-app.adapter'
+
+// Export the appropriate services based on environment
+export { RealGitHubAPIService as GitHubAPIService } from './real-github.adapter'
+export { GitHubAppService as GitHubApp } from './github-app.adapter'

lib/infrastructure/adapters/github/real-github.adapter.ts

···
+/**
+ * Real GitHub API Service Adapter
+ * Implements IGitHubService using actual GitHub API calls via Octokit
+ */
+
+import { IGitHubService } from '../../../core/ports'
+import { Organization, Repository, PullRequest, User } from '../../../core/domain/entities'
+import { GitHubClient, createGitHubClient, createGitHubInstallationClient } from '../../../github'
+import { createInstallationClient } from '../../../github-app'
+import crypto from 'crypto'
+import { 
+  findOrCreateOrganization, 
+  findOrCreateRepository,
+  findUserById,
+  createPullRequest,
+  findPullRequestByNumber,
+  updatePullRequest,
+  findReviewByGitHubId,
+  createPullRequestReview,
+  setRepositoryTracking,
+  findRepositoryById,
+  findRepositoryByGitHubId,
+  addUserToOrganization,
+  findOrCreateUserByGitHubId,
+  findOrganizationById,
+  findRepositoryByFullName,
+  updatePullRequestCategory,
+  getOrganizationCategories,
+  getOrganizationAiSettings,
+  getOrganizationApiKey,
+  findCategoryByNameAndOrg
+} from '../../../repositories'
+import * as OrganizationRepository from '../../../repositories/organization-repository'
+import * as PullRequestRepository from '../../../repositories/pr-repository'
+import { generateText } from 'ai'
+import { createOpenAI } from '@ai-sdk/openai'
+import { createGoogleGenerativeAI } from '@ai-sdk/google'
+import { createAnthropic } from '@ai-sdk/anthropic'
+
+export class RealGitHubAPIService implements IGitHubService {
+  private client?: GitHubClient
+
+  constructor(private accessToken?: string) {
+    if (accessToken) {
+      this.client = createGitHubClient(accessToken)
+    }
+  }
+
+  /**
+   * Get user information from GitHub
+   */
+  async getUser(accessToken: string): Promise<User> {
+    const client = createGitHubClient(accessToken)
+    const githubUser = await client.getCurrentUser()
+    
+    return {
+      id: githubUser.id.toString(),
+      login: githubUser.login,
+      name: githubUser.name || githubUser.login,
+      email: githubUser.email || null,
+      avatarUrl: githubUser.avatar_url || '',
+      htmlUrl: githubUser.html_url || `https://github.com/${githubUser.login}`,
+      type: 'User' as const,
+      isNewUser: false, // Determined elsewhere in the application
+      hasGithubApp: false, // Determined elsewhere in the application
+      createdAt: new Date(), // GitHub API doesn't provide creation date for users in basic calls
+      updatedAt: new Date()
+    }
+  }
+
+  /**
+   * Get user's organizations from GitHub
+   */
+  async getUserOrganizations(accessToken: string): Promise<Organization[]> {
+    const client = createGitHubClient(accessToken)
+    const githubOrgs = await client.getUserOrganizations()
+    
+    return githubOrgs.map(org => ({
+      id: org.id.toString(),
+      login: org.login,
+      name: org.login, // GitHub Organizations only have login in basic API
+      description: org.description || null,
+      avatarUrl: org.avatar_url || '',
+      type: 'Organization' as const,
+      htmlUrl: `https://github.com/${org.login}`,
+      isInstalled: false, // Will be updated when we check installation status
+      installationId: null,
+      createdAt: new Date(), // GitHub API doesn't provide creation date
+      updatedAt: new Date()
+    }))
+  }
+
+  /**
+   * Get organization information from GitHub
+   */
+  async getOrganization(orgLogin: string): Promise<Organization> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    // Use the organization repositories endpoint to get org info
+    const repos = await this.client.getOrganizationRepositories(orgLogin)
+    const firstRepo = repos[0]
+    
+    if (!firstRepo) {
+      throw new Error(`No repositories found for organization: ${orgLogin}`)
+    }
+
+    const owner = firstRepo.owner
+    return {
+      id: owner.id.toString(),
+      login: owner.login,
+      name: owner.login, // Owner type doesn't have name property
+      description: null,
+      avatarUrl: (owner as any).avatar_url || '',
+      type: 'Organization' as const,
+      htmlUrl: `https://github.com/${owner.login}`,
+      isInstalled: false,
+      installationId: null,
+      createdAt: new Date(),
+      updatedAt: new Date()
+    }
+  }
+
+  /**
+   * Get organization repositories from GitHub
+   */
+  async getOrganizationRepositories(
+    orgLogin: string,
+    options?: {
+      type?: 'all' | 'public' | 'private'
+      sort?: 'created' | 'updated' | 'pushed' | 'full_name'
+      per_page?: number
+      page?: number
+    }
+  ): Promise<Repository[]> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    const githubRepos = await this.client.getOrganizationRepositories(orgLogin)
+    
+    return githubRepos.map(repo => ({
+      id: repo.id.toString(),
+      name: repo.name,
+      fullName: repo.full_name,
+      description: repo.description || null,
+      htmlUrl: repo.html_url,
+      defaultBranch: (repo as any).default_branch || 'main',
+      isPrivate: (repo as any).private || false,
+      isTracked: false,
+      isArchived: (repo as any).archived || false,
+      language: (repo as any).language || null,
+      size: (repo as any).size || 0,
+      stargazersCount: (repo as any).stargazers_count || 0,
+      forksCount: (repo as any).forks_count || 0,
+      openIssuesCount: (repo as any).open_issues_count || 0,
+      organizationId: repo.owner.id.toString(),
+      createdAt: new Date((repo as any).created_at || Date.now()),
+      updatedAt: new Date((repo as any).updated_at || Date.now()),
+      pushedAt: (repo as any).pushed_at ? new Date((repo as any).pushed_at) : null
+    }))
+  }
+
+  /**
+   * Get accessible repositories for an organization (requires GitHub App)
+   */
+  async getAccessibleRepositories(orgLogin: string): Promise<Repository[]> {
+    // For now, return all org repositories
+    // In production, this would filter based on GitHub App installation permissions
+    return this.getOrganizationRepositories(orgLogin)
+  }
+
+  /**
+   * Get repository information from GitHub
+   */
+  async getRepository(owner: string, repo: string): Promise<Repository> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    const githubRepo = await this.client.getRepository(owner, repo)
+    
+    return {
+      id: githubRepo.id.toString(),
+      name: githubRepo.name,
+      fullName: githubRepo.full_name,
+      description: githubRepo.description || null,
+      htmlUrl: githubRepo.html_url,
+      defaultBranch: (githubRepo as any).default_branch || 'main',
+      isPrivate: (githubRepo as any).private || false,
+      isTracked: false,
+      isArchived: (githubRepo as any).archived || false,
+      language: (githubRepo as any).language || null,
+      size: (githubRepo as any).size || 0,
+      stargazersCount: (githubRepo as any).stargazers_count || 0,
+      forksCount: (githubRepo as any).forks_count || 0,
+      openIssuesCount: (githubRepo as any).open_issues_count || 0,
+      organizationId: githubRepo.owner.id.toString(),
+      createdAt: new Date((githubRepo as any).created_at || Date.now()),
+      updatedAt: new Date((githubRepo as any).updated_at || Date.now()),
+      pushedAt: (githubRepo as any).pushed_at ? new Date((githubRepo as any).pushed_at) : null
+    }
+  }
+
+  /**
+   * Get pull requests for a repository
+   */
+  async getRepositoryPullRequests(
+    owner: string,
+    repo: string,
+    options?: {
+      state?: 'open' | 'closed' | 'all'
+      sort?: 'created' | 'updated' | 'popularity' | 'long-running'
+      direction?: 'asc' | 'desc'
+      per_page?: number
+      page?: number
+    }
+  ): Promise<PullRequest[]> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    const state = options?.state || 'all'
+    const githubPRs = await this.client.getAllPullRequests(owner, repo, state)
+    
+    return githubPRs.map(pr => this.mapGitHubPRToDomain(pr))
+  }
+
+  /**
+   * Get pull request details from GitHub
+   */
+  async getPullRequest(
+    owner: string,
+    repo: string,
+    pullNumber: number
+  ): Promise<PullRequest> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    const githubPR = await this.client.getPullRequest(owner, repo, pullNumber)
+    return this.mapGitHubPRToDomain(githubPR)
+  }
+
+  /**
+   * Get pull request reviews
+   */
+  async getPullRequestReviews(
+    owner: string,
+    repo: string,
+    pullNumber: number
+  ): Promise<Array<{
+    id: string
+    user: User
+    state: 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED'
+    body: string
+    submittedAt: Date
+  }>> {
+    if (!this.client) {
+      throw new Error('GitHub client not initialized. Access token required.')
+    }
+
+    const reviews = await this.client.getPullRequestReviews(owner, repo, pullNumber)
+    
+    return reviews
+      .filter(review => review.user) // Only include reviews with user data
+      .map(review => ({
+        id: review.id.toString(),
+        user: {
+          id: review.user!.id.toString(),
+          login: review.user!.login,
+          name: review.user!.name || review.user!.login,
+          email: review.user!.email || null,
+          avatarUrl: review.user!.avatar_url || '',
+          htmlUrl: (review.user as any).html_url || `https://github.com/${review.user!.login}`,
+          type: 'User' as const,
+          isNewUser: false,
+          hasGithubApp: false,
+          createdAt: new Date(),
+          updatedAt: new Date()
+        },
+        state: this.mapReviewState(review.state),
+        body: (review as any).body || '',
+        submittedAt: new Date((review as any).submitted_at)
+      }))
+  }
+
+  /**
+   * Sync organization repositories from GitHub
+   */
+  async syncOrganizationRepositories(orgLogin: string): Promise<{
+    synced: Repository[]
+    errors: Array<{ repo: string; error: string }>
+  }> {
+    try {
+      const repositories = await this.getOrganizationRepositories(orgLogin)
+      
+      // Store repositories in database
+      const org = await findOrCreateOrganization({
+        github_id: repositories[0] ? parseInt(repositories[0].id) : 0,
+        name: orgLogin,
+        avatar_url: '',
+      })
+
+      const synced: Repository[] = []
+      const errors: Array<{ repo: string; error: string }> = []
+
+      for (const repo of repositories) {
+        try {
+          await findOrCreateRepository({
+            github_id: parseInt(repo.id),
+            organization_id: org.id,
+            name: repo.name,
+            full_name: repo.fullName,
+            description: repo.description,
+            private: repo.isPrivate,
+            is_tracked: false
+          })
+          synced.push(repo)
+        } catch (error) {
+          errors.push({
+            repo: repo.fullName,
+            error: error instanceof Error ? error.message : 'Unknown error'
+          })
+        }
+      }
+
+      return { synced, errors }
+    } catch (error) {
+      return {
+        synced: [],
+        errors: [{ repo: orgLogin, error: error instanceof Error ? error.message : 'Unknown error' }]
+      }
+    }
+  }
+
+  /**
+   * Sync repository pull requests from GitHub
+   */
+  async syncRepositoryPullRequests(
+    repositoryId: string,
+    since?: Date
+  ): Promise<{
+    synced: PullRequest[]
+    errors: Array<{ pr: number; error: string }>
+  }> {
+    try {
+      // Find repository in database
+      const dbRepo = await findRepositoryById(parseInt(repositoryId))
+      if (!dbRepo) {
+        return {
+          synced: [],
+          errors: [{ pr: 0, error: `Repository ${repositoryId} not found` }]
+        }
+      }
+
+      const [owner, repo] = dbRepo.full_name.split('/')
+      if (!owner || !repo) {
+        return {
+          synced: [],
+          errors: [{ pr: 0, error: 'Invalid repository full name format' }]
+        }
+      }
+
+      let pullRequests = await this.getRepositoryPullRequests(owner, repo)
+      
+      // Filter by 'since' date if provided
+      if (since) {
+        pullRequests = pullRequests.filter(pr => new Date(pr.createdAt) >= since)
+      }
+
+      const synced: PullRequest[] = []
+      const errors: Array<{ pr: number; error: string }> = []
+
+      for (const pr of pullRequests) {
+        try {
+          const existingPR = await findPullRequestByNumber(parseInt(repositoryId), pr.number)
+          
+          if (existingPR) {
+            // Update existing PR
+            await updatePullRequest(existingPR.id, {
+              title: pr.title,
+              state: pr.status as 'open' | 'closed' | 'merged'
+            })
+          } else {
+            // Create new PR
+            const author = await findOrCreateUserByGitHubId({
+              id: pr.developer.id.toString(),
+              login: pr.developer.name, // Use name as login since domain only has name
+              avatar_url: '',
+              name: pr.developer.name
+            })
+
+            if (author) {
+              await createPullRequest({
+                github_id: parseInt(pr.id.toString()),
+                repository_id: parseInt(repositoryId),
+                number: pr.number,
+                title: pr.title,
+                description: null, // Domain entity doesn't have description
+                author_id: author.id,
+                state: pr.status as 'open' | 'closed' | 'merged',
+                created_at: pr.createdAt,
+                updated_at: pr.createdAt, // Use createdAt since domain has both as strings
+                closed_at: null,
+                merged_at: pr.status === 'merged' ? pr.mergedAt : null,
+                draft: false,
+                additions: pr.linesAdded || 0,
+                deletions: 0,
+                changed_files: pr.files || 0,
+                category_id: null,
+                category_confidence: null
+              })
+            }
+          }
+          
+          synced.push(pr)
+        } catch (error) {
+          errors.push({
+            pr: pr.number,
+            error: error instanceof Error ? error.message : 'Unknown error'
+          })
+        }
+      }
+
+      return { synced, errors }
+    } catch (error) {
+      return {
+        synced: [],
+        errors: [{ pr: 0, error: error instanceof Error ? error.message : 'Unknown error' }]
+      }
+    }
+  }
+
+  /**
+   * Check GitHub App installation status
+   */
+  async getInstallationStatus(orgLogin: string): Promise<{
+    isInstalled: boolean
+    installationId: string | null
+    permissions: Record<string, string>
+  }> {
+    try {
+      // Find organization in database to get installation ID
+      const org = await findOrCreateOrganization({
+        github_id: 0,
+        name: orgLogin,
+        avatar_url: '',
+      })
+
+      const isInstalled = !!org.installation_id
+      const installationId = org.installation_id?.toString() || null
+
+      return {
+        isInstalled,
+        installationId,
+        permissions: isInstalled ? {
+          contents: 'read',
+          pull_requests: 'read',
+          metadata: 'read'
+        } : {}
+      }
+    } catch (error) {
+      console.error('Error checking installation status:', error)
+      return {
+        isInstalled: false,
+        installationId: null,
+        permissions: {}
+      }
+    }
+  }
+
+  /**
+   * Validate webhook signature
+   */
+  validateWebhookSignature(
+    payload: string,
+    signature: string,
+    secret: string
+  ): boolean {
+    if (!signature || !secret) {
+      return false
+    }
+
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(payload, 'utf8')
+      .digest('hex')
+
+    const expectedSignatureWithPrefix = `sha256=${expectedSignature}`
+
+    // Use crypto.timingSafeEqual to prevent timing attacks
+    if (signature.length !== expectedSignatureWithPrefix.length) {
+      return false
+    }
+
+    return crypto.timingSafeEqual(
+      Buffer.from(signature, 'utf8'),
+      Buffer.from(expectedSignatureWithPrefix, 'utf8')
+    )
+  }
+
+  /**
+   * Process GitHub webhook event
+   */
+  async processWebhookEvent(
+    event: string,
+    payload: any
+  ): Promise<{
+    processed: boolean
+    actions: string[]
+    errors?: string[]
+  }> {
+    const supportedEvents = ['pull_request', 'pull_request_review', 'installation', 'ping']
+    
+    if (!supportedEvents.includes(event)) {
+      return {
+        processed: false,
+        actions: [],
+        errors: [`Unsupported event type: ${event}`]
+      }
+    }
+
+    const actions: string[] = []
+    const errors: string[] = []
+
+    try {
+      switch (event) {
+        case 'pull_request':
+          await this.handlePullRequestWebhook(payload)
+          actions.push(`Processed pull_request.${payload.action}`)
+          break
+          
+        case 'pull_request_review':
+          await this.handlePullRequestReviewWebhook(payload)
+          actions.push(`Processed pull_request_review.${payload.action}`)
+          break
+          
+        case 'installation':
+          await this.handleInstallationWebhook(payload)
+          actions.push(`Processed installation.${payload.action}`)
+          break
+          
+        case 'ping':
+          actions.push('Processed ping event')
+          break
+      }
+
+      return {
+        processed: true,
+        actions,
+        errors: errors.length > 0 ? errors : undefined
+      }
+    } catch (error) {
+      return {
+        processed: false,
+        actions,
+        errors: [error instanceof Error ? error.message : 'Unknown webhook processing error']
+      }
+    }
+  }
+
+  /**
+   * Handle pull request webhook events
+   */
+  private async handlePullRequestWebhook(payload: any): Promise<void> {
+    const { action, repository, pull_request: pr } = payload
+
+    console.log(`[Webhook] Processing PR #${pr.number} action=${action} repo=${repository.full_name}`)
+
+    // Find repository in database
+    const repoInDb = await findRepositoryByFullName(repository.full_name)
+    if (!repoInDb) {
+      console.log(`Repository ${repository.full_name} not tracked, skipping webhook`)
+      return
+    }
+
+    // Map GitHub PR state to our state format
+    const prState = pr.merged_at 
+      ? 'merged' 
+      : pr.state === 'closed' ? 'closed' : 'open'
+
+    // Check if PR exists
+    const existingPR = await findPullRequestByNumber(repoInDb.id, pr.number)
+
+    if (existingPR) {
+      // Update existing PR
+      await updatePullRequest(existingPR.id, {
+        title: pr.title,
+        description: pr.body,
+        state: prState,
+        updated_at: pr.updated_at,
+        closed_at: pr.closed_at,
+        merged_at: pr.merged_at,
+        draft: pr.draft,
+        additions: pr.additions,
+        deletions: pr.deletions,
+        changed_files: pr.changed_files
+      })
+
+      console.log(`[Webhook] Updated PR #${pr.number} in ${repository.full_name}`)
+
+      // Process AI categorization if action is 'opened'
+      if (action === 'opened' && repoInDb.organization_id) {
+        try {
+          await this.fetchAdditionalPRData(repository, pr, existingPR.id, repoInDb.organization_id, payload)
+        } catch (error) {
+          console.error('[Webhook] Error in AI categorization for existing PR:', error)
+        }
+      }
+    } else {
+      // Create new PR
+      console.log(`[Webhook] Creating new PR #${pr.number} in ${repository.full_name}`)
+
+      const author = await findOrCreateUserByGitHubId({
+        id: pr.user.id.toString(),
+        login: pr.user.login,
+        avatar_url: pr.user.avatar_url,
+        name: pr.user.name || pr.user.login
+      })
+
+      if (!author) {
+        console.error(`[Webhook] Could not create user for GitHub ID: ${pr.user.id}`)
+        return
+      }
+
+      const newPR = await createPullRequest({
+        github_id: pr.id,
+        repository_id: repoInDb.id,
+        number: pr.number,
+        title: pr.title,
+        description: pr.body,
+        author_id: author.id,
+        state: prState,
+        created_at: pr.created_at,
+        updated_at: pr.updated_at,
+        closed_at: pr.closed_at,
+        merged_at: pr.merged_at,
+        draft: pr.draft,
+        additions: pr.additions || null,
+        deletions: pr.deletions || null,
+        changed_files: pr.changed_files || null,
+        category_id: null,
+        category_confidence: null
+      })
+
+      console.log(`[Webhook] Created PR #${pr.number} with DB ID ${newPR.id}`)
+
+      // Process AI categorization if action is 'opened'
+      if (action === 'opened' && repoInDb.organization_id) {
+        try {
+          await this.fetchAdditionalPRData(repository, pr, newPR.id, repoInDb.organization_id, payload)
+        } catch (error) {
+          console.error('[Webhook] Error in AI categorization for new PR:', error)
+        }
+      }
+    }
+  }
+
+  /**
+   * Handle pull request review webhook events
+   */
+  private async handlePullRequestReviewWebhook(payload: any): Promise<void> {
+    const { repository, pull_request, review } = payload
+
+    // Find repository and PR
+    const repoInDb = await this.findRepositoryByFullName(repository.full_name)
+    if (!repoInDb) return
+
+    const existingPR = await findPullRequestByNumber(repoInDb.id, pull_request.number)
+    if (!existingPR) return
+
+    // Check if review exists
+    const existingReview = await findReviewByGitHubId(review.id)
+    const reviewState = this.mapReviewState(review.state) as 'approved' | 'changes_requested' | 'commented' | 'dismissed'
+
+    if (existingReview) {
+      // Update review (implementation depends on your updatePullRequestReview function)
+      // await updatePullRequestReview(existingReview.id, { state: reviewState })
+    } else {
+      // Create new review
+      await createPullRequestReview({
+        github_id: review.id,
+        pull_request_id: existingPR.id,
+        reviewer_id: review.user.id.toString(),
+        state: reviewState,
+        submitted_at: review.submitted_at
+      })
+    }
+  }
+
+  /**
+   * Handle installation webhook events
+   */
+  private async handleInstallationWebhook(payload: any): Promise<void> {
+    const { action, installation, repositories } = payload
+    const account = installation.account
+
+    if (account.type !== 'Organization') {
+      console.log(`[Webhook] Skipping installation event for non-organization: ${account.login}`)
+      return
+    }
+
+    const orgGitHubId = account.id
+    const orgLogin = account.login
+    const installationId = installation.id
+    const orgAvatarUrl = account.avatar_url || null
+
+    console.log(`[Webhook] Installation ${action} for org ${orgLogin} (${orgGitHubId}), installation ID: ${installationId}`)
+
+    try {
+      // Find or create organization
+      let org = await OrganizationRepository.findOrganizationByGitHubId(orgGitHubId)
+
+      if (!org && action === 'created') {
+        console.log(`[Webhook] Creating organization ${orgLogin}`)
+        org = await OrganizationRepository.createOrganization({
+          github_id: orgGitHubId,
+          name: orgLogin,
+          avatar_url: orgAvatarUrl
+        })
+        console.log(`[Webhook] Created organization ${orgLogin} with DB ID ${org.id}`)
+      } else if (!org) {
+        console.log(`[Webhook] Organization ${orgLogin} not found for action ${action}`)
+        return
+      }
+
+      if (action === 'created') {
+        // Update with installation ID
+        const updatedOrg = await OrganizationRepository.updateOrganization(org.id, {
+          installation_id: installationId,
+          name: orgLogin,
+          avatar_url: orgAvatarUrl
+        })
+        
+        if (updatedOrg) {
+          console.log(`[Webhook] Stored installation ID ${installationId} for org ${orgLogin}`)
+        } else {
+          console.error(`[Webhook] Failed to update org ${orgLogin} with installation ID`)
+        }
+
+        // Process repositories if provided in payload
+        if (repositories && repositories.length > 0) {
+          console.log(`[Webhook] Processing ${repositories.length} repositories for installation`)
+          
+          for (const repoData of repositories) {
+            try {
+              await findOrCreateRepository({
+                github_id: repoData.id,
+                name: repoData.name,
+                full_name: repoData.full_name,
+                private: repoData.private,
+                organization_id: org.id,
+                description: null,
+                is_tracked: true
+              })
+              console.log(`[Webhook] Added repository ${repoData.full_name} to org ${org.id}`)
+            } catch (repoError) {
+              console.error(`[Webhook] Error adding repository ${repoData.full_name}:`, repoError)
+            }
+          }
+        }
+      } else if (action === 'deleted') {
+        // Clear installation ID
+        const updatedOrg = await OrganizationRepository.updateOrganization(org.id, {
+          installation_id: null
+        })
+        
+        if (updatedOrg) {
+          console.log(`[Webhook] Cleared installation ID for org ${orgLogin}`)
+        } else {
+          console.error(`[Webhook] Failed to clear installation ID for org ${orgLogin}`)
+        }
+      } else if (action === 'suspend') {
+        console.log(`[Webhook] App suspended for org ${orgLogin}`)
+        await OrganizationRepository.updateOrganization(org.id, { installation_id: null })
+      } else if (action === 'unsuspend') {
+        console.log(`[Webhook] App unsuspended for org ${orgLogin}`)
+        await OrganizationRepository.updateOrganization(org.id, { installation_id: installationId })
+      } else {
+        console.log(`[Webhook] Unhandled installation action: ${action}`)
+      }
+    } catch (error) {
+      console.error(`[Webhook] Error handling installation event:`, error)
+      throw error
+    }
+  }
+
+  /**
+   * Fetch additional PR data including AI categorization
+   */
+  private async fetchAdditionalPRData(
+    repository: any, 
+    pr: any, 
+    prDbId: number,
+    organizationId: number,
+    fullPayload?: any
+  ): Promise<void> {
+    console.log(`[Webhook] Fetching additional data for PR #${pr.number} in org ${organizationId}`)
+
+    try {
+      // Get organization details to find installation ID
+      const orgDetails = await findOrganizationById(organizationId)
+      if (!orgDetails) {
+        console.error(`[Webhook] Organization ${organizationId} not found`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'error', 
+          error_message: 'Organization not found' 
+        })
+        return
+      }
+
+      let installationId = orgDetails.installation_id
+      
+      // Fallback to payload installation ID if not in DB
+      if (!installationId) {
+        installationId = fullPayload?.installation?.id || repository?.installation?.id
+      }
+
+      if (!installationId) {
+        console.warn(`[Webhook] No installation ID for org ${organizationId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: 'No GitHub App installation' 
+        })
+        return
+      }
+
+      // Get AI settings
+      const aiSettings = await getOrganizationAiSettings(organizationId)
+      const selectedModelId = aiSettings.selectedModelId
+      
+      if (!selectedModelId || selectedModelId === '__none__') {
+        console.log(`[Webhook] AI categorization disabled for org ${organizationId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: 'AI categorization disabled' 
+        })
+        return
+      }
+
+      const provider = aiSettings.provider
+      if (!provider) {
+        console.log(`[Webhook] AI provider not set for org ${organizationId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: 'AI provider not set' 
+        })
+        return
+      }
+
+      const apiKey = await getOrganizationApiKey(organizationId, provider)
+      if (!apiKey) {
+        console.warn(`[Webhook] API key for ${provider} not set for org ${organizationId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: `API key for ${provider} not set` 
+        })
+        return
+      }
+
+      // Create AI client
+      let aiClientProvider
+      switch (provider) {
+        case 'openai':
+          aiClientProvider = createOpenAI({ apiKey })
+          break
+        case 'google':
+          aiClientProvider = createGoogleGenerativeAI({ apiKey })
+          break
+        case 'anthropic':
+          aiClientProvider = createAnthropic({ apiKey })
+          break
+        default:
+          console.error(`[Webhook] Unsupported AI provider: ${provider}`)
+          await PullRequestRepository.updatePullRequest(prDbId, { 
+            ai_status: 'error', 
+            error_message: `Unsupported AI provider: ${provider}` 
+          })
+          return
+      }
+
+      const modelInstance = aiClientProvider(selectedModelId)
+      if (!modelInstance) {
+        console.error(`[Webhook] Could not get model instance for ${selectedModelId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'error', 
+          error_message: `Could not get AI model instance ${selectedModelId}` 
+        })
+        return
+      }
+
+      // Create GitHub client with installation
+      let githubClient: GitHubClient
+      try {
+        githubClient = await createInstallationClient(installationId)
+        console.log(`[Webhook] Created GitHub client with installation ID ${installationId}`)
+      } catch (error) {
+        console.error(`[Webhook] Failed to create GitHub client:`, error)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'error', 
+          error_message: 'Failed to create GitHub client' 
+        })
+        return
+      }
+
+      // Fetch PR diff
+      let diff: string
+      try {
+        diff = await githubClient.getPullRequestDiff(repository.owner.login, repository.name, pr.number)
+      } catch (error: any) {
+        if (error.message?.includes('expired') || error.message?.includes('invalid') || error.status === 401) {
+          console.warn(`[Webhook] Token expired, retrying with fresh client`)
+          try {
+            githubClient = await createInstallationClient(installationId)
+            diff = await githubClient.getPullRequestDiff(repository.owner.login, repository.name, pr.number)
+          } catch (retryError) {
+            console.error(`[Webhook] Failed to fetch PR diff after retry:`, retryError)
+            await PullRequestRepository.updatePullRequest(prDbId, { 
+              ai_status: 'error', 
+              error_message: 'Failed to fetch PR diff' 
+            })
+            return
+          }
+        } else {
+          console.error(`[Webhook] Failed to fetch PR diff:`, error)
+          await PullRequestRepository.updatePullRequest(prDbId, { 
+            ai_status: 'error', 
+            error_message: 'Failed to fetch PR diff' 
+          })
+          return
+        }
+      }
+
+      if (!diff) {
+        console.warn(`[Webhook] Empty PR diff for ${repository.full_name}#${pr.number}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: 'Empty PR diff' 
+        })
+        return
+      }
+
+      // Get organization categories
+      const orgCategories = await getOrganizationCategories(organizationId)
+      const categoryNames = orgCategories.map(c => c.name)
+      
+      if (categoryNames.length === 0) {
+        console.warn(`[Webhook] No categories for org ${organizationId}`)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'skipped', 
+          error_message: 'No categories configured' 
+        })
+        return
+      }
+
+      // Update PR status to processing
+      await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'processing' })
+
+      // Generate AI categorization
+      const systemPrompt = `You are an expert at categorizing GitHub pull requests. Analyze the pull request title, body, and diff. Respond with the most relevant category from the provided list and a confidence score (0-1). Available categories: ${categoryNames.join(', ')}. Respond in the format: Category: [Selected Category], Confidence: [Score]. Example: Category: Bug Fix, Confidence: 0.9`
+      
+      const userPrompt = `Title: ${pr.title}
+Body: ${pr.body || ''}
+Diff:
+${diff}`
+
+      try {
+        const { text } = await generateText({
+          model: modelInstance,
+          system: systemPrompt,
+          prompt: userPrompt,
+        })
+
+        console.log(`[Webhook] AI Response for PR #${pr.number}: ${text}`)
+
+        // Parse AI response
+        const categoryMatch = text.match(/Category: (.*?), Confidence: (\d\.?\d*)/i)
+        if (categoryMatch && categoryMatch[1] && categoryMatch[2]) {
+          const categoryName = categoryMatch[1].trim()
+          const confidence = parseFloat(categoryMatch[2])
+
+          const category = await findCategoryByNameAndOrg(organizationId, categoryName)
+          if (category) {
+            await updatePullRequestCategory(prDbId, category.id, confidence)
+            await PullRequestRepository.updatePullRequest(prDbId, { ai_status: 'completed' })
+            console.log(`[Webhook] PR #${pr.number} categorized as '${categoryName}' with confidence ${confidence}`)
+          } else {
+            console.warn(`[Webhook] AI suggested category '${categoryName}' not found`)
+            await PullRequestRepository.updatePullRequest(prDbId, { 
+              ai_status: 'error', 
+              error_message: `AI suggested category '${categoryName}' not found` 
+            })
+          }
+        } else {
+          console.warn(`[Webhook] Could not parse AI response: ${text}`)
+          await PullRequestRepository.updatePullRequest(prDbId, { 
+            ai_status: 'error', 
+            error_message: 'Could not parse AI response' 
+          })
+        }
+      } catch (aiError) {
+        console.error('[Webhook] AI text generation failed:', aiError)
+        await PullRequestRepository.updatePullRequest(prDbId, { 
+          ai_status: 'error', 
+          error_message: 'AI text generation failed' 
+        })
+      }
+    } catch (error) {
+      console.error('[Webhook] Error in fetchAdditionalPRData:', error)
+      await PullRequestRepository.updatePullRequest(prDbId, { 
+        ai_status: 'error', 
+        error_message: 'Critical error in AI processing' 
+      })
+    }
+  }
+
+  /**
+   * Helper methods
+   */
+  private mapGitHubPRToDomain(githubPR: any): PullRequest {
+    const state = githubPR.merged_at 
+      ? 'merged' 
+      : githubPR.state === 'closed' ? 'closed' : 'open'
+
+    const createdAt = new Date(githubPR.created_at || Date.now())
+    const mergedAt = githubPR.merged_at ? new Date(githubPR.merged_at) : null
+    const cycleTime = mergedAt ? Math.round((mergedAt.getTime() - createdAt.getTime()) / (1000 * 60 * 60)) : 0 // hours
+
+    return {
+      id: githubPR.id.toString(),
+      number: githubPR.number,
+      title: githubPR.title,
+      developer: {
+        id: githubPR.user.id.toString(),
+        name: githubPR.user.name || githubPR.user.login
+      },
+      repository: {
+        id: githubPR.base?.repo?.id?.toString() || '',
+        name: githubPR.base?.repo?.name || ''
+      },
+      status: state,
+      createdAt: createdAt.toISOString(),
+      mergedAt: mergedAt ? mergedAt.toISOString() : createdAt.toISOString(), // fallback to createdAt for domain compatibility
+      cycleTime,
+      investmentArea: undefined, // To be determined by AI categorization
+      linesAdded: githubPR.additions || 0,
+      files: githubPR.changed_files || 0
+    }
+  }
+
+  private mapReviewState(state: string): 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' {
+    switch (state.toLowerCase()) {
+      case 'approved':
+        return 'APPROVED'
+      case 'changes_requested':
+        return 'CHANGES_REQUESTED'
+      default:
+        return 'COMMENTED'
+    }
+  }
+
+  private async findRepositoryByFullName(fullName: string): Promise<any> {
+    try {
+      return await findRepositoryByFullName && await findRepositoryByFullName(fullName)
+    } catch (error) {
+      return null
+    }
+  }
+
+  private async findOrganizationByGitHubId(githubId: number): Promise<any> {
+    try {
+      return await findOrganizationById && await findOrganizationById(githubId)
+    } catch (error) {
+      return null
+    }
+  }
+}

lib/infrastructure/adapters/turso/index.ts

···
 /**
  * Turso Adapters Index
- * Exports all Turso database adapter implementations
+ * Exports all Turso database adapter implementations with real database queries
  */
 
-// Export simplified production adapters
-export { SimpleTursoPullRequestRepository as TursoPullRequestRepository } from './simple-pr.adapter'
-export { SimpleTursoMetricsService as TursoMetricsService } from './simple-metrics.adapter'
-export { SimpleTursoAuthService as TursoAuthService } from './simple-auth.adapter'
-export { SimpleTursoOrganizationRepository as TursoOrganizationRepository } from './simple-org.adapter'
-export { SimpleTursoRepository as TursoRepository } from './simple-repo.adapter'
+// Export real production adapters that query the database
+export { TursoPullRequestRepository } from './pull-request.adapter'
+export { TursoMetricsService } from './metrics.adapter' 
+export { TursoAuthService } from './auth.adapter'
+export { TursoOrganizationRepository } from './organization.adapter'
+export { TursoRepository } from './repository.adapter'

lib/infrastructure/config/environment.ts

···
     
     const hasGitHubApp = Boolean(
       process.env.GITHUB_APP_ID && 
-      process.env.GITHUB_PRIVATE_KEY
+      process.env.GITHUB_APP_PRIVATE_KEY
     )
     
     // Force demo mode if explicitly set
···
     if (hasGitHubApp) {
       config.github = {
         appId: process.env.GITHUB_APP_ID!,
-        privateKey: process.env.GITHUB_PRIVATE_KEY!,
+        privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
         webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
-        clientId: process.env.GITHUB_CLIENT_ID,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET
+        clientId: process.env.GITHUB_OAUTH_CLIENT_ID,
+        clientSecret: process.env.GITHUB_OAUTH_CLIENT_SECRET
       }
     }