# anuradhakadam035-ops/swaroop-project- architecture

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

- Interactive diagram: https://gitdiagram.com/anuradhakadam035-ops/swaroop-project-
- Repository: https://github.com/anuradhakadam035-ops/swaroop-project-

## Overview

#### Purpose and Topology
VIDYASETU is an AI-assisted career-guidance platform for students. It combines registration/profile data, MCQ assessments, skills, and education context to produce career matches, skill-gap analysis, learning roadmaps, courses, jobs, resumes, interview support, and reports. The repository is a static multi-page frontend plus a Python backend API.

#### Application Entry Points
- Backend API bootstrap and route composition: `backend/main.py`
- Backend configuration and database access boundary: `backend/config.py`, `backend/database.py`
- Browser entry pages include `frontend/index.html`, `frontend/dashboard.html`, and role-specific admin pages such as `frontend/admin.html`.
- Frontend JavaScript calls backend APIs through `frontend/css/js/api.js`; feature pages have corresponding feature scripts.

#### API and Domain Boundary
FastAPI-style routers organize the API by user workflow rather than a single monolith: authentication, profile/dashboard, assessment, career/recommendations, and AI features. Representative API modules are `backend/routers/auth.py`, `backend/routers/assessment.py`, `backend/routers/recommendation.py`, `backend/routers/roadmap.py`, and `backend/routers/resume.py`.
Schemas define request/response contracts separately from persistent entities, while models represent the stored domain: `backend/schemas/assessment.py`, `backend/schemas/recommendation.py`, `backend/models/assessment.py`, `backend/models/recommendation.py`.

#### Identity, Roles, and Persistence
Users and administrators are distinct authenticated actors. User authentication/security is isolated in `backend/security/auth.py`; administrator authentication is isolated in `backend/security/admin_auth.py`. Core persisted entities cover users, assessments/questions/answers/results, recommendations, resumes, jobs, chats, interviews, and admin-managed courses: `backend/models/user.py`, `backend/models/assessment_result.py`, `backend/models/student_answer.py`, `backend/models/admin_course.py`.
This provides the key boundary between HTTP/UI input, validated schemas, authorization, and database-backed records.

#### Assessment-to-Recommendation Pipeline
The primary control flow is: user registers/authenticates → completes assessment questions → answers and results are stored → recommendation logic evaluates profile/skills/assessment signals → generated career matches and gaps are returned to dashboard/report views.
Relevant stages are implemented in `backend/routers/assessment.py`, `backend/services/recommendation_engine.py`, `backend/services/skill_service.py`, and `backend/services/roadmap_generator.py`. Rule-based career knowledge and skill extraction/matching utilities support the pipeline: `backend/utils/career_rules.py`, `backend/utils/skill_extractor.py`, `backend/utils/skill_matcher.py`.

#### AI and Career-Development Services
Gemini is the explicit AI-provider integration boundary: `backend/core/gemini.py`. AI-facing router/service layers support general AI output, chatbot conversations, and interview assistance: `backend/routers/ai.py`, `backend/services/ai_service.py`, `backend/services/chatbot_ai.py`, `backend/services/interview_ai.py`.
Derived guidance is exposed as recommendations, roadmaps, courses, and jobs through `backend/routers/recommendation.py`, `backend/routers/course.py`, and `backend/routers/jobs.py`.

#### Resume, ATS, and Document Processing
Resume workflows ingest and analyze candidate documents, calculate ATS-oriented feedback, and generate reportable output. The API/service/utilities boundary is visible in `backend/routers/resume.py`, `backend/services/resume_service.py`, `backend/services/ats_service.py`, and `backend/utils/pdf_reader.py`. PDF generation is separated in `backend/services/pdf_service.py`.

