GitHub Channel — Architecture & Roadmap

model ChannelSourceMap {
  id               String    @id @default(cuid())
  tenantId         String
  githubChannelId  String    // ConnectedChannel of type "GitHub"
  targetChannelId  String    // ConnectedChannel of type Website or LandingPage
  repoOwner        String    // GitHub repo owner (user or org)
  repoName         String    // Repository name
  defaultBranch    String    @default("main")
  filePaths        String[]  // Specific file paths to track (e.g. src/pages/index.tsx)
  framework        String?   // Detected on first sync: "nextjs-app" | "nextjs-pages" | "nuxt" | "vue" | "gatsby" | "html"
  webhookId        Int?      // GitHub webhook ID (set in Phase 5)
  webhookSecret    String?   // HMAC secret for webhook verification (encrypted, set in Phase 5)
  extractedAt      DateTime? // When content was last successfully extracted
  lastSyncedAt     DateTime? // When the last sync job completed
  createdAt        DateTime  @default(now())
  updatedAt        DateTime  @updatedAt
 
  tenant        Tenant           @relation(fields: [tenantId], references: [id])
  githubChannel ConnectedChannel @relation("GitHubSourceChannel", fields: [githubChannelId], references: [id])
  targetChannel ConnectedChannel @relation("GitHubTargetChannel", fields: [targetChannelId], references: [id])
  codeChanges   AgentCodeChange[]
 
  @@unique([targetChannelId])   // One source map per target channel
  @@index([tenantId])
  @@index([githubChannelId])
}

model AgentCodeChange {
  id                  String    @id @default(cuid())
  tenantId            String
  sourceMappingId     String
  status              String    // "pending_review" | "approved" | "running" | "pr_opened" | "merged" | "failed" | "cancelled"
  recommendations     Json      // RecommendationItem[] — see types below
  targetFiles         String[]  // File paths the agent will read and potentially modify
  prUrl               String?   // Set when PR is created
  prNumber            Int?
  branchName          String?   // e.g. "leadmetrics/seo-opt-20260423-1430-abc123"
  agentLog            String?   @db.Text  // Streamed log from the coding agent run
  requestedByUserId   String
  approvedByUserId    String?
  approvedAt          DateTime?
  completedAt         DateTime?
  errorMessage        String?
  createdAt           DateTime  @default(now())
  updatedAt           DateTime  @updatedAt
 
  tenant         Tenant           @relation(fields: [tenantId], references: [id])
  sourceMap      ChannelSourceMap @relation(fields: [sourceMappingId], references: [id])
  requestedBy    User             @relation("CodeChangeRequester", fields: [requestedByUserId], references: [id])
  approvedBy     User?            @relation("CodeChangeApprover", fields: [approvedByUserId], references: [id])
 
  @@index([tenantId])
  @@index([sourceMappingId])
  @@index([tenantId, status])
}

type RecommendationItem = {
  text: string                 // The recommendation instruction for the coding agent
  source: RecommendationSource
  targetFilePath?: string      // Which file this applies to (if known at push time)
  priority: "high" | "medium" | "low"
}
 
type RecommendationSource = {
  type: "github-insights"      // From the GitHub AI Insights worker
       | "site-auditor"        // From the Site Auditor deliverable
       | "content-brief"       // From a Content Brief
       | "keyword-researcher"  // From a keyword researcher output
       | "manual"              // Typed by the DM directly
  insightId?: string           // ChannelInsight.id if source is github-insights
  activityId?: string          // Activity.id if source is a deliverable
  contentBriefId?: string      // ContentBrief.id if source is content-brief
}

// packages/db/prisma/seed.ts — add to CHANNEL_CATALOGUE array
{
  type: "GitHub",
  name: "GitHub",
  description: "Map repository source files to landing pages and websites",
  iconKey: "github",
  categories: ["Source Control"],
  authenticationType: "OAuth",
  requiresUrl: false,
  isActive: true,
}

