# mriganka-dev/emotion-lens architecture

> Architecture diagram of the GitHub repository mriganka-dev/emotion-lens, 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/mriganka-dev/emotion-lens
- Repository: https://github.com/mriganka-dev/emotion-lens

## Overview

Emotion Lens is a web app for analyzing facial expressions in uploaded images. Users navigate to the scanner, submit an image, and receive per-face emotion scores and overlays; the backend validates and normalizes the image, detects faces (with a documented whole-image fallback), preprocesses crops, and classifies them. The graph also preserves the home/about pages and health endpoint. Backend call relationships are supported by excerpts; frontend scanner-to-API wiring is shown as unverified because its source was not excerpted.

Main entry points: [`backend/app/services/pipeline.py`](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/pipeline.py) (Analysis orchestration), [`backend/app/routes/predict.py`](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/routes/predict.py) (Emotion API), [`backend/app/main.py`](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/main.py) (FastAPI startup), [`frontend/src/App.tsx`](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/App.tsx) (Routes and app shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Routes and app shell<br/>[App.tsx]"]
  node_home["Home page<br/>[HomePage.tsx]"]
  node_about["About page<br/>[AboutPage.tsx]"]
end

subgraph group_scan["Image analysis UI"]
  node_scanpage["Scan page<br/>[ScanPage.tsx]"]
  node_analyzer["Analyzer interface<br/>[Analyzer.tsx]"]
  node_analysis_hook["Analysis hook<br/>[useAnalyzeImage.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API service"]
  node_browser_api["Emotion API<br/>[predict.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_server["FastAPI startup<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_schemas["Prediction schemas<br/>[prediction.py]"]
end

subgraph group_inference["Inference pipeline"]
  node_image_io["Image validation<br/>[image_io.py]"]
  node_pipeline["Analysis orchestration<br/>[pipeline.py]"]
  node_face_detector["Face detection<br/>[face_detector.py]"]
  node_preprocess["Face preprocessing<br/>[preprocessing.py]"]
  node_model["Emotion classifier<br/>[emotion_model.py]"]
end

node_visitor(("Visitor"))

node_visitor -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_scanpage
node_app -->|"routes to"| node_about
node_visitor -.->|"uploads image"| node_analyzer
node_scanpage -.->|"renders"| node_analyzer
node_analyzer -.->|"requests analysis"| node_analysis_hook
node_analysis_hook -.->|"calls"| node_api_client
node_api_client -.->|"posts image"| node_browser_api
node_server -->|"registers route"| node_health
node_server -->|"registers route"| node_browser_api
node_server -->|"initializes"| node_face_detector
node_server -->|"initializes"| node_model
node_browser_api -->|"loads image"| node_image_io
node_browser_api -->|"invokes analysis"| node_pipeline
node_pipeline -->|"detects faces"| node_face_detector
node_pipeline -->|"builds batch"| node_preprocess
node_pipeline -->|"predicts scores"| node_model
node_pipeline -->|"returns response"| node_schemas
node_browser_api -->|"returns response"| node_schemas
node_health -->|"uses response"| node_schemas

click node_app "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/HomePage.tsx"
click node_about "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/AboutPage.tsx"
click node_scanpage "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/ScanPage.tsx"
click node_analyzer "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/components/analyzer/Analyzer.tsx"
click node_analysis_hook "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/hooks/useAnalyzeImage.ts"
click node_api_client "https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/lib/api.ts"
click node_browser_api "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/routes/predict.py"
click node_health "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/routes/health.py"
click node_server "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/main.py"
click node_settings "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/config.py"
click node_image_io "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/image_io.py"
click node_pipeline "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/pipeline.py"
click node_face_detector "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/face_detector.py"
click node_preprocess "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/preprocessing.py"
click node_model "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/emotion_model.py"
click node_schemas "https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/schemas/prediction.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_app,node_home,node_about toneBlue
class node_scanpage,node_analyzer,node_analysis_hook,node_api_client toneAmber
class node_browser_api,node_health,node_server,node_settings,node_schemas toneMint
class node_image_io,node_pipeline,node_face_detector,node_preprocess,node_model toneRose
class node_visitor toneIndigo
```

## Components

### Web application

- [Routes and app shell](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Home page](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [About page](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/AboutPage.tsx): `frontend/src/pages/AboutPage.tsx`

### Image analysis UI

- [Scan page](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/pages/ScanPage.tsx): `frontend/src/pages/ScanPage.tsx`
- [Analyzer interface](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/components/analyzer/Analyzer.tsx): `frontend/src/components/analyzer/Analyzer.tsx`
- [Analysis hook](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/hooks/useAnalyzeImage.ts): `frontend/src/hooks/useAnalyzeImage.ts`
- [API client](https://github.com/mriganka-dev/emotion-lens/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API service

- [Emotion API](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/routes/predict.py): `backend/app/routes/predict.py`
- [Health endpoint](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/routes/health.py): `backend/app/routes/health.py`
- [FastAPI startup](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Runtime settings](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/config.py): `backend/app/config.py`
- [Prediction schemas](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/schemas/prediction.py): `backend/app/schemas/prediction.py`

### Inference pipeline

- [Image validation](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/image_io.py): `backend/app/services/image_io.py`
- [Analysis orchestration](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [Face detection](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/face_detector.py): `backend/app/services/face_detector.py`
- [Face preprocessing](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/preprocessing.py): `backend/app/services/preprocessing.py`
- [Emotion classifier](https://github.com/mriganka-dev/emotion-lens/blob/main/backend/app/services/emotion_model.py): `backend/app/services/emotion_model.py`

### Other components

- **Visitor**

## Connections

- Visitor → Routes and app shell: uses
- Routes and app shell → Home page: routes to (evidence: `frontend/src/App.tsx`)
- Routes and app shell → Scan page: routes to (evidence: `frontend/src/App.tsx`)
- Routes and app shell → About page: routes to (evidence: `frontend/src/App.tsx`)
- Visitor → Analyzer interface: uploads image
- Scan page → Analyzer interface: renders
- Analyzer interface → Analysis hook: requests analysis
- Analysis hook → API client: calls
- API client → Emotion API: posts image
- FastAPI startup → Health endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI startup → Emotion API: registers route (evidence: `backend/app/main.py`)
- FastAPI startup → Face detection: initializes (evidence: `backend/app/main.py`)
- FastAPI startup → Emotion classifier: initializes (evidence: `backend/app/main.py`)
- Emotion API → Image validation: loads image (evidence: `backend/app/routes/predict.py`)
- Emotion API → Analysis orchestration: invokes analysis (evidence: `backend/app/routes/predict.py`)
- Analysis orchestration → Face detection: detects faces (evidence: `backend/app/services/pipeline.py`)
- Analysis orchestration → Face preprocessing: builds batch (evidence: `backend/app/services/pipeline.py`)
- Analysis orchestration → Emotion classifier: predicts scores (evidence: `backend/app/services/pipeline.py`)
- Analysis orchestration → Prediction schemas: returns response (evidence: `backend/app/services/pipeline.py`)
- Emotion API → Prediction schemas: returns response (evidence: `backend/app/routes/predict.py`)
- Health endpoint → Prediction schemas: uses response (evidence: `backend/app/routes/health.py`)
