Architecture Deep Dive

┌─────────────────────────────────────────────┐
│           Frontend (Cloudflare Workers)      │
│  TanStack Start + Router + shadcn/ui        │
└──────────────┬──────────────────────────────┘
               │ Convex WebSocket
┌──────────────▼──────────────────────────────┐
│           Backend (Convex Cloud)             │
│  Queries, Mutations, Actions, Workflows     │
├─────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────┐          │
│  │  Database   │  │  File Store  │          │
│  └─────────────┘  └──────────────┘          │
│  ┌─────────────┐  ┌──────────────┐          │
│  │ RAG/Vector  │  │  Workflows   │          │
│  └─────────────┘  └──────────────┘          │
└──────────────┬──────────────────────────────┘
               │
┌──────────────▼──────────────────────────────┐
│        External APIs                         │
│  GitHub API • Gemini AI • Embeddings        │
└─────────────────────────────────────────────┘

packages/backend/convex/
├── schema.ts               # Database schema
├── auth.ts, auth.config.ts # Better Auth setup
├── repos.ts                # Repository queries/mutations
├── architectureEntities.ts # Entity queries
├── issues.ts               # Issue analysis
├── pullRequests.ts         # PR analysis
├── chat.ts                 # Chat queries/mutations
├── gemini.ts               # All AI generation
├── github.ts               # GitHub API actions
├── prompts.ts              # AI prompts
├── aiValidation.ts         # Zod schemas
├── workflows/
│   └── analyzeRepository.ts # 11-step workflow
└── agent/
    ├── codebaseAgent.ts    # Agent setup
    └── tools.ts            # 9 agent tools

1. validateRepository()     // Check GitHub API
2. handleReIndex()          // Clear old data if re-index
3. fetchFileTree()          // Get all file paths
4. calculateIterations()    // Based on repo size
5. ingestToRAG()           // Embed top 500 files
6. generateSummary()       // 300-word overview
7. discoverArchitecture()  // 2-5 iterations
8. consolidateEntities()   // Filter to top 5-15
9. generateDiagrams()      // Mermaid + narrative
10. analyzeIssues()        // Fetch & analyze issues
11. analyzePRs()           // Fetch & analyze PRs

for (let i = 0; i < iterationCount; i++) {
  // Get context from previous iterations
  const previousContext = await getPreviousEntities(ctx, repoId);

  // Ask AI to discover more specific components
  const newEntities = await discoverIteration(
    fileTree,
    previousContext,
    iterationNumber: i + 1
  );

  // Save to database
  await saveEntities(ctx, repoId, newEntities);
}

// packages/backend/convex/github.ts
export const ingestRepository = action({
  handler: async (ctx, { fullName }) => {
    // 1. Fetch file tree from GitHub
    const files = await fetchFileTree(fullName);

    // 2. Filter to top 500 files (by size, extension)
    const topFiles = filterRelevantFiles(files);

    // 3. Chunk and embed
    for (const file of topFiles) {
      const content = await fetchFileContent(file.path);
      await ctx.vectorSearch("rag", `repo:${fullName}`).add({
        text: content,
        metadata: { path: file.path }
      });
    }
  }
});

// agent/tools.ts
const results = await ctx.vectorSearch("rag", `repo:${fullName}`)
  .search(query, { limit: 5 });

export const generateSummary = action({
  handler: async (ctx, { fileTree, metadata }) => {
    const response = await generateObject({
      model: gemini("gemini-2.5-flash-exp"),
      schema: SummarySchema,
      prompt: SUMMARY_PROMPT.replace("{FILE_TREE}", fileTree)
    });
    return response.object.summary;
  }
});

const ArchitectureEntitySchema = z.object({
  name: z.string().min(1),
  description: z.string().min(50),
  importance: z.number().min(0).max(1),
  layer: z.enum(["entry-point", "core", "feature", "utility", "integration"]),
  path: z.string()
});

apps/web/src/routes/
├── __root.tsx              # Root layout (header, auth)
├── index.tsx               # Home page
├── _github/                # GitHub layout
│   └── $owner_.$repo/      # Repo layout
│       ├── index.tsx       # Summary tab
│       ├── arch/           # Architecture
│       │   ├── index.tsx   # Entity list
│       │   └── $slug.tsx   # Entity detail
│       ├── issues/
│       │   ├── index.tsx   # Issue list
│       │   └── $number.tsx # Issue detail
│       ├── pr/
│       │   ├── index.tsx   # PR list
│       │   └── $number.tsx # PR detail
│       └── chat/
│           ├── index.tsx   # New chat
│           └── $chatId.tsx # Chat thread

const convex = new ConvexClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convex);

export const router = createRouter({
  context: {
    queryClient: new QueryClient(),
    convexReactClient: convex,
    convexQueryClient
  }
});

// Reactive query (auto-subscribes)
const repo = useQuery(api.repos.getByFullName, { fullName });

// Mutation (one-off)
const startAnalysis = useMutation(api.repos.startAnalysis);

// Action (async)
const getOwnerInfo = useAction(api.github.getOwnerInfo);

if (!repo) return <Skeleton />;
if (repo.status === "processing") return <ProgressIndicator />;
return <RepoContent repo={repo} />;

{repo.summary && <SummaryCard summary={repo.summary} />}
{repo.entities && <ArchitectureList entities={repo.entities} />}
{repo.diagram && <MermaidDiagram code={repo.diagram} />}

// Backend
await ctx.runMutation(internal.repos.updateSummary, { summary });
// Frontend sees update immediately via Convex subscription

await ctx.runMutation(internal.repos.updateArchitecture, { entities });
// Frontend sees architecture!

const repo = await ctx.db
  .query("repositories")
  .withIndex("by_fullName_lower", (q) =>
    q.eq("fullNameLower", fullName.toLowerCase())
  )
  .first();

const validPath = fileTree.some(f => f.path === llmPath);
if (!validPath) {
  console.warn("Invalid path from LLM:", llmPath);
  return null; // Skip invalid entity
}