# ameyasingh23/inline_explainer architecture

> Architecture diagram of the GitHub repository ameyasingh23/inline_explainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ameyasingh23/inline_explainer
- Repository: https://github.com/ameyasingh23/inline_explainer

## Overview

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.

Main entry points: [`apps/web/components/workspace/WorkspaceShell.tsx`](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/WorkspaceShell.tsx) (WorkspaceShell), [`apps/api/routers/explain.py`](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/explain.py) (Explain router), [`apps/api/routers/chat.py`](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/chat.py) (Chat router), [`apps/api/main.py`](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web App"]
  node_web_home["Home<br/>next route<br/>[page.tsx]"]
  node_web_login["Login<br/>auth route<br/>[page.tsx]"]
  node_web_workspace["Workspace<br/>[page.tsx]"]
  node_web_shell["WorkspaceShell<br/>ui shell<br/>[WorkspaceShell.tsx]"]
  node_web_tree["FileTree<br/>repo navigator<br/>[FileTree.tsx]"]
  node_web_code["CodePanel<br/>code viewer<br/>[CodePanel.tsx]"]
  node_web_explain["ExplanationPanel<br/>explanation UI"]
  node_web_chat["ChatTray<br/>chat UI<br/>[ChatTray.tsx]"]
  node_web_chat_state["useChatSession<br/>chat state<br/>[useChatSession.ts]"]
  node_web_auth["Supabase client<br/>auth/session<br/>[client.ts]"]
  node_web_auth_server["Supabase server<br/>auth/session<br/>[server.ts]"]
  node_web_middleware["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_api["API Service"]
  node_api_main["FastAPI app<br/>api entrypoint<br/>[main.py]"]
  node_api_ingest["Ingest router<br/>ingest api<br/>[ingest.py]"]
  node_api_explain["Explain router<br/>explain api<br/>[explain.py]"]
  node_api_chat["Chat router<br/>chat api<br/>[chat.py]"]
  node_api_user["User router<br/>user api<br/>[user.py]"]
  node_api_repo["Repo service<br/>ingestion pipeline<br/>[repo_service.py]"]
  node_api_core["Core controls<br/>auth/rate/cache"]
end

subgraph group_external["External Services"]
  node_ext_supabase[("Supabase<br/>auth+postgres")]
  node_ext_github[("GitHub<br/>source repos")]
  node_ext_models(("LLM providers<br/>model waterfall"))
end

node_web_home -->|"sign in"| node_web_login
node_web_login -->|"start session"| node_web_auth
node_web_auth_server -->|"session lookup"| node_ext_supabase
node_web_middleware -->|"gate routes"| node_web_auth
node_web_workspace -->|"compose"| node_web_shell
node_web_shell -->|"layout"| node_web_tree
node_web_shell -->|"layout"| node_web_code
node_web_shell -->|"layout"| node_web_explain
node_web_shell -->|"layout"| node_web_chat
node_web_chat -->|"state"| node_web_chat_state
node_web_workspace -->|"analyze repo"| node_api_ingest
node_web_workspace -->|"explain file"| node_api_explain
node_web_chat -->|"ask"| node_api_chat
node_web_tree -->|"browse source"| node_ext_github
node_api_main -->|"mount"| node_api_ingest
node_api_main -->|"mount"| node_api_explain
node_api_main -->|"mount"| node_api_chat
node_api_main -->|"mount"| node_api_user
node_api_ingest -->|"pipeline"| node_api_repo
node_api_ingest -->|"guard"| node_api_core
node_api_explain -->|"guard"| node_api_core
node_api_chat -->|"guard"| node_api_core
node_api_user -->|"guard"| node_api_core
node_api_repo -->|"clone"| node_ext_github
node_api_repo -->|"store graph"| node_ext_supabase
node_api_explain -->|"generate"| node_ext_models
node_api_chat -->|"respond"| node_ext_models
node_api_explain -->|"cache"| node_ext_supabase
node_api_chat -->|"session store"| node_ext_supabase
node_api_user -->|"profiles"| node_ext_supabase

click node_web_home "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/page.tsx"
click node_web_login "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/(auth)/login/page.tsx"
click node_web_workspace "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/(workspace)/[owner]/[repo]/page.tsx"
click node_web_shell "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/WorkspaceShell.tsx"
click node_web_tree "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/FileTree.tsx"
click node_web_code "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/CodePanel.tsx"
click node_web_explain "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/ExplanationPanel.tsx"
click node_web_chat "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/ChatTray.tsx"
click node_web_chat_state "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/hooks/useChatSession.ts"
click node_web_auth "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/lib/supabase/client.ts"
click node_web_auth_server "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/lib/supabase/server.ts"
click node_web_middleware "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/middleware.ts"
click node_api_main "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/main.py"
click node_api_ingest "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/ingest.py"
click node_api_explain "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/explain.py"
click node_api_chat "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/chat.py"
click node_api_user "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/user.py"
click node_api_repo "https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/services/repo_service.py"
click node_api_core "https://github.com/ameyasingh23/inline_explainer/tree/main/apps/api/core"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_home,node_web_login,node_web_workspace,node_web_shell,node_web_tree,node_web_code,node_web_explain,node_web_chat,node_web_chat_state,node_web_auth,node_web_auth_server,node_web_middleware toneBlue
class node_api_main,node_api_ingest,node_api_explain,node_api_chat,node_api_user,node_api_repo,node_api_core toneAmber
class node_ext_supabase,node_ext_github,node_ext_models toneMint
```

## Components

### Web App

Next.js frontend for auth, workspace, and account UX

- [Home](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/page.tsx): next route · Landing entry for the app · `apps/web/app/page.tsx`
- [Login](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/(auth)/login/page.tsx): auth route · GitHub sign-in entry · `apps/web/app/(auth)/login/page.tsx`
- [Workspace](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/app/(workspace)/[owner]/[repo]/page.tsx): workspace route · Main repo workspace view · `apps/web/app/(workspace)/[owner]/[repo]/page.tsx`
- [WorkspaceShell](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/WorkspaceShell.tsx): ui shell · Coordinates the split-pane workspace · `apps/web/components/workspace/WorkspaceShell.tsx`
- [FileTree](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/FileTree.tsx): repo navigator · Shows repository structure and file selection · `apps/web/components/workspace/FileTree.tsx`
- [CodePanel](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/CodePanel.tsx): code viewer · Displays source code and selections · `apps/web/components/workspace/CodePanel.tsx`
- [ExplanationPanel](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/ExplanationPanel.tsx): explanation UI · Renders file explanations and cached content · `apps/web/components/workspace/ExplanationPanel.tsx`
- [ChatTray](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/components/workspace/ChatTray.tsx): chat UI · Repo and file scoped chat interface · `apps/web/components/workspace/ChatTray.tsx`
- [useChatSession](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/hooks/useChatSession.ts): chat state · Streams and persists chat history · `apps/web/hooks/useChatSession.ts`
- [Supabase client](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/lib/supabase/client.ts): auth/session · Browser session and middleware auth plumbing · `apps/web/lib/supabase/client.ts`
- [Supabase server](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/lib/supabase/server.ts): auth/session · Server-side auth/session helpers · `apps/web/lib/supabase/server.ts`
- [Middleware](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/web/middleware.ts): route guard · Protects workspace and session routes · `apps/web/middleware.ts`

### API Service

FastAPI backend for ingestion, explanation, chat, and user data

- [FastAPI app](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/main.py): api entrypoint · API application wiring and startup · `apps/api/main.py`
- [Ingest router](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/ingest.py): ingest api · Public repo analysis endpoint · `apps/api/routers/ingest.py`
- [Explain router](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/explain.py): explain api · Streaming file explanation endpoint · `apps/api/routers/explain.py`
- [Chat router](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/chat.py): chat api · Repo and file chat endpoints · `apps/api/routers/chat.py`
- [User router](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/routers/user.py): user api · Profile, repo listing, and account deletion · `apps/api/routers/user.py`
- [Repo service](https://github.com/ameyasingh23/inline_explainer/blob/main/apps/api/services/repo_service.py): ingestion pipeline · Clones, validates, and builds code graphs · `apps/api/services/repo_service.py`
- [Core controls](https://github.com/ameyasingh23/inline_explainer/tree/main/apps/api/core): auth/rate/cache · JWT verification, rate limits, config, and Supabase access · `apps/api/core`

### External Services

Auth, storage, source repos, and model providers

- **Supabase**: auth+postgres · Auth, Postgres storage, and cached app data
- **GitHub**: source repos · Public repositories used for ingestion and file navigation
- **LLM providers**: model waterfall · Fallback generation providers for explanations and chat

## Connections

- Home → Login: sign in · Users move from landing to authentication
- Login → Supabase client: start session · Client-side Supabase auth flow
- Supabase server → Supabase: session lookup · Server-side session validation and user data access
- Middleware → Supabase client: gate routes · Protects authenticated workspace pages
- Workspace → WorkspaceShell: compose · Workspace page renders the main shell
- WorkspaceShell → FileTree: layout · File tree occupies the navigation pane
- WorkspaceShell → CodePanel: layout · Code viewer occupies the editor pane
- WorkspaceShell → ExplanationPanel: layout · Explanation panel sits beside code
- WorkspaceShell → ChatTray: layout · Chat tray anchors the conversation area
- ChatTray → useChatSession: state · Chat UI delegates session persistence and streaming
- Workspace → Ingest router: analyze repo · Workspace triggers repository ingestion when needed
- Workspace → Explain router: explain file · Workspace requests file explanations
- ChatTray → Chat router: ask · Chat UI sends repo or file scoped prompts
- FileTree → GitHub: browse source · Browser uses public GitHub data for navigation
- FastAPI app → Ingest router: mount · Registers the ingest router
- FastAPI app → Explain router: mount · Registers the explain router
- FastAPI app → Chat router: mount · Registers the chat router
- FastAPI app → User router: mount · Registers the user router
- Ingest router → Repo service: pipeline · Ingest delegates clone and graph extraction
- Ingest router → Core controls: guard · Applies auth, config, and rate limits
- Explain router → Core controls: guard · Uses shared auth and rate-limit controls
- Chat router → Core controls: guard · Uses shared auth and rate-limit controls
- User router → Core controls: guard · Uses shared auth and data access helpers
- Repo service → GitHub: clone · Fetches public repositories for analysis
- Repo service → Supabase: store graph · Persists repository metadata and graph JSON
- Explain router → LLM providers: generate · Streams file explanations from model providers
- Chat router → LLM providers: respond · Generates conversational answers through provider fallback
- Explain router → Supabase: cache · Caches generated explanations for reuse
- Chat router → Supabase: session store · Persists and restores chat history
- User router → Supabase: profiles · Reads and updates user and repository records