# souvikkundu0901/ai-face-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/souvikkundu0901/ai-face-analyzer
- Repository: https://github.com/souvikkundu0901/ai-face-analyzer

## Overview

AI Face Analyzer is a FastAPI service that turns an uploaded selfie into quality-checked facial and skin metrics, deterministic recommendations, visual output, and a safety-constrained explanation report. The principal workflow is orchestrated in `app/main.py`; README documents its analysis stages, while sampled code confirms rules-to-LLM ownership. Authenticated users can retain derived scan data, compare scans over time, and manage accounts. The repository also documents a web interface and operational health/observability features. Some pipeline wiring and UI implementation were not sampled, so uncertain links are omitted.

Main entry points: [`app/main.py`](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/main.py) (FastAPI service), [`app/llm/client.py`](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/llm/client.py) (Explanation generator), [`app/auth/dependencies.py`](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/auth/dependencies.py) (Auth dependencies), [`app/db/session.py`](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/db/session.py) (Database sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Selfie analysis"]
  node_api["FastAPI service<br/>[main.py]"]
  node_quality["Quality gate<br/>[quality.py]"]
  node_detection["Face landmarks<br/>[face_detect.py]"]
  node_geometry["Geometry metrics<br/>[geometry.py]"]
  node_skin["Skin metrics<br/>[skin.py]"]
  node_overlay["Visual overlays<br/>[overlay.py]"]
end

subgraph group_reporting["Recommendations and reports"]
  node_rules["Recommendation rules<br/>[engine.py]"]
  node_llm["Explanation generator<br/>[client.py]"]
  node_report["Analysis response<br/>[schemas.py]"]
end

subgraph group_accounts["Accounts and history"]
  node_auth["Auth and tokens<br/>[security.py]"]
  node_authdeps["Auth dependencies<br/>[dependencies.py]"]
  node_dbsession["Database sessions<br/>[session.py]"]
  node_dbmodels[("User and scans<br/>[models.py]")]
  node_comparison["Scan comparison<br/>[service.py]"]
end

subgraph group_operations["Security and operations"]
  node_validation["Upload validation<br/>[validation.py]"]
  node_limiter["Rate limiting<br/>[rate_limiter.py]"]
  node_metrics["Metrics collector<br/>[metrics.py]"]
  node_health["Health and probes<br/>[main.py]"]
end

node_user(("Selfie user"))
node_gemini(("Gemini API"))
node_web["Web interface<br/>[index.html]"]

node_user -->|"uploads selfie"| node_api
node_api -->|"validates upload"| node_validation
node_api -->|"checks quality"| node_quality
node_api -->|"detects face"| node_detection
node_api -->|"analyzes geometry"| node_geometry
node_api -->|"analyzes skin"| node_skin
node_api -->|"builds overlays"| node_overlay
node_api -->|"evaluates scores"| node_rules
node_api -->|"requests explanation"| node_llm
node_llm -.->|"calls"| node_gemini
node_llm -->|"returns explanation"| node_report
node_api -->|"returns analysis"| node_report
node_web -->|"uses API"| node_api
node_api -->|"checks identity"| node_authdeps
node_authdeps -->|"validates tokens"| node_auth
node_api -->|"issues tokens"| node_auth
node_api -->|"opens sessions"| node_dbsession
node_dbsession -->|"persists records"| node_dbmodels
node_api -->|"compares scans"| node_comparison
node_api -->|"throttles requests"| node_limiter
node_api -->|"records timings"| node_metrics
node_api -->|"serves probes"| node_health

click node_api "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/main.py"
click node_quality "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/quality.py"
click node_detection "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/face_detect.py"
click node_geometry "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/geometry.py"
click node_skin "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/skin.py"
click node_overlay "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/overlay.py"
click node_rules "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/rules/engine.py"
click node_llm "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/llm/client.py"
click node_report "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/schemas.py"
click node_web "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/static/index.html"
click node_auth "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/auth/security.py"
click node_authdeps "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/auth/dependencies.py"
click node_dbsession "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/db/session.py"
click node_dbmodels "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/db/models.py"
click node_comparison "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/comparison/service.py"
click node_validation "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/security/validation.py"
click node_limiter "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/security/rate_limiter.py"
click node_metrics "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/monitoring/metrics.py"
click node_health "https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/main.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_api,node_quality,node_detection,node_geometry,node_skin,node_overlay,node_user toneBlue
class node_rules,node_llm,node_report toneAmber
class node_auth,node_authdeps,node_dbsession,node_dbmodels,node_comparison,node_gemini toneMint
class node_validation,node_limiter,node_metrics,node_health toneRose
class node_web toneTeal
```

## Components

### Selfie analysis

- [FastAPI service](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/main.py): `app/main.py`
- [Quality gate](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/quality.py): `app/pipeline/quality.py`
- [Face landmarks](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/face_detect.py): `app/pipeline/face_detect.py`
- [Geometry metrics](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/geometry.py): `app/pipeline/geometry.py`
- [Skin metrics](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/skin.py): `app/pipeline/skin.py`
- [Visual overlays](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/pipeline/overlay.py): `app/pipeline/overlay.py`

### Recommendations and reports

- [Recommendation rules](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/rules/engine.py): `app/rules/engine.py`
- [Explanation generator](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/llm/client.py): `app/llm/client.py`
- [Analysis response](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/schemas.py): `app/schemas.py`

### Accounts and history

- [Auth and tokens](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/auth/security.py): `app/auth/security.py`
- [Auth dependencies](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`
- [Database sessions](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/db/session.py): `app/db/session.py`
- [User and scans](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/db/models.py): `app/db/models.py`
- [Scan comparison](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/comparison/service.py): `app/comparison/service.py`

### Security and operations

- [Upload validation](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/security/validation.py): `app/security/validation.py`
- [Rate limiting](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/security/rate_limiter.py): `app/security/rate_limiter.py`
- [Metrics collector](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/monitoring/metrics.py): `app/monitoring/metrics.py`
- [Health and probes](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/app/main.py): `app/main.py`

### Other components

- **Selfie user**
- **Gemini API**
- [Web interface](https://github.com/souvikkundu0901/ai-face-analyzer/blob/main/static/index.html): `static/index.html`

## Connections

- Selfie user → FastAPI service: uploads selfie
- FastAPI service → Upload validation: validates upload
- FastAPI service → Quality gate: checks quality
- FastAPI service → Face landmarks: detects face
- FastAPI service → Geometry metrics: analyzes geometry
- FastAPI service → Skin metrics: analyzes skin
- FastAPI service → Visual overlays: builds overlays
- FastAPI service → Recommendation rules: evaluates scores
- FastAPI service → Explanation generator: requests explanation
- Explanation generator → Gemini API: calls
- Explanation generator → Analysis response: returns explanation
- FastAPI service → Analysis response: returns analysis
- Web interface → FastAPI service: uses API
- FastAPI service → Auth dependencies: checks identity
- Auth dependencies → Auth and tokens: validates tokens
- FastAPI service → Auth and tokens: issues tokens
- FastAPI service → Database sessions: opens sessions
- Database sessions → User and scans: persists records
- FastAPI service → Scan comparison: compares scans
- FastAPI service → Rate limiting: throttles requests
- FastAPI service → Metrics collector: records timings
- FastAPI service → Health and probes: serves probes