# nirmalareddi/recommendation_system architecture

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

- Interactive diagram: https://gitdiagram.com/nirmalareddi/recommendation_system
- Repository: https://github.com/nirmalareddi/recommendation_system

## Overview

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: [`backend/app/api/recommendations.py`](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/recommendations.py) (Recommendation workflow), [`backend/app/main.py`](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/models/db_models.py`](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/models/db_models.py) (ORM entities), [`backend/app/api/students.py`](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/students.py) (Student intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_form["Intake form<br/>[index.html]"]
end

subgraph group_api["API and workflow"]
  node_app["FastAPI app<br/>[main.py]"]
  node_student_api["Student intake<br/>[students.py]"]
  node_university_api["Program catalog API<br/>[universities.py]"]
  node_recommendation_api["Recommendation workflow<br/>[recommendations.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_decision["Recommendation stages"]
  node_scoring["Eligibility and scoring<br/>[scoring.py]"]
  node_scoring_config["Scoring weights<br/>[config.py]"]
  node_explanations["Explanation generation"]
  node_email["Email notification<br/>[email_service.py]"]
end

subgraph group_data["Data and persistence"]
  node_orm["ORM entities<br/>[db_models.py]"]
  node_database_layer["Database sessions<br/>[database.py]"]
  node_store[("Relational database")]
  node_seed["University seeding<br/>[seed.py]"]
  node_seed_data["University records"]
end

node_student(("Student"))
node_anthropic["Anthropic API"]
node_email_services["Email providers"]

node_student -->|"provides profile"| node_form
node_form -->|"submits intake"| node_student_api
node_app -->|"registers route"| node_student_api
node_app -->|"registers route"| node_university_api
node_app -->|"registers route"| node_recommendation_api
node_student_api -->|"validates with"| node_schemas
node_university_api -->|"validates with"| node_schemas
node_recommendation_api -->|"returns as"| node_schemas
node_student_api -->|"creates and reads"| node_orm
node_university_api -->|"creates and lists"| node_orm
node_recommendation_api -->|"loads and persists"| node_orm
node_recommendation_api -->|"scores programs"| node_scoring
node_scoring -->|"uses weights"| node_scoring_config
node_recommendation_api -->|"requests explanations"| node_explanations
node_explanations -.->|"generates via"| node_anthropic
node_recommendation_api -->|"sends recommendations"| node_email
node_email -.->|"delivers through"| node_email_services
node_app -->|"initializes database"| node_database_layer
node_database_layer -->|"creates tables"| node_orm
node_database_layer -->|"opens sessions"| node_store
node_app -->|"seeds on startup"| node_seed
node_seed -->|"loads records"| node_seed_data
node_seed -->|"creates programs"| node_orm

click node_form "https://github.com/nirmalareddi/recommendation_system/blob/main/frontend/student-form/index.html"
click node_app "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/main.py"
click node_student_api "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/students.py"
click node_university_api "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/universities.py"
click node_recommendation_api "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/recommendations.py"
click node_schemas "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/models/schemas.py"
click node_scoring "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/scoring/scoring.py"
click node_scoring_config "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/scoring/config.py"
click node_explanations "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/llm/explanation_service.py"
click node_email "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/notifications/email_service.py"
click node_orm "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/models/db_models.py"
click node_database_layer "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/database.py"
click node_seed "https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/seed.py"
click node_seed_data "https://github.com/nirmalareddi/recommendation_system/blob/main/data/seed_universities.csv"

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_form toneBlue
class node_app,node_student_api,node_university_api,node_recommendation_api,node_schemas toneAmber
class node_scoring,node_scoring_config,node_explanations,node_email,node_anthropic toneMint
class node_orm,node_database_layer,node_store,node_seed,node_seed_data toneRose
class node_student,node_email_services toneIndigo
```

## Components

### User experience

- [Intake form](https://github.com/nirmalareddi/recommendation_system/blob/main/frontend/student-form/index.html): `frontend/student-form/index.html`

### API and workflow

- [FastAPI app](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/main.py): `backend/app/main.py`
- [Student intake](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/students.py): `backend/app/api/students.py`
- [Program catalog API](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/universities.py): `backend/app/api/universities.py`
- [Recommendation workflow](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/api/recommendations.py): `backend/app/api/recommendations.py`
- [API schemas](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`

### Recommendation stages

- [Eligibility and scoring](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/scoring/scoring.py): `backend/app/scoring/scoring.py`
- [Scoring weights](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/scoring/config.py): `backend/app/scoring/config.py`
- [Explanation generation](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/llm/explanation_service.py): `backend/app/llm/explanation_service.py`
- [Email notification](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/notifications/email_service.py): `backend/app/notifications/email_service.py`

### Data and persistence

- [ORM entities](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/models/db_models.py): `backend/app/models/db_models.py`
- [Database sessions](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/database.py): `backend/app/database.py`
- **Relational database**
- [University seeding](https://github.com/nirmalareddi/recommendation_system/blob/main/backend/app/seed.py): `backend/app/seed.py`
- [University records](https://github.com/nirmalareddi/recommendation_system/blob/main/data/seed_universities.csv): `data/seed_universities.csv`

### Other components

- **Student**
- **Anthropic API**
- **Email providers**

## Connections

- Student → Intake form: provides profile (evidence: `README.md`)
- Intake form → Student intake: submits intake (evidence: `README.md`)
- FastAPI app → Student intake: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Program catalog API: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Recommendation workflow: registers route (evidence: `backend/app/main.py`)
- Student intake → API schemas: validates with (evidence: `backend/app/api/students.py`)
- Program catalog API → API schemas: validates with (evidence: `backend/app/api/universities.py`)
- Recommendation workflow → API schemas: returns as (evidence: `backend/app/api/recommendations.py`)
- Student intake → ORM entities: creates and reads (evidence: `backend/app/api/students.py`)
- Program catalog API → ORM entities: creates and lists (evidence: `backend/app/api/universities.py`)
- Recommendation workflow → ORM entities: loads and persists (evidence: `backend/app/api/recommendations.py`)
- Recommendation workflow → Eligibility and scoring: scores programs (evidence: `backend/app/api/recommendations.py`)
- Eligibility and scoring → Scoring weights: uses weights (evidence: `backend/app/scoring/scoring.py`)
- Recommendation workflow → Explanation generation: requests explanations (evidence: `backend/app/api/recommendations.py`)
- Explanation generation → Anthropic API: generates via (evidence: `README.md`)
- Recommendation workflow → Email notification: sends recommendations (evidence: `backend/app/api/recommendations.py`)
- Email notification → Email providers: delivers through (evidence: `README.md`)
- FastAPI app → Database sessions: initializes database (evidence: `backend/app/main.py`)
- Database sessions → ORM entities: creates tables (evidence: `backend/app/database.py`)
- Database sessions → Relational database: opens sessions (evidence: `backend/app/database.py`)
- FastAPI app → University seeding: seeds on startup (evidence: `backend/app/main.py`)
- University seeding → University records: loads records (evidence: `backend/app/seed.py`)
- University seeding → ORM entities: creates programs (evidence: `backend/app/seed.py`)
