# alancode59/ai-cv-backend architecture

> Architecture diagram of the GitHub repository alancode59/ai-cv-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alancode59/ai-cv-backend
- Repository: https://github.com/alancode59/ai-cv-backend

## Overview

AI CV Analyzer accepts CV text or PDF plus a job description, evaluates the match with Cerebras AI, persists the analysis, and returns a structured score, skills, and recommendations. The PDF path validates and extracts text before analysis; history endpoints retrieve persisted results. The integrated web interface submits PDF analyses and displays results, while health endpoints check MongoDB and AI connectivity. The graph follows the documented and excerpted calls; the user routes are present but not registered by the shown application entry point.

Main entry points: [`app/routes/cv_routes.py`](https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/cv_routes.py) (CV endpoints), [`app/services/ai_service.py`](https://github.com/alancode59/ai-cv-backend/blob/main/app/services/ai_service.py) (AI analysis), [`app/main.py`](https://github.com/alancode59/ai-cv-backend/blob/main/app/main.py) (FastAPI app), [`app/routes/health_routes.py`](https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/health_routes.py) (Health endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web_ui["Analyzer page<br/>[index.html]"]
  node_browser_logic["Browser interaction<br/>[app.js]"]
  node_web_styles["Page styling<br/>[styles.css]"]
end

subgraph group_api["API and validation"]
  node_app_entry["FastAPI app<br/>[main.py]"]
  node_cv_routes["CV endpoints<br/>[cv_routes.py]"]
  node_health_routes["Health endpoints<br/>[health_routes.py]"]
  node_cv_schema["Analysis schema<br/>[cv_schema.py]"]
end

subgraph group_analysis["Analysis services"]
  node_pdf_service["PDF validation and extraction<br/>[pdf_service.py]"]
  node_cv_service["Analysis orchestration<br/>[cv_service.py]"]
  node_ai_service["AI analysis<br/>[ai_service.py]"]
  node_prompt["Analysis prompt<br/>[cv_prompt.py]"]
end

subgraph group_persistence["Persistence"]
  node_cv_repository["Analysis repository<br/>[cv_repository.py]"]
  node_mongo_model["Mongo connection<br/>[mongo.py]"]
end

node_user(("User"))
node_cerebras{{"Cerebras AI"}}
node_mongo_db[("MongoDB")]

node_user -->|"uses"| node_web_ui
node_app_entry -->|"renders"| node_web_ui
node_browser_logic -->|"submits PDF"| node_cv_routes
node_browser_logic -->|"updates results"| node_web_ui
node_app_entry -->|"registers"| node_cv_routes
node_app_entry -->|"registers"| node_health_routes
node_cv_routes -->|"validates responses"| node_cv_schema
node_cv_routes -->|"validates and extracts"| node_pdf_service
node_cv_routes -->|"requests analysis"| node_cv_service
node_cv_service -->|"requests evaluation"| node_ai_service
node_ai_service -->|"formats prompt"| node_prompt
node_ai_service -->|"requests completion"| node_cerebras
node_cv_service -->|"saves and retrieves"| node_cv_repository
node_cv_repository -->|"gets database"| node_mongo_model
node_mongo_model -.->|"connects to"| node_mongo_db
node_health_routes -->|"checks database"| node_mongo_model
node_health_routes -->|"checks AI"| node_ai_service

click node_web_ui "https://github.com/alancode59/ai-cv-backend/blob/main/app/templates/index.html"
click node_browser_logic "https://github.com/alancode59/ai-cv-backend/blob/main/app/static/js/app.js"
click node_web_styles "https://github.com/alancode59/ai-cv-backend/blob/main/app/static/css/styles.css"
click node_app_entry "https://github.com/alancode59/ai-cv-backend/blob/main/app/main.py"
click node_cv_routes "https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/cv_routes.py"
click node_health_routes "https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/health_routes.py"
click node_cv_schema "https://github.com/alancode59/ai-cv-backend/blob/main/app/schemas/cv_schema.py"
click node_pdf_service "https://github.com/alancode59/ai-cv-backend/blob/main/app/services/pdf_service.py"
click node_cv_service "https://github.com/alancode59/ai-cv-backend/blob/main/app/services/cv_service.py"
click node_ai_service "https://github.com/alancode59/ai-cv-backend/blob/main/app/services/ai_service.py"
click node_prompt "https://github.com/alancode59/ai-cv-backend/blob/main/app/prompts/cv_prompt.py"
click node_cv_repository "https://github.com/alancode59/ai-cv-backend/blob/main/app/repositories/cv_repository.py"
click node_mongo_model "https://github.com/alancode59/ai-cv-backend/blob/main/app/models/mongo.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_web_ui,node_browser_logic,node_web_styles,node_user toneBlue
class node_app_entry,node_cv_routes,node_health_routes,node_cv_schema,node_mongo_db toneAmber
class node_pdf_service,node_cv_service,node_ai_service,node_prompt toneMint
class node_cv_repository,node_mongo_model toneRose
class node_cerebras toneIndigo
```

## Components

### Web interface

- [Analyzer page](https://github.com/alancode59/ai-cv-backend/blob/main/app/templates/index.html): `app/templates/index.html`
- [Browser interaction](https://github.com/alancode59/ai-cv-backend/blob/main/app/static/js/app.js): `app/static/js/app.js`
- [Page styling](https://github.com/alancode59/ai-cv-backend/blob/main/app/static/css/styles.css): `app/static/css/styles.css`

### API and validation

- [FastAPI app](https://github.com/alancode59/ai-cv-backend/blob/main/app/main.py): `app/main.py`
- [CV endpoints](https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/cv_routes.py): `app/routes/cv_routes.py`
- [Health endpoints](https://github.com/alancode59/ai-cv-backend/blob/main/app/routes/health_routes.py): `app/routes/health_routes.py`
- [Analysis schema](https://github.com/alancode59/ai-cv-backend/blob/main/app/schemas/cv_schema.py): `app/schemas/cv_schema.py`

### Analysis services

- [PDF validation and extraction](https://github.com/alancode59/ai-cv-backend/blob/main/app/services/pdf_service.py): `app/services/pdf_service.py`
- [Analysis orchestration](https://github.com/alancode59/ai-cv-backend/blob/main/app/services/cv_service.py): `app/services/cv_service.py`
- [AI analysis](https://github.com/alancode59/ai-cv-backend/blob/main/app/services/ai_service.py): `app/services/ai_service.py`
- [Analysis prompt](https://github.com/alancode59/ai-cv-backend/blob/main/app/prompts/cv_prompt.py): `app/prompts/cv_prompt.py`

### Persistence

- [Analysis repository](https://github.com/alancode59/ai-cv-backend/blob/main/app/repositories/cv_repository.py): `app/repositories/cv_repository.py`
- [Mongo connection](https://github.com/alancode59/ai-cv-backend/blob/main/app/models/mongo.py): `app/models/mongo.py`

### Other components

- **User**
- **Cerebras AI**
- **MongoDB**

## Connections

- User → Analyzer page: uses (evidence: `README.md`)
- FastAPI app → Analyzer page: renders (evidence: `app/main.py`)
- Browser interaction → CV endpoints: submits PDF (evidence: `app/static/js/app.js`)
- Browser interaction → Analyzer page: updates results (evidence: `app/static/js/app.js`)
- FastAPI app → CV endpoints: registers (evidence: `app/main.py`)
- FastAPI app → Health endpoints: registers (evidence: `app/main.py`)
- CV endpoints → Analysis schema: validates responses (evidence: `app/routes/cv_routes.py`)
- CV endpoints → PDF validation and extraction: validates and extracts (evidence: `app/routes/cv_routes.py`)
- CV endpoints → Analysis orchestration: requests analysis (evidence: `app/routes/cv_routes.py`)
- Analysis orchestration → AI analysis: requests evaluation (evidence: `app/services/cv_service.py`)
- AI analysis → Analysis prompt: formats prompt (evidence: `app/services/ai_service.py`)
- AI analysis → Cerebras AI: requests completion (evidence: `app/services/ai_service.py`)
- Analysis orchestration → Analysis repository: saves and retrieves (evidence: `app/services/cv_service.py`)
- Analysis repository → Mongo connection: gets database (evidence: `app/repositories/cv_repository.py`)
- Mongo connection → MongoDB: connects to
- Health endpoints → Mongo connection: checks database (evidence: `app/routes/health_routes.py`)
- Health endpoints → AI analysis: checks AI (evidence: `app/routes/health_routes.py`)
