# amalvichu/fere-facial_emotion_recognition_engine architecture

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

- Interactive diagram: https://gitdiagram.com/amalvichu/fere-facial_emotion_recognition_engine
- Repository: https://github.com/amalvichu/fere-facial_emotion_recognition_engine

## Overview

This is a browser-based, real-time facial emotion recognizer. The principal workflow captures webcam frames, posts them to the FastAPI prediction endpoint, detects faces, classifies each crop using a trained CNN or mock fallback, and displays results. The frontend also smooths predictions, tracks history, and supports CSV export; status polling and model-mode reporting are part of the experience. Arrows reflect shown calls or documented transfers; unsampled details are not inferred.

Main entry points: [`frontend/src/App.jsx`](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx) (Application Controller), [`backend/main.py`](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/main.py) (FastAPI Endpoints), [`frontend/src/components/Webcam.jsx`](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/Webcam.jsx) (Camera Capture), [`backend/model_loader.py`](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/model_loader.py) (Emotion Model Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and Interface"]
  node_webcam_ui["Camera Capture<br/>[Webcam.jsx]"]
end

subgraph group_frontend["Frontend Results"]
  node_app["Application Controller<br/>[App.jsx]"]
  node_header["Status Header<br/>[Header.jsx]"]
  node_emotion_view["Emotion Card<br/>[EmotionResult.jsx]"]
  node_probability_view["Probability Bars"]
  node_smoothing["Prediction Smoothing<br/>[App.jsx]"]
  node_history["Prediction History and CSV<br/>[App.jsx]"]
end

subgraph group_service["Prediction Service"]
  node_api["FastAPI Endpoints<br/>[main.py]"]
end

subgraph group_inference["Face and Emotion Inference"]
  node_decoder["Image Decoder<br/>[utils.py]"]
  node_detector["Haar Face Detection<br/>[utils.py]"]
  node_model["Emotion Model Manager<br/>[model_loader.py]"]
  node_cnn["Emotion CNN<br/>[model_loader.py]"]
  node_weights["Model Checkpoints"]
end

node_person(("Browser User"))
node_camera(("Webcam"))

node_person -->|"starts camera"| node_webcam_ui
node_camera -->|"streams video"| node_webcam_ui
node_webcam_ui -->|"submits frames"| node_app
node_app -->|"posts frames"| node_api
node_api -->|"returns predictions"| node_app
node_app -->|"checks status"| node_api
node_api -->|"decodes image"| node_decoder
node_api -->|"detects faces"| node_detector
node_api -->|"predicts crops"| node_model
node_model -->|"runs inference"| node_cnn
node_model -->|"loads checkpoint"| node_weights
node_app -->|"smooths probabilities"| node_smoothing
node_app -->|"records predictions"| node_history
node_app -->|"passes face boxes"| node_webcam_ui
node_app -->|"renders status"| node_header
node_app -->|"renders emotion"| node_emotion_view
node_app -->|"renders probabilities"| node_probability_view

click node_webcam_ui "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/Webcam.jsx"
click node_app "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx"
click node_header "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/Header.jsx"
click node_emotion_view "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/EmotionResult.jsx"
click node_probability_view "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/ProbabilityBars.jsx"
click node_smoothing "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx"
click node_history "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/main.py"
click node_decoder "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/utils.py"
click node_detector "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/utils.py"
click node_model "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/model_loader.py"
click node_cnn "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/model_loader.py"
click node_weights "https://github.com/amalvichu/fere-facial_emotion_recognition_engine/tree/main/models"

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_webcam_ui,node_person toneBlue
class node_app,node_header,node_emotion_view,node_probability_view,node_smoothing,node_history toneAmber
class node_api toneMint
class node_decoder,node_detector,node_model,node_cnn,node_weights toneRose
class node_camera toneIndigo
```

## Components

### Capture and Interface

- [Camera Capture](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/Webcam.jsx): `frontend/src/components/Webcam.jsx`

### Frontend Results

- [Application Controller](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Status Header](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/Header.jsx): `frontend/src/components/Header.jsx`
- [Emotion Card](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/EmotionResult.jsx): `frontend/src/components/EmotionResult.jsx`
- [Probability Bars](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/components/ProbabilityBars.jsx): `frontend/src/components/ProbabilityBars.jsx`
- [Prediction Smoothing](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Prediction History and CSV](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Prediction Service

- [FastAPI Endpoints](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/main.py): `backend/main.py`

### Face and Emotion Inference

- [Image Decoder](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/utils.py): `backend/utils.py`
- [Haar Face Detection](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/utils.py): `backend/utils.py`
- [Emotion Model Manager](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/model_loader.py): `backend/model_loader.py`
- [Emotion CNN](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/blob/main/backend/model_loader.py): `backend/model_loader.py`
- [Model Checkpoints](https://github.com/amalvichu/fere-facial_emotion_recognition_engine/tree/main/models): `models`

### Other components

- **Browser User**
- **Webcam**

## Connections

- Browser User → Camera Capture: starts camera (evidence: `frontend/src/components/Webcam.jsx`)
- Webcam → Camera Capture: streams video (evidence: `README.md`)
- Camera Capture → Application Controller: submits frames (evidence: `frontend/src/components/Webcam.jsx`)
- Application Controller → FastAPI Endpoints: posts frames (evidence: `frontend/src/App.jsx`)
- FastAPI Endpoints → Application Controller: returns predictions (evidence: `frontend/src/App.jsx`)
- Application Controller → FastAPI Endpoints: checks status (evidence: `frontend/src/App.jsx`)
- FastAPI Endpoints → Image Decoder: decodes image (evidence: `backend/main.py`)
- FastAPI Endpoints → Haar Face Detection: detects faces (evidence: `backend/main.py`)
- FastAPI Endpoints → Emotion Model Manager: predicts crops (evidence: `backend/main.py`)
- Emotion Model Manager → Emotion CNN: runs inference (evidence: `backend/model_loader.py`)
- Emotion Model Manager → Model Checkpoints: loads checkpoint (evidence: `README.md`)
- Application Controller → Prediction Smoothing: smooths probabilities (evidence: `frontend/src/App.jsx`)
- Application Controller → Prediction History and CSV: records predictions (evidence: `frontend/src/App.jsx`)
- Application Controller → Camera Capture: passes face boxes (evidence: `frontend/src/App.jsx`)
- Application Controller → Status Header: renders status (evidence: `frontend/src/App.jsx`)
- Application Controller → Emotion Card: renders emotion (evidence: `frontend/src/App.jsx`)
- Application Controller → Probability Bars: renders probabilities (evidence: `frontend/src/App.jsx`)