# kid-ye/acad-system architecture

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

- Interactive diagram: https://gitdiagram.com/kid-ye/acad-system
- Repository: https://github.com/kid-ye/acad-system

## Overview

Pyqheaven is an exam-question archive with four user-facing workflows: filtered/semantic search, citation-grounded chat, course statistics, and bulk PDF downloads. The React app calls a FastAPI backend; documented backend capabilities include metadata, question, paper, and figure endpoints. Shared backend layers provide filtering, SQLite access, result shaping, semantic retrieval, and LLM completion. The README also describes an offline corpus-preparation pipeline. Several routes and modules were not sampled, so their internal call relationships are shown only where documented; no unsampled source was inspected.

Main entry points: [`frontend/src/api.ts`](https://github.com/kid-ye/acad-system/blob/main/frontend/src/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/kid-ye/acad-system/blob/main/frontend/src/App.tsx) (React application), [`backend/app/routers/search.py`](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/search.py) (Search endpoints), [`backend/app/db.py`](https://github.com/kid-ye/acad-system/blob/main/backend/app/db.py) (SQLite corpus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["React application<br/>[App.tsx]"]
  node_home["Question search<br/>[Home.tsx]"]
  node_ask["Grounded chat<br/>[Ask.tsx]"]
  node_stats["Course statistics<br/>[Stats.tsx]"]
  node_download["PDF export<br/>[Download.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_question_card["Question card<br/>[QuestionCard.tsx]"]
end

subgraph group_api["API workflows"]
  node_search_api["Search endpoints<br/>[search.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_meta_api["Metadata and stats<br/>[meta.py]"]
  node_question_api["Question detail<br/>[questions.py]"]
  node_papers_api["Paper downloads<br/>[papers.py]"]
  node_files_api["PDF and figures<br/>[files.py]"]
end

subgraph group_core["Search and retrieval"]
  node_chat_flow["Chat retrieval flow<br/>[chat.py]"]
  node_llm["LLM completion<br/>[llm.py]"]
  node_semantic["Semantic retrieval<br/>[semantic.py]"]
  node_filters["Shared filters<br/>[filters.py]"]
  node_database[("SQLite corpus<br/>[db.py]")]
  node_shaping["Result shaping<br/>[shape.py]"]
end

subgraph group_data["Corpus pipeline"]
  node_embed["Question embeddings<br/>[embed_questions.py]"]
  node_topics["Topic labeling<br/>[label_topics.py]"]
  node_apply_topics["Apply topic labels<br/>[apply_topics.py]"]
  node_papers_store[("Source PDF archive")]
end

node_visitor(("Archive user"))

node_visitor -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_ask
node_app -->|"routes to"| node_stats
node_app -->|"routes to"| node_download
node_home -.->|"requests data"| node_api_client
node_ask -.->|"requests chat"| node_api_client
node_stats -.->|"requests stats"| node_api_client
node_download -.->|"requests papers"| node_api_client
node_home -->|"renders results"| node_question_card
node_api_client -->|"calls search"| node_search_api
node_api_client -->|"calls chat"| node_chat_api
node_api_client -->|"calls metadata"| node_meta_api
node_api_client -->|"calls detail"| node_question_api
node_api_client -->|"calls export"| node_papers_api
node_api_client -->|"fetches files"| node_files_api
node_search_api -->|"builds predicates"| node_filters
node_search_api -->|"queries"| node_database
node_search_api -->|"retrieves matches"| node_semantic
node_search_api -->|"shapes results"| node_shaping
node_chat_api -.->|"delegates chat"| node_chat_flow
node_chat_flow -.->|"completes answer"| node_llm
node_chat_flow -.->|"retrieves evidence"| node_semantic
node_meta_api -.->|"reads corpus"| node_database
node_question_api -.->|"reads question"| node_database
node_papers_api -.->|"serves PDFs"| node_papers_store
node_files_api -.->|"serves figures"| node_papers_store
node_embed -.->|"produces embeddings"| node_database
node_topics -.->|"labels topics"| node_apply_topics
node_apply_topics -.->|"updates topics"| node_database

click node_app "https://github.com/kid-ye/acad-system/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Home.tsx"
click node_ask "https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Ask.tsx"
click node_stats "https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Stats.tsx"
click node_download "https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Download.tsx"
click node_api_client "https://github.com/kid-ye/acad-system/blob/main/frontend/src/api.ts"
click node_question_card "https://github.com/kid-ye/acad-system/blob/main/frontend/src/components/QuestionCard.tsx"
click node_search_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/search.py"
click node_chat_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/chat.py"
click node_meta_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/meta.py"
click node_question_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/questions.py"
click node_papers_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/papers.py"
click node_files_api "https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/files.py"
click node_chat_flow "https://github.com/kid-ye/acad-system/blob/main/backend/app/chat.py"
click node_llm "https://github.com/kid-ye/acad-system/blob/main/backend/app/llm.py"
click node_semantic "https://github.com/kid-ye/acad-system/blob/main/backend/app/semantic.py"
click node_filters "https://github.com/kid-ye/acad-system/blob/main/backend/app/filters.py"
click node_database "https://github.com/kid-ye/acad-system/blob/main/backend/app/db.py"
click node_shaping "https://github.com/kid-ye/acad-system/blob/main/backend/app/shape.py"
click node_embed "https://github.com/kid-ye/acad-system/blob/main/scripts/embed_questions.py"
click node_topics "https://github.com/kid-ye/acad-system/blob/main/scripts/label_topics.py"
click node_apply_topics "https://github.com/kid-ye/acad-system/blob/main/scripts/apply_topics.py"

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_app,node_home,node_ask,node_stats,node_download,node_api_client,node_question_card,node_visitor toneBlue
class node_search_api,node_chat_api,node_meta_api,node_question_api,node_papers_api,node_files_api toneAmber
class node_chat_flow,node_llm,node_semantic,node_filters,node_database,node_shaping toneMint
class node_embed,node_topics,node_apply_topics,node_papers_store toneRose
```

## Components

### Web application

- [React application](https://github.com/kid-ye/acad-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Question search](https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Home.tsx): `frontend/src/routes/Home.tsx`
- [Grounded chat](https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Ask.tsx): `frontend/src/routes/Ask.tsx`
- [Course statistics](https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Stats.tsx): `frontend/src/routes/Stats.tsx`
- [PDF export](https://github.com/kid-ye/acad-system/blob/main/frontend/src/routes/Download.tsx): `frontend/src/routes/Download.tsx`
- [API client](https://github.com/kid-ye/acad-system/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Question card](https://github.com/kid-ye/acad-system/blob/main/frontend/src/components/QuestionCard.tsx): `frontend/src/components/QuestionCard.tsx`

### API workflows

- [Search endpoints](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/search.py): `backend/app/routers/search.py`
- [Chat endpoint](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Metadata and stats](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/meta.py): `backend/app/routers/meta.py`
- [Question detail](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/questions.py): `backend/app/routers/questions.py`
- [Paper downloads](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/papers.py): `backend/app/routers/papers.py`
- [PDF and figures](https://github.com/kid-ye/acad-system/blob/main/backend/app/routers/files.py): `backend/app/routers/files.py`

### Search and retrieval

- [Chat retrieval flow](https://github.com/kid-ye/acad-system/blob/main/backend/app/chat.py): `backend/app/chat.py`
- [LLM completion](https://github.com/kid-ye/acad-system/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Semantic retrieval](https://github.com/kid-ye/acad-system/blob/main/backend/app/semantic.py): `backend/app/semantic.py`
- [Shared filters](https://github.com/kid-ye/acad-system/blob/main/backend/app/filters.py): `backend/app/filters.py`
- [SQLite corpus](https://github.com/kid-ye/acad-system/blob/main/backend/app/db.py): `backend/app/db.py`
- [Result shaping](https://github.com/kid-ye/acad-system/blob/main/backend/app/shape.py): `backend/app/shape.py`

### Corpus pipeline

- [Question embeddings](https://github.com/kid-ye/acad-system/blob/main/scripts/embed_questions.py): `scripts/embed_questions.py`
- [Topic labeling](https://github.com/kid-ye/acad-system/blob/main/scripts/label_topics.py): `scripts/label_topics.py`
- [Apply topic labels](https://github.com/kid-ye/acad-system/blob/main/scripts/apply_topics.py): `scripts/apply_topics.py`
- **Source PDF archive**

### Other components

- **Archive user**

## Connections

- Archive user → React application: uses
- React application → Question search: routes to
- React application → Grounded chat: routes to
- React application → Course statistics: routes to
- React application → PDF export: routes to
- Question search → API client: requests data
- Grounded chat → API client: requests chat
- Course statistics → API client: requests stats
- PDF export → API client: requests papers
- Question search → Question card: renders results
- API client → Search endpoints: calls search
- API client → Chat endpoint: calls chat
- API client → Metadata and stats: calls metadata
- API client → Question detail: calls detail
- API client → Paper downloads: calls export
- API client → PDF and figures: fetches files
- Search endpoints → Shared filters: builds predicates (evidence: `backend/app/routers/search.py`)
- Search endpoints → SQLite corpus: queries (evidence: `backend/app/routers/search.py`)
- Search endpoints → Semantic retrieval: retrieves matches (evidence: `backend/app/routers/search.py`)
- Search endpoints → Result shaping: shapes results (evidence: `backend/app/routers/search.py`)
- Chat endpoint → Chat retrieval flow: delegates chat
- Chat retrieval flow → LLM completion: completes answer
- Chat retrieval flow → Semantic retrieval: retrieves evidence
- Metadata and stats → SQLite corpus: reads corpus
- Question detail → SQLite corpus: reads question
- Paper downloads → Source PDF archive: serves PDFs
- PDF and figures → Source PDF archive: serves figures
- Question embeddings → SQLite corpus: produces embeddings
- Topic labeling → Apply topic labels: labels topics
- Apply topic labels → SQLite corpus: updates topics
