ameyasingh23/inline_explainer

1. Repository shape

- This is a two-app monorepo: apps/web is the Next.js frontend and apps/api is the FastAPI backend.

- The project is centered on one workflow: a user submits a public repo URL, the backend analyzes the repo structure, and the frontend presents an IDE-like workspace with code, explanations, and chat.

2. Frontend boundary: workspace and presentation

- apps/web owns all browser UX: landing page, GitHub login, repo workspace, profile/account pages, privacy/terms.

- The main architecture surface is the workspace route app/(workspace)/[owner]/[repo], which renders a file tree, code viewer, explanation panel, and chat tray side by side.

- WorkspaceShell, FileTree, CodePanel, ExplanationPanel, and ChatTray are the core UI composition units.

3. Frontend state and session management

- Supabase is used on the web side for auth/session handling via lib/supabase/client.ts, lib/supabase/server.ts, and middleware.ts.

- useChatSession.ts owns chat session state, streaming message handling, and persistence across reloads.

- The browser also performs some direct data access patterns, such as loading repo/file structure and auth state, while the backend handles analysis and AI generation.

4. Backend boundary: analysis, explanation, and chat

- apps/api is the authoritative service for repo ingestion, graph extraction, explanation generation, chat responses, user profile/repo listing, and account deletion.

- The backend is split into routers by concern: ingest.py, explain.py, chat.py, and user.py.

- Shared cross-cutting concerns live in core/: config loading, JWT auth verification, rate limiting, and Supabase access.

5. Repo ingestion pipeline

- POST /api/ingest is the backend entry point for analyzing a public repository.

- repo_service.py clones the repo with GitPython, validates it, and runs Graphify/tree-sitter extraction to build a code graph.

- That graph is stored in Supabase as graph_json on the repositories record, along with repository metadata and processing status.

- This is the system’s main offline-like processing step, but it happens on demand through the API.

6. Explanation pipeline

- POST /api/explain generates a file-level explanation as a streaming SSE response.

- The backend combines the target file with connected graph context: imports, callers, callees, and nearby related files.

- Explanations are persisted in Supabase so revisiting a file can load cached output immediately without re-running the model.

7. Chat pipeline

- POST /api/chat is the conversational interface for follow-up questions.

- The frontend supports two chat scopes: repo-level chat and file-level chat.

- Repo chat uses repository context such as README and file tree; file chat uses the selected file code, its explanation, and optional selected text from the editor or explanation panel.

- GET /api/chat/session restores persisted conversation history for a file.

8. Data model and persistence boundary

- Supabase Postgres is the main persistent store for repositories, explanations, chat_sessions, and users.

- repositories stores repo identity plus the extracted graph.

- explanations caches generated explanations per repository/file.

- chat_sessions stores message history keyed by repository and file.

- users links app identity to Supabase Auth users and GitHub identity.

9. Authentication and trust model

- GitHub OAuth is handled through Supabase Auth on the frontend.

- The backend does not share auth secrets with the frontend; it verifies Supabase JWTs using JWKS in core/auth.py.

- Every backend endpoint in the main API path expects a bearer token, which makes the browser-to-backend and backend-to-Supabase trust boundaries explicit.

10. Model/provider layer

- The backend routes LLM requests through a multi-provider waterfall router.

- The repository design mentions Groq, Google Gemini, and NVIDIA NIM as fallback providers.

- This provider abstraction matters architecturally because the frontend never talks directly to model APIs; all model selection and fallback behavior stays behind the backend.

11. Cross-cutting controls

- core/rate_limiter.py applies per-user, per-endpoint limits with different caps for ingest, explain, and chat.

- Cache hits do not count against rate limits, which means the system distinguishes expensive generation from cheap retrieval.

- psutil is used during ingestion to monitor memory use, reflecting that repo analysis is the most resource-sensitive backend path.

12. External integrations and deployment

- Supabase provides auth, Postgres, and likely row-level security for user data.

- The frontend is designed for Vercel deployment, while the backend is designed for Render.

- The browser also relies on GitHub’s public repository APIs for file tree navigation in the workspace.

- A health endpoint exists to support uptime/cold-start mitigation for the backend.

13. What to show in an architecture diagram

- The clearest diagram should separate: browser/UI, FastAPI API, Supabase, and external model/repo services.

- The key flows are:

- login/session via Supabase Auth,

- repo ingest from browser to backend to Supabase,

- file explanation from browser to backend to LLM provider to Supabase cache,

- chat from browser to backend to LLM provider with persisted session state in Supabase.

- The central architectural idea is that the frontend is a thin interactive workspace, while the backend owns analysis, caching, auth verification, and all AI calls.