How nirmalareddi/recommendation_system works
This is an admissions-recommendation POC: students submit profiles, programs are maintained as reference data, and a recommendation request filters and scores eligible programs, ranks the top three, generates explanations, persists the result, and sends an email. The frontend is a plain intake form; FastAPI exposes intake, reference-data, and recommendation endpoints. Scoring, explanation generation, and notification are distinct product stages. The graph also shows the ORM/storage layer and startup seeding. Some optional integrations are documented in the README; those edges are marked dashed because their runtime wiring is not fully excerpted.
Main entry points: recommendations.py Recommendation workflow · main.py FastAPI app · db_models.py ORM entities · students.py Student intake
Components 18
User experience
- Intake form
frontend/student-form/index.html
API and workflow
- FastAPI app
backend/app/main.py - Student intake
backend/app/api/students.py - Program catalog API
backend/app/api/universities.py - Recommendation workflow
backend/app/api/recommendations.py - API schemas
backend/app/models/schemas.py
Recommendation stages
- Eligibility and scoring
backend/app/scoring/scoring.py - Scoring weights
backend/app/scoring/config.py - Explanation generation
backend/app/llm/explanation_service.py - Email notification
backend/app/notifications/email_service.py
Data and persistence
- ORM entities
backend/app/models/db_models.py - Database sessions
backend/app/database.py - Relational database
- University seeding
backend/app/seed.py - University records
data/seed_universities.csv
Other components
- Student
- Anthropic API
- Email providers
Connections 23
- Student → Intake form: provides profile
README.md - Intake form → Student intake: submits intake
README.md - FastAPI app → Student intake: registers route
backend/app/main.py - FastAPI app → Program catalog API: registers route
backend/app/main.py - FastAPI app → Recommendation workflow: registers route
backend/app/main.py - Student intake → API schemas: validates with
backend/app/api/students.py - Program catalog API → API schemas: validates with
backend/app/api/universities.py - Recommendation workflow → API schemas: returns as
backend/app/api/recommendations.py - Student intake → ORM entities: creates and reads
backend/app/api/students.py - Program catalog API → ORM entities: creates and lists
backend/app/api/universities.py - Recommendation workflow → ORM entities: loads and persists
backend/app/api/recommendations.py - Recommendation workflow → Eligibility and scoring: scores programs
backend/app/api/recommendations.py - Eligibility and scoring → Scoring weights: uses weights
backend/app/scoring/scoring.py - Recommendation workflow → Explanation generation: requests explanations
backend/app/api/recommendations.py - Explanation generation → Anthropic API: generates via
README.md - Recommendation workflow → Email notification: sends recommendations
backend/app/api/recommendations.py - Email notification → Email providers: delivers through
README.md - FastAPI app → Database sessions: initializes database
backend/app/main.py - Database sessions → ORM entities: creates tables
backend/app/database.py - Database sessions → Relational database: opens sessions
backend/app/database.py - FastAPI app → University seeding: seeds on startup
backend/app/main.py - University seeding → University records: loads records
backend/app/seed.py - University seeding → ORM entities: creates programs
backend/app/seed.py