packages/providers/github/
  package.json
  tsconfig.json
  src/
    index.ts          ← exports GitHubService + all types
    types.ts          ← OAuthInfo, GitHubRepo, GitHubTreeEntry, GitHubCommit, etc.
    github.ts         ← GitHubService class

class GitHubService {
  constructor(
    private config: { clientId: string; clientSecret: string },
    private accessToken?: string
  ) {}
 
  // ── OAuth ──────────────────────────────────────────────────────────────────
 
  // Returns the GitHub authorization URL — user is redirected here
  authorize(callbackUrl: string, state: string): string
 
  // Exchanges authorization code for access + refresh tokens
  authorizeCallback(code: string, callbackUrl: string): Promise<OAuthInfo>
 
  // Refreshes an expired access token (GitHub OAuth tokens don't expire by default,
  // but fine-grained tokens can — kept for forward compatibility)
  refreshToken(refreshToken: string): Promise<OAuthInfo>
 
  // Returns the authenticated user's login and display name
  getAuthenticatedUser(): Promise<{ login: string; name: string }>
 
  // ── Repository access ─────────────────────────────────────────────────────
 
  // List all repos accessible to the token (paginated, returns up to 100)
  listRepos(): Promise<GitHubRepo[]>
 
  // Get the default branch name for a repo
  getDefaultBranch(owner: string, repo: string): Promise<string>
 
  // Recursively list all files in a repo tree (flattened — no directories)
  getFileTree(owner: string, repo: string, branch: string): Promise<GitHubTreeEntry[]>
 
  // Fetch decoded content of a single file
  getFileContent(owner: string, repo: string, path: string, branch: string): Promise<string>
 
  // Get recent commits for a file path (for change tracking)
  getCommitHistory(owner: string, repo: string, path: string, limit?: number): Promise<GitHubCommit[]>
 
  // Get repo-level stats returned in the analytics endpoint
  getRepoStats(owner: string, repo: string): Promise<GitHubRepoStats>
 
  // ── Code write-back (used by coding agent) ────────────────────────────────
 
  // Create a new branch from the tip of baseBranch
  createBranch(owner: string, repo: string, branchName: string, baseBranch: string): Promise<void>
 
  // Create or update a file on a branch (handles base64 encoding + SHA for updates)
  putFile(owner: string, repo: string, path: string, branch: string, content: string, message: string): Promise<void>
 
  // Open a pull request
  createPR(owner: string, repo: string, params: CreatePRParams): Promise<{ number: number; url: string }>
 
  // ── Webhooks (Phase 5) ────────────────────────────────────────────────────
 
  createWebhook(owner: string, repo: string, callbackUrl: string, secret: string): Promise<{ id: number }>
  deleteWebhook(owner: string, repo: string, webhookId: number): Promise<void>
  verifyWebhookSignature(payload: string, signature: string, secret: string): boolean
}

type OAuthInfo = {
  accessToken: string
  refreshToken?: string
  expireOn?: string
  scope: string
}
 
type GitHubRepo = {
  owner: string
  name: string
  fullName: string          // "owner/repo"
  defaultBranch: string
  isPrivate: boolean
  pushedAt: string          // ISO date
}
 
type GitHubTreeEntry = {
  path: string
  type: "blob" | "tree"
  size?: number
}
 
type GitHubCommit = {
  sha: string
  message: string
  authorName: string
  committedAt: string
}
 
type GitHubRepoStats = {
  openPRs: number
  commitCount30d: number
  lastPushedAt: string
}
 
type CreatePRParams = {
  head: string              // branch name
  base: string              // target branch (usually "main")
  title: string
  body: string
}