#### Administration and Analytics
Administrative routes manage admins, students, courses, jobs, questions, and dashboard operations: `backend/routers/admin.py`, `backend/routers/admin_questions.py`, `backend/routers/admin_course.py`, `backend/routers/admin_students.py`. Analytics has its own API/service layer—`backend/routers/analytics.py`, `backend/services/analtyics_service.py`—allowing aggregate reporting to remain distinct from student-facing recommendation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser frontend"]
  node_pages["Student &amp; admin pages<br/>static frontend<br/>[index.html]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_main["API bootstrap<br/>FastAPI app<br/>[main.py]"]
  node_workflow_routers["User workflow routers<br/>API routers<br/>[recommendation.py]"]
  node_admin_routers["Admin &amp; analytics routers<br/>API routers<br/>[admin.py]"]
end

subgraph group_guidance["Guidance services"]
  node_assessment["Assessment workflow<br/>assessment API<br/>[assessment.py]"]
  node_recommendation_engine["Career recommendation engine<br/>recommendation service"]
  node_career_rules["Career rules &amp; matching<br/>career knowledge utilities<br/>[career_rules.py]"]
  node_skills["Skill gap service<br/>skill analysis service<br/>[skill_service.py]"]
  node_roadmaps["Roadmap generator<br/>guidance generator"]
  node_gemini{{"Gemini integration<br/>AI provider boundary<br/>[gemini.py]"}}
  node_ai_features["AI chat &amp; interview services<br/>AI application services<br/>[ai_service.py]"]
  node_resume_ats["Resume &amp; ATS analysis<br/>document analysis service<br/>[resume_service.py]"]
  node_pdf_output["PDF reports<br/>document generation<br/>[pdf_service.py]"]
  node_analytics["Analytics service<br/>aggregate reporting service"]
end

subgraph group_data["Identity and data"]
  node_schemas["API schemas<br/>request/response contracts<br/>[assessment.py]"]
  node_user_auth["User authentication<br/>security service<br/>[auth.py]"]
  node_admin_auth["Admin authentication<br/>security service<br/>[admin_auth.py]"]
  node_database[("Database access<br/>persistence boundary<br/>[database.py]")]
  node_domain_models["Domain records<br/>persistent models"]
end

node_pages -->|"uses API client"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_main
node_main -->|"mounts"| node_workflow_routers
node_main -->|"mounts"| node_admin_routers
node_workflow_routers -->|"validates"| node_schemas
node_workflow_routers -->|"authenticates users"| node_user_auth
node_admin_routers -->|"authenticates admins"| node_admin_auth
node_assessment -->|"stores answers and results"| node_domain_models
node_workflow_routers -->|"serves assessment"| node_assessment
node_assessment -->|"assessment signals"| node_recommendation_engine
node_recommendation_engine -->|"applies rules"| node_career_rules
node_recommendation_engine -->|"finds skill gaps"| node_skills
node_skills -->|"guides roadmap"| node_roadmaps
node_recommendation_engine -->|"stores matches"| node_domain_models
node_workflow_routers -->|"AI endpoints"| node_ai_features
node_ai_features -->|"AI generation"| node_gemini
node_workflow_routers -->|"resume endpoints"| node_resume_ats
node_resume_ats -->|"report output"| node_pdf_output
node_admin_routers -->|"reporting endpoints"| node_analytics
node_analytics -->|"aggregates records"| node_domain_models
node_domain_models -->|"persists through"| node_database

click node_pages "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/frontend/index.html"
click node_frontend_api "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/frontend/css/js/api.js"
click node_main "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/main.py"
click node_workflow_routers "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/recommendation.py"
click node_admin_routers "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/admin.py"
click node_schemas "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/schemas/assessment.py"
click node_user_auth "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/security/auth.py"
click node_admin_auth "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/security/admin_auth.py"
click node_database "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/database.py"
click node_domain_models "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/models/assessment_result.py"
click node_assessment "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/assessment.py"
click node_recommendation_engine "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/recommendation_engine.py"
click node_career_rules "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/utils/career_rules.py"
click node_skills "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/skill_service.py"
click node_roadmaps "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/roadmap_generator.py"
click node_gemini "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/core/gemini.py"
click node_ai_features "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/ai_service.py"
click node_resume_ats "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/resume_service.py"
click node_pdf_output "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/pdf_service.py"
click node_analytics "https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/analtyics_service.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_pages,node_frontend_api toneBlue
class node_main,node_workflow_routers,node_admin_routers toneAmber
class node_assessment,node_recommendation_engine,node_career_rules,node_skills,node_roadmaps,node_gemini,node_ai_features,node_resume_ats,node_pdf_output,node_analytics toneMint
class node_schemas,node_user_auth,node_admin_auth,node_database,node_domain_models toneRose
```

## Components

### Browser frontend

Static multi-page student and admin interface.

- [Student & admin pages](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/frontend/index.html): static frontend · `frontend/index.html`
- [API client](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/frontend/css/js/api.js): browser API client · `frontend/css/js/api.js`

### Backend API

FastAPI bootstrap and workflow routers.

- [API bootstrap](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/main.py): FastAPI app · Composes backend routes. · `backend/main.py`
- [User workflow routers](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/recommendation.py): API routers · Auth, assessment, recommendations, roadmaps, resumes, courses, and jobs. · `backend/routers/recommendation.py`
- [Admin & analytics routers](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/admin.py): API routers · Administration and aggregate reporting endpoints. · `backend/routers/admin.py`

### Guidance services

Assessment, recommendation, AI, and document pipelines.

- [Assessment workflow](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/routers/assessment.py): assessment API · Captures questions, answers, and results. · `backend/routers/assessment.py`
- [Career recommendation engine](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/recommendation_engine.py): recommendation service · Evaluates profile, skills, and assessment signals. · `backend/services/recommendation_engine.py`
- [Career rules & matching](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/utils/career_rules.py): career knowledge utilities · `backend/utils/career_rules.py`
- [Skill gap service](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/skill_service.py): skill analysis service · `backend/services/skill_service.py`
- [Roadmap generator](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/roadmap_generator.py): guidance generator · `backend/services/roadmap_generator.py`
- [Gemini integration](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/core/gemini.py): AI provider boundary · `backend/core/gemini.py`
- [AI chat & interview services](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/ai_service.py): AI application services · General AI, chatbot, and interview assistance. · `backend/services/ai_service.py`
- [Resume & ATS analysis](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/resume_service.py): document analysis service · Processes resumes and produces ATS-oriented feedback. · `backend/services/resume_service.py`
- [PDF reports](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/pdf_service.py): document generation · `backend/services/pdf_service.py`
- [Analytics service](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/services/analtyics_service.py): aggregate reporting service · `backend/services/analtyics_service.py`

### Identity and data

Authorization, contracts, and persisted domain records.

- [API schemas](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/schemas/assessment.py): request/response contracts · `backend/schemas/assessment.py`
- [User authentication](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/security/auth.py): security service · `backend/security/auth.py`
- [Admin authentication](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/security/admin_auth.py): security service · `backend/security/admin_auth.py`
- [Database access](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/database.py): persistence boundary · `backend/database.py`
- [Domain records](https://github.com/anuradhakadam035-ops/swaroop-project-/blob/main/backend/models/assessment_result.py): persistent models · Users, answers, results, recommendations, resumes, jobs, chats, interviews, and courses. · `backend/models/assessment_result.py`

## Connections

- Student & admin pages → API client: uses API client
- API client → API bootstrap: HTTP requests
- API bootstrap → User workflow routers: mounts
- API bootstrap → Admin & analytics routers: mounts
- User workflow routers → API schemas: validates
- User workflow routers → User authentication: authenticates users
- Admin & analytics routers → Admin authentication: authenticates admins
- Assessment workflow → Domain records: stores answers and results
- User workflow routers → Assessment workflow: serves assessment
- Assessment workflow → Career recommendation engine: assessment signals
- Career recommendation engine → Career rules & matching: applies rules
- Career recommendation engine → Skill gap service: finds skill gaps
- Skill gap service → Roadmap generator: guides roadmap
- Career recommendation engine → Domain records: stores matches
- User workflow routers → AI chat & interview services: AI endpoints
- AI chat & interview services → Gemini integration: AI generation
- User workflow routers → Resume & ATS analysis: resume endpoints
- Resume & ATS analysis → PDF reports: report output
- Admin & analytics routers → Analytics service: reporting endpoints
- Analytics service → Domain records: aggregates records
- Domain records → Database access: persists through
