How udlhs/degreeguidance works
Degree Guidance is a Sri Lankan university-admissions decision aid. Students submit their A/L profile, receive deterministic eligibility results and transparent rankings, then may ask a conversational advisor grounded in course data and knowledge sources. Admins maintain the yearly cutoff dataset through handbook ingestion, review, and promotion. The README documents capabilities beyond the sampled implementation; links for those are limited to documented module paths, and the source excerpts do not show every router-to-service call.
Main entry points: db.py Postgres and pgvector · route.ts Public API proxy · orchestrator.py Agent orchestrator · admin_ingestions.py Ingestion API
Components 25
Student guidance
- Guidance interface
web/src/app/(student)/page.tsx - Public API proxy
web/src/app/api/public/[...path]/route.ts - Guidance results
web/src/components/student/results-view.tsx - Advisor chat
web/src/components/student/chat-panel.tsx
AI advisor
- Agent orchestrator
core/chat/orchestrator.py - Advisor tools
core/chat/tools.py - Knowledge retrieval
core/rag/retrieval.py - Gemini
Admin data lifecycle
- Admin panel
web/src/app/admin/(panel)/ingestions/page.tsx - Admin BFF
web/src/app/api/bff/[...path]/route.ts - Ingestion API
apps/api/routers/admin_ingestions.py - Arq queue
apps/api/queue.py - PDF extraction job
apps/worker/jobs/extract_pdf.py - Ingestion processing
core/ingestion/grid_extractor.py - Cutoff loader
apps/worker/jobs/ingest_zscores.py - Knowledge indexing
apps/worker/jobs/index_factsheets.py
API and persistence
- Eligibility API
apps/api/routers/eligibility.py - Eligibility engine
core/eligibility/engine.py - Recommendation API
apps/api/routers/recommendations.py - Ranking service
core/scoring/service.py - Scoring engine
core/scoring/engine.py - Chat API
apps/api/routers/chat.py - Postgres and pgvector
core/db.py
Other components
- Student
- Administrator
Connections 36
- Student → Guidance interface: enters profile
- Guidance interface → Public API proxy: requests guidance
- Public API proxy → Eligibility API: forwards request
- Eligibility API → Eligibility engine: checks eligibility
- Eligibility engine → Postgres and pgvector: queries cutoffs
- Eligibility engine → Postgres and pgvector: writes audit
- Public API proxy → Recommendation API: requests ranking
- Recommendation API → Ranking service: ranks eligible courses
- Ranking service → Scoring engine: scores courses
- Scoring engine → Recommendation API: returns ranking
- Recommendation API → Postgres and pgvector: loads scoring data
- Eligibility API → Public API proxy: returns results
- Recommendation API → Public API proxy: returns ranking
- Public API proxy → Guidance results: supplies guidance
- Guidance interface → Advisor chat: opens advisor
- Advisor chat → Chat API: sends question
- Chat API → Agent orchestrator: runs agent
- Agent orchestrator → Advisor tools: dispatches tools
- Advisor tools → Knowledge retrieval: searches knowledge
- Knowledge retrieval → Postgres and pgvector: retrieves passages
- Agent orchestrator → Gemini: sends prompt and tools
- Gemini → Agent orchestrator: returns tool calls
- Advisor tools → Postgres and pgvector: reads course data
- Agent orchestrator → Chat API: returns response
- Administrator → Admin panel: manages handbooks
- Admin panel → Admin BFF: calls admin API
- Admin BFF → Ingestion API: forwards request
- Ingestion API → Arq queue: enqueues extraction
- Arq queue → PDF extraction job: dispatches job
- PDF extraction job → Ingestion processing: extracts cutoff grid
- Ingestion API → Postgres and pgvector: stores review state
- Admin panel → Ingestion API: uploads handbook
- Ingestion API → Cutoff loader: promotes reviewed data
- Cutoff loader → Postgres and pgvector: writes cutoff records
- Knowledge indexing → Postgres and pgvector: indexes knowledge
- Admin BFF → Knowledge indexing: requests indexing