# funshothanni/marginalia architecture

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

- Interactive diagram: https://gitdiagram.com/funshothanni/marginalia
- Repository: https://github.com/funshothanni/marginalia

## Overview

marginalia is a study assistant for organizing course PDFs and asking questions grounded in their content. The main workflow is sign in, select a subject, upload a PDF for ingestion, then ask questions in persistent chats and revisit chat history. The graph includes the documented subject/document/chat capabilities and the sampled retrieval and ingestion paths. Some UI-to-API wiring and external AI-provider details were not shown, so those relationships are omitted rather than inferred.

Main entry points: [`src/lib/db.ts`](https://github.com/funshothanni/marginalia/blob/main/src/lib/db.ts) (Data access), [`src/lib/auth.ts`](https://github.com/funshothanni/marginalia/blob/main/src/lib/auth.ts) (Current-user lookup), [`src/app/api/query/route.ts`](https://github.com/funshothanni/marginalia/blob/main/src/app/api/query/route.ts) (Question endpoint), [`src/lib/ingest.ts`](https://github.com/funshothanni/marginalia/blob/main/src/lib/ingest.ts) (PDF ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_auth_ui["Login and signup<br/>[LoginForm.tsx]"]
  node_workspace["Workspace<br/>[Workspace.tsx]"]
  node_sidebar["Subject and history sidebar"]
  node_chat_panel["Chat panel<br/>[ChatPanel.tsx]"]
end

subgraph group_access["Identity and access"]
  node_auth_routes["Auth routes<br/>[route.ts]"]
  node_auth_confirm["Auth confirmation<br/>[route.ts]"]
  node_user_auth["Current-user lookup<br/>[auth.ts]"]
end

subgraph group_study["Study content"]
  node_subject_rules["Subject parsing<br/>[courseSubject.ts]"]
  node_upload_route["PDF upload endpoint<br/>[route.ts]"]
  node_ingest["PDF ingestion<br/>[ingest.ts]"]
  node_pdf_extract["PDF text extraction<br/>[extract.ts]"]
  node_chunking["Text chunking<br/>[chunk.ts]"]
  node_embedding["Embedding<br/>[embed.ts]"]
end

subgraph group_conversation["Chat and retrieval"]
  node_chat_routes["Chat endpoints<br/>[route.ts]"]
  node_query_route["Question endpoint<br/>[route.ts]"]
  node_conversation_reply["Conversational reply<br/>[conversation.ts]"]
  node_rag["RAG answering<br/>[rag.ts]"]
  node_rewrite["Question rewriting<br/>[rewrite.ts]"]
  node_answer_generation["Answer generation<br/>[generate.ts]"]
end

subgraph group_platform["Persistence and services"]
  node_data_api["Documents and subjects<br/>[route.ts]"]
  node_message_api["Message endpoint<br/>[route.ts]"]
  node_db["Data access<br/>[db.ts]"]
  node_contracts["Chat and retrieval types"]
  node_supabase_client["Supabase clients<br/>[server.ts]"]
end

node_student(("Student"))
node_supabase[("Supabase")]

node_student -->|"signs in"| node_auth_ui
node_student -->|"uses"| node_workspace
node_workspace -->|"renders"| node_sidebar
node_workspace -->|"renders"| node_chat_panel
node_auth_routes -->|"authenticates"| node_supabase_client
node_auth_confirm -->|"confirms"| node_supabase_client
node_user_auth -->|"gets user"| node_supabase_client
node_chat_routes -->|"checks user"| node_user_auth
node_chat_routes -->|"validates subject"| node_subject_rules
node_chat_routes -->|"manages chats"| node_db
node_upload_route -->|"checks user"| node_user_auth
node_upload_route -->|"validates subject"| node_subject_rules
node_upload_route -->|"ingests PDF"| node_ingest
node_ingest -->|"extracts text"| node_pdf_extract
node_ingest -->|"chunks text"| node_chunking
node_ingest -->|"embeds chunks"| node_embedding
node_ingest -->|"stores chunks"| node_db
node_query_route -->|"checks user"| node_user_auth
node_query_route -->|"validates subject"| node_subject_rules
node_query_route -->|"tries reply"| node_conversation_reply
node_query_route -->|"asks question"| node_rag
node_query_route -->|"reads and saves"| node_db
node_rag -->|"rewrites question"| node_rewrite
node_rag -->|"embeds query"| node_embedding
node_rag -->|"searches chunks"| node_db
node_rag -->|"generates answer"| node_answer_generation
node_data_api -->|"checks user"| node_user_auth
node_data_api -->|"reads documents"| node_db
node_message_api -->|"checks user"| node_user_auth
node_message_api -->|"reads messages"| node_db
node_db -->|"creates client"| node_supabase_client
node_supabase_client -->|"connects"| node_supabase
node_db -->|"uses types"| node_contracts

click node_auth_ui "https://github.com/funshothanni/marginalia/blob/main/src/app/login/LoginForm.tsx"
click node_workspace "https://github.com/funshothanni/marginalia/blob/main/src/app/app/Workspace.tsx"
click node_sidebar "https://github.com/funshothanni/marginalia/blob/main/src/app/app/WorkspaceSidebar.tsx"
click node_chat_panel "https://github.com/funshothanni/marginalia/blob/main/src/app/app/ChatPanel.tsx"
click node_auth_routes "https://github.com/funshothanni/marginalia/blob/main/src/app/api/auth/signup/route.ts"
click node_auth_confirm "https://github.com/funshothanni/marginalia/blob/main/src/app/auth/confirm/route.ts"
click node_user_auth "https://github.com/funshothanni/marginalia/blob/main/src/lib/auth.ts"
click node_subject_rules "https://github.com/funshothanni/marginalia/blob/main/src/lib/courseSubject.ts"
click node_upload_route "https://github.com/funshothanni/marginalia/blob/main/src/app/api/upload/route.ts"
click node_ingest "https://github.com/funshothanni/marginalia/blob/main/src/lib/ingest.ts"
click node_pdf_extract "https://github.com/funshothanni/marginalia/blob/main/src/lib/extract.ts"
click node_chunking "https://github.com/funshothanni/marginalia/blob/main/src/lib/chunk.ts"
click node_embedding "https://github.com/funshothanni/marginalia/blob/main/src/lib/embed.ts"
click node_chat_routes "https://github.com/funshothanni/marginalia/blob/main/src/app/api/chats/route.ts"
click node_query_route "https://github.com/funshothanni/marginalia/blob/main/src/app/api/query/route.ts"
click node_conversation_reply "https://github.com/funshothanni/marginalia/blob/main/src/lib/conversation.ts"
click node_rag "https://github.com/funshothanni/marginalia/blob/main/src/lib/rag.ts"
click node_rewrite "https://github.com/funshothanni/marginalia/blob/main/src/lib/rewrite.ts"
click node_answer_generation "https://github.com/funshothanni/marginalia/blob/main/src/lib/generate.ts"
click node_data_api "https://github.com/funshothanni/marginalia/blob/main/src/app/api/documents/route.ts"
click node_message_api "https://github.com/funshothanni/marginalia/blob/main/src/app/api/messages/route.ts"
click node_db "https://github.com/funshothanni/marginalia/blob/main/src/lib/db.ts"
click node_contracts "https://github.com/funshothanni/marginalia/tree/main/src/types"
click node_supabase_client "https://github.com/funshothanni/marginalia/blob/main/src/lib/supabase/server.ts"

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_auth_ui,node_workspace,node_sidebar,node_chat_panel toneBlue
class node_auth_routes,node_auth_confirm,node_user_auth,node_supabase toneAmber
class node_subject_rules,node_upload_route,node_ingest,node_pdf_extract,node_chunking,node_embedding toneMint
class node_chat_routes,node_query_route,node_conversation_reply,node_rag,node_rewrite,node_answer_generation toneRose
class node_data_api,node_message_api,node_db,node_contracts,node_supabase_client,node_student toneIndigo
```

## Components

### User experience

- [Login and signup](https://github.com/funshothanni/marginalia/blob/main/src/app/login/LoginForm.tsx): `src/app/login/LoginForm.tsx`
- [Workspace](https://github.com/funshothanni/marginalia/blob/main/src/app/app/Workspace.tsx): `src/app/app/Workspace.tsx`
- [Subject and history sidebar](https://github.com/funshothanni/marginalia/blob/main/src/app/app/WorkspaceSidebar.tsx): `src/app/app/WorkspaceSidebar.tsx`
- [Chat panel](https://github.com/funshothanni/marginalia/blob/main/src/app/app/ChatPanel.tsx): `src/app/app/ChatPanel.tsx`

### Identity and access

- [Auth routes](https://github.com/funshothanni/marginalia/blob/main/src/app/api/auth/signup/route.ts): `src/app/api/auth/signup/route.ts`
- [Auth confirmation](https://github.com/funshothanni/marginalia/blob/main/src/app/auth/confirm/route.ts): `src/app/auth/confirm/route.ts`
- [Current-user lookup](https://github.com/funshothanni/marginalia/blob/main/src/lib/auth.ts): `src/lib/auth.ts`

### Study content

- [Subject parsing](https://github.com/funshothanni/marginalia/blob/main/src/lib/courseSubject.ts): `src/lib/courseSubject.ts`
- [PDF upload endpoint](https://github.com/funshothanni/marginalia/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [PDF ingestion](https://github.com/funshothanni/marginalia/blob/main/src/lib/ingest.ts): `src/lib/ingest.ts`
- [PDF text extraction](https://github.com/funshothanni/marginalia/blob/main/src/lib/extract.ts): `src/lib/extract.ts`
- [Text chunking](https://github.com/funshothanni/marginalia/blob/main/src/lib/chunk.ts): `src/lib/chunk.ts`
- [Embedding](https://github.com/funshothanni/marginalia/blob/main/src/lib/embed.ts): `src/lib/embed.ts`

### Chat and retrieval

- [Chat endpoints](https://github.com/funshothanni/marginalia/blob/main/src/app/api/chats/route.ts): `src/app/api/chats/route.ts`
- [Question endpoint](https://github.com/funshothanni/marginalia/blob/main/src/app/api/query/route.ts): `src/app/api/query/route.ts`
- [Conversational reply](https://github.com/funshothanni/marginalia/blob/main/src/lib/conversation.ts): `src/lib/conversation.ts`
- [RAG answering](https://github.com/funshothanni/marginalia/blob/main/src/lib/rag.ts): `src/lib/rag.ts`
- [Question rewriting](https://github.com/funshothanni/marginalia/blob/main/src/lib/rewrite.ts): `src/lib/rewrite.ts`
- [Answer generation](https://github.com/funshothanni/marginalia/blob/main/src/lib/generate.ts): `src/lib/generate.ts`

### Persistence and services

- [Documents and subjects](https://github.com/funshothanni/marginalia/blob/main/src/app/api/documents/route.ts): `src/app/api/documents/route.ts`
- [Message endpoint](https://github.com/funshothanni/marginalia/blob/main/src/app/api/messages/route.ts): `src/app/api/messages/route.ts`
- [Data access](https://github.com/funshothanni/marginalia/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Chat and retrieval types](https://github.com/funshothanni/marginalia/tree/main/src/types): `src/types`
- [Supabase clients](https://github.com/funshothanni/marginalia/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`

### Other components

- **Student**
- **Supabase**

## Connections

- Student → Login and signup: signs in
- Student → Workspace: uses
- Workspace → Subject and history sidebar: renders (evidence: `src/app/app/Workspace.tsx`)
- Workspace → Chat panel: renders (evidence: `src/app/app/Workspace.tsx`)
- Auth routes → Supabase clients: authenticates (evidence: `src/app/api/auth/signup/route.ts`)
- Auth confirmation → Supabase clients: confirms (evidence: `src/app/auth/confirm/route.ts`)
- Current-user lookup → Supabase clients: gets user (evidence: `src/lib/auth.ts`)
- Chat endpoints → Current-user lookup: checks user (evidence: `src/app/api/chats/route.ts`)
- Chat endpoints → Subject parsing: validates subject (evidence: `src/app/api/chats/route.ts`)
- Chat endpoints → Data access: manages chats (evidence: `src/app/api/chats/route.ts`)
- PDF upload endpoint → Current-user lookup: checks user (evidence: `src/app/api/upload/route.ts`)
- PDF upload endpoint → Subject parsing: validates subject (evidence: `src/app/api/upload/route.ts`)
- PDF upload endpoint → PDF ingestion: ingests PDF (evidence: `src/app/api/upload/route.ts`)
- PDF ingestion → PDF text extraction: extracts text (evidence: `src/lib/ingest.ts`)
- PDF ingestion → Text chunking: chunks text (evidence: `src/lib/ingest.ts`)
- PDF ingestion → Embedding: embeds chunks (evidence: `src/lib/ingest.ts`)
- PDF ingestion → Data access: stores chunks (evidence: `src/lib/ingest.ts`)
- Question endpoint → Current-user lookup: checks user (evidence: `src/app/api/query/route.ts`)
- Question endpoint → Subject parsing: validates subject (evidence: `src/app/api/query/route.ts`)
- Question endpoint → Conversational reply: tries reply (evidence: `src/app/api/query/route.ts`)
- Question endpoint → RAG answering: asks question (evidence: `src/app/api/query/route.ts`)
- Question endpoint → Data access: reads and saves (evidence: `src/app/api/query/route.ts`)
- RAG answering → Question rewriting: rewrites question (evidence: `src/lib/rag.ts`)
- RAG answering → Embedding: embeds query (evidence: `src/lib/rag.ts`)
- RAG answering → Data access: searches chunks (evidence: `src/lib/rag.ts`)
- RAG answering → Answer generation: generates answer (evidence: `src/lib/rag.ts`)
- Documents and subjects → Current-user lookup: checks user (evidence: `src/app/api/documents/route.ts`)
- Documents and subjects → Data access: reads documents (evidence: `src/app/api/documents/route.ts`)
- Message endpoint → Current-user lookup: checks user (evidence: `src/app/api/messages/route.ts`)
- Message endpoint → Data access: reads messages (evidence: `src/app/api/messages/route.ts`)
- Data access → Supabase clients: creates client (evidence: `src/lib/db.ts`)
- Supabase clients → Supabase: connects (evidence: `src/lib/supabase/server.ts`)
- Data access → Chat and retrieval types: uses types (evidence: `src/lib/db.ts`)
