How kid-ye/acad-system works
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: api.ts API client · App.tsx React application · search.py Search endpoints · db.py SQLite corpus
Components 24
Web application
- React application
frontend/src/App.tsx - Question search
frontend/src/routes/Home.tsx - Grounded chat
frontend/src/routes/Ask.tsx - Course statistics
frontend/src/routes/Stats.tsx - PDF export
frontend/src/routes/Download.tsx - API client
frontend/src/api.ts - Question card
frontend/src/components/QuestionCard.tsx
API workflows
- Search endpoints
backend/app/routers/search.py - Chat endpoint
backend/app/routers/chat.py - Metadata and stats
backend/app/routers/meta.py - Question detail
backend/app/routers/questions.py - Paper downloads
backend/app/routers/papers.py - PDF and figures
backend/app/routers/files.py
Search and retrieval
- Chat retrieval flow
backend/app/chat.py - LLM completion
backend/app/llm.py - Semantic retrieval
backend/app/semantic.py - Shared filters
backend/app/filters.py - SQLite corpus
backend/app/db.py - Result shaping
backend/app/shape.py
Corpus pipeline
- Question embeddings
scripts/embed_questions.py - Topic labeling
scripts/label_topics.py - Apply topic labels
scripts/apply_topics.py - Source PDF archive
Other components
- Archive user
Connections 30
- 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
backend/app/routers/search.py - Search endpoints → SQLite corpus: queries
backend/app/routers/search.py - Search endpoints → Semantic retrieval: retrieves matches
backend/app/routers/search.py - Search endpoints → Result shaping: shapes results
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