case "GitHub": {
  const token = decrypt(channel.tokenInfo).accessToken
  const svc = new GitHubService(config, token)
  const stats = await svc.getRepoStats(subChannelInfo.owner, subChannelInfo.repo)
  const maps = await db.channelSourceMap.findMany({ where: { githubChannelId: id } })
  const pendingChanges = await db.agentCodeChange.count({
    where: { sourceMappingId: { in: maps.map(m => m.id) }, status: "pending_review" }
  })
  return { stats, sourceMaps: maps, pendingChanges }
}

1. User opens Channels page → clicks "Connect GitHub"
2. ConnectDialog: user enters display name → clicks "Connect"
   → ConnectDialog calls GET /tenant/v1/channel-connect/github/connect
   → Opens OAuth popup window pointing to GitHub authorization URL
3. GitHub authorization page:
   → User reviews requested scopes (repo + admin:repo_hook)
   → User clicks "Authorize Leadmetrics"
4. GitHub redirects to /github/callback with code
   → Route exchanges code for access token via GitHub token endpoint
   → Saves encrypted tokenInfo + userInfo on ConnectedChannel
   → Redirects popup to /github/repo/select?state={channelId}
5. Repo selection page (inside popup):
   → Lists all repos the token can access
   → User selects one repo
   → POST /github/repo/select saves subChannelInfo{owner, repo, defaultBranch}
   → isConnected = true, connectionHistory entry written
   → Popup posts message to parent window → popup closes
6. ConnectDialog detects popup closed → navigates to GitHub channel detail page
7. User opens "Source Maps" tab → clicks "Add Source Map"
8. Source map modal:
   a. "Target page" — dropdown of all Website/LandingPage channels for the tenant
   b. "Repository" — pre-filled from subChannelInfo (or dropdown if user wants a different repo)
   c. "Branch" — pre-filled with defaultBranch
   d. "Files" — tree browser loaded from GET /channels/:id/repos/:owner/:repo/tree
      User selects one or more files (e.g. src/pages/index.tsx, src/pages/pricing.tsx)
9. User confirms → POST /tenant/v1/source-maps
   → ChannelSourceMap created
   → github-source-sync job enqueued immediately (first sync, framework detection)
10. Sync completes → framework stored on ChannelSourceMap → extracted content in RAG

1. Load ChannelSourceMap by sourceMappingId
2. Load ConnectedChannel (githubChannelId) — decrypt tokenInfo → accessToken
   → Refresh token if expireOn is within 5 minutes
3. Instantiate GitHubService with refreshed token
4. If ChannelSourceMap.framework is null (first sync):
   → Fetch root file tree
   → Detect framework by checking for config files (next.config.*, nuxt.config.*,
     gatsby-config.*, vite.config.*) and directory structure (app/ vs pages/)
   → Set ChannelSourceMap.framework
5. For each path in sourceMap.filePaths:
   a. Fetch file content via getFileContent(owner, repo, path, branch)
   b. Determine extraction strategy from file extension + detected framework
   c. Extract semantic content (see Content Extraction section below)
   d. Build ExtractedPageContent record
6. Ingest each ExtractedPageContent into the RAG pipeline
   → dataset type: "github-source", document ID: `${sourceMappingId}:${filePath}` (upsert)
7. Update ChannelSourceMap.lastSyncedAt = now(), extractedAt = now()
8. enqueueNotification() → DM: "Source sync complete for [channel title]"

1. Load ConnectedChannel — decrypt tokenInfo
2. Load all ChannelSourceMap records for this channel
3. For each source map → load ExtractedPageContent from RAG store
4. Load tenant's active keywords (keyword-researcher output)
5. Build Claude prompt:
   System: "You are an SEO analyst reviewing a client's actual page source code.
            Identify gaps between the current content and the target keywords.
            Return structured JSON only."
   User: { pages: ExtractedPageContent[], keywords: string[] }
6. Parse Claude JSON → SWOT structure:
   {
     strengths: string[],
     weaknesses: string[],
     opportunities: string[],
     recommendations: RecommendationItem[],  // includes priority + targetFilePath
     summary: string
   }
