lilysu/schemata

1. Overall shape

- This is a hybrid monorepo centered on a Next.js 16 frontend, with an optional FastAPI backend in backend/.

- The product’s core function is to take a GitHub repository URL/owner-repo pair, fetch repository structure, generate a diagram, and let users drill into subdirectories recursively.

2. Frontend application boundary

- The main user-facing app lives under src/app/ and src/components/.

- Next.js route handlers under src/app/api/... can serve generation, cost, health, and prefetch requests.

- The frontend can also be configured to call the external FastAPI backend instead of its local handlers via environment flags, which makes the architecture split between “embedded backend” and “legacy/external backend” modes.

3. Diagram generation pipeline

- The diagram pipeline is intentionally hybrid:

- deterministic repo analysis first,

- then one LLM streaming pass for edges/relationships.

- The deterministic layer lives in src/server/generate/analyzer.ts and produces nodes, groups, and inferred structure immediately from the repo file tree.

- The LLM layer then adds semantic relationships and missing components, which reduces token usage and avoids multi-stage generation.

4. Streaming request flow

- The main generation path is exposed by src/app/api/generate/stream/route.ts on the frontend side and backend/app/routers/generate.py on the FastAPI side.

- The UI consumes streamed output through the diagram hooks in src/hooks/diagram/ and src/hooks/useDiagram.ts.

- This means the diagram can render progressively: nodes appear first, then edges and explanation stream in.

5. Recursive background prefetch

- A distinctive subsystem is the prefetch pipeline in src/app/api/generate/prefetch/route.ts.

- After a diagram loads, the frontend identifies directory nodes and pre-generates child diagrams in the background.

- This recursion continues down the tree, so drill-down views are often already cached before the user clicks them.

6. Caching and persistence

- Generated diagrams are cached in Supabase PostgreSQL via Drizzle ORM, with schema in src/server/db/schema.ts.

- The README describes two main caches: one for top-level repo diagrams and one for sub-diagrams keyed by directory/file scope.

- This cache is a major architectural boundary: once populated, it eliminates repeat LLM calls for the same repo scope.

7. GitHub data access

- Repository structure and README content are fetched through GitHub-specific services in src/server/generate/github.ts and mirrored in backend backend/app/services/github_service.py.

- GitHub authentication can use a PAT or GitHub App credentials, which matters because rate limits and access to private repos affect the fetch layer.

- This layer is upstream of both deterministic analysis and LLM generation.

8. AI provider abstraction

- The model/provider layer is centralized in src/server/generate/provider.ts, model-config.ts, and prompts.ts, with parallel backend equivalents under backend/app/services/.

- The app supports direct provider calls to OpenAI, Anthropic, or Google, and optionally routes through Vercel AI Gateway.

- This abstraction matters because the rest of the app treats the model as pluggable, while prompts and fallback model selection remain centralized.

9. UI rendering and interaction

- Diagram visualization is handled by React Flow in src/components/flow-diagram.tsx and the node components under src/components/flow-nodes/.

- The diagram is not just static output: nodes are interactive, clickable, and support drill-down navigation into directories and source files.

- The UI layer also includes export, copy, breadcrumbs, dialogs, theme controls, and repo-specific actions that wrap the core graph.

10. Domain logic in hooks and feature modules

- Diagram-specific domain logic is concentrated in src/features/diagram/ and src/hooks/diagram/.

- These modules handle GitHub URL parsing, SSE/event streaming, export formatting, diagram state transitions, and drill-down behavior.

- This keeps the UI components relatively presentational and pushes orchestration into reusable client-side logic.

11. Backend FastAPI service

- The Python backend mirrors the core generation responsibilities: routing, GitHub access, prompt definitions, model configuration, pricing, and observability.

- It includes its own tests under backend/tests/, Nginx setup, and Docker entrypoints, suggesting it is deployable as a standalone API service.

- In practice, this backend acts as the production-grade or legacy service path, while the Next.js app can also operate with local route handlers.

12. Operational and deployment boundaries

- The repo includes GitHub Actions for CI and deployment, plus Docker Compose for local full-stack runs.

- Supabase is the persistence layer, GitHub is the source-of-truth data source, and LLM providers are the external compute layer.

- The architectural picture is therefore: browser UI → Next.js/FastAPI API → GitHub + LLM provider → Supabase cache → streamed diagram back to the client, with recursive prefetch expanding the cached graph in the background.