7. Store as ChannelInsight record (same model as all other insight workers)

const tools = [
  {
    name: "read_file",
    description: "Read the current content of a source file from the repository",
    input_schema: { type: "object", properties: { path: { type: "string" } } }
  },
  {
    name: "list_directory",
    description: "List files in a directory of the repository",
    input_schema: { type: "object", properties: { path: { type: "string" } } }
  },
  {
    name: "write_file",
    description: "Stage an updated version of a file. Call this once per file with the complete new content.",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" },
        reason: { type: "string" }   // brief explanation of what changed and why
      }
    }
  },
  {
    name: "create_pr",
    description: "Create a pull request with all staged file changes. Call this once when done.",
    input_schema: {
      type: "object",
      properties: {
        title: { type: "string" },
        body: { type: "string" }
      }
    }
  }
]

1. Load AgentCodeChange (codeChangeId) — verify status is "approved"
2. Load ChannelSourceMap → githubChannelId → ConnectedChannel → decrypt tokenInfo
3. Refresh token if needed
4. Set AgentCodeChange.status = "running", log start timestamp
5. Instantiate GitHubService with fresh token
6. Create branch: "leadmetrics/seo-opt-{YYYYMMDD-HHmm}-{codeChangeId.slice(0,6)}"
   → Store branchName on AgentCodeChange
7. Build system prompt for Claude:
   - Framework: {ChannelSourceMap.framework}
   - Repo: {owner}/{repo}, branch: {branchName}
   - Target files: {codeChange.targetFiles}
   - The following SEO and content optimizations have been approved by the DM.
     Apply all of them. Make deep structural changes where needed — you may add
     new sections, new components, new JSON-LD blocks, rewrite headings and paragraphs.
     Do not change functionality, routing, or styling.
   - Recommendations (numbered list): {codeChange.recommendations}
8. Start Claude tool use loop:
   a. Send messages to Claude with tools defined above
   b. For each tool call Claude makes:
      - read_file → call GitHubService.getFileContent() → return content to Claude
      - list_directory → call GitHubService.getFileTree() filtered to path → return to Claude
      - write_file → call GitHubService.putFile() on the new branch → append to agentLog
      - create_pr → call GitHubService.createPR() → store prUrl + prNumber → break loop
   c. Append each tool call + result to AgentCodeChange.agentLog (streaming update)
   d. Stop when Claude calls create_pr or when message count exceeds 40 (safety limit)
9. Update AgentCodeChange:
   - status = "pr_opened"
   - prUrl, prNumber set
   - completedAt = now()
10. enqueueNotification() → DM: "PR ready for review: {prTitle}" with prUrl

## SEO & Content Optimization — Generated by Leadmetrics
 
This PR was generated by the Leadmetrics coding agent based on DM-approved recommendations.
 
### Changes Applied
 
{numbered list of recommendations with source attribution}
 
### Review Checklist
 
- [ ] Review each file diff and confirm copy aligns with brand voice
- [ ] Check that no functionality, routing, or styling was altered
- [ ] Verify all new structured data (JSON-LD) is valid
- [ ] Merge when satisfied — Leadmetrics will auto-sync on merge
 
---
*Generated {date} · Requested by {requestedByName} · Approved by {approvedByName}*
*[View in Leadmetrics]({dashboardUrl}/channels/{githubChannelId})*

type ExtractedPageContent = {
  filePath: string
  fileType: "html" | "tsx" | "jsx" | "vue" | "md" | "mdx"
  title: string | null
  metaDescription: string | null
  ogTitle: string | null
  ogDescription: string | null
  headings: { level: 1 | 2 | 3 | 4 | 5 | 6; text: string }[]
  structuredData: object[]        // JSON-LD blocks parsed from the file
  bodyText: string                // stripped prose, whitespace-collapsed
  wordCount: number
  extractedAt: string             // ISO date
}