# germanica-1/face-embedding-api architecture

> Architecture diagram of the GitHub repository germanica-1/face-embedding-api, 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/germanica-1/face-embedding-api
- Repository: https://github.com/germanica-1/face-embedding-api

## Overview

This Flask backend accepts student images for face-embedding generation and syncing, and accepts face-match requests from clients such as the Raspberry Pi. Its main stages are image decoding, face detection and embedding, student matching, attendance logging, and parent email notification. The graph also shows the Supabase-backed student data operations and local embedding mirror. The README documents the capabilities; the sampled source supports the depicted calls, but the referenced local student JSON file is not present in the supplied tree.

Main entry points: [`app.py`](https://github.com/germanica-1/face-embedding-api/blob/main/app.py) (Flask Service), [`app/routes.py`](https://github.com/germanica-1/face-embedding-api/blob/main/app/routes.py) (Match and Sync Routes), [`processing/face_embeddings.py`](https://github.com/germanica-1/face-embedding-api/blob/main/processing/face_embeddings.py) (Embedding Sync), [`processing/recog_logs.py`](https://github.com/germanica-1/face-embedding-api/blob/main/processing/recog_logs.py) (Attendance Logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_service["Flask Service<br/>[app.py]"]
  node_routes["Match and Sync Routes<br/>[routes.py]"]
end

subgraph group_vision["Face Processing"]
  node_faceproc["Face Detection and Embedding<br/>[face_processing.py]"]
end

subgraph group_records["Student Records"]
  node_supabase_helper["Student Embedding Updates<br/>[supabase_helper.py]"]
  node_face_embeddings["Embedding Sync<br/>[face_embeddings.py]"]
  node_localdata[("Local Embedding Files")]
end

subgraph group_alerts["Attendance Alerts"]
  node_attendance["Attendance Logging<br/>[recog_logs.py]"]
  node_email["EmailJS Sender<br/>[email_send.py]"]
end

node_client(("Frontend / Pi"))
node_supabase[("Supabase")]
node_emailjs["EmailJS"]

node_client -->|"sends images"| node_service
node_service -->|"registers routes"| node_routes
node_service -->|"fetches and updates embeddings"| node_supabase_helper
node_service -->|"processes faces"| node_faceproc
node_routes -->|"syncs embeddings"| node_face_embeddings
node_routes -->|"logs matched face"| node_attendance
node_routes -->|"reads student JSON"| node_localdata
node_face_embeddings -->|"fetches students"| node_supabase
node_face_embeddings -->|"writes embedding mirror"| node_localdata
node_supabase_helper -->|"reads and updates students"| node_supabase
node_attendance -->|"writes attendance and reads email"| node_supabase
node_attendance -->|"sends notification"| node_email
node_email -->|"posts email"| node_emailjs
node_service -->|"returns API result"| node_client

click node_service "https://github.com/germanica-1/face-embedding-api/blob/main/app.py"
click node_routes "https://github.com/germanica-1/face-embedding-api/blob/main/app/routes.py"
click node_faceproc "https://github.com/germanica-1/face-embedding-api/blob/main/processing/face_processing.py"
click node_supabase_helper "https://github.com/germanica-1/face-embedding-api/blob/main/processing/supabase_helper.py"
click node_face_embeddings "https://github.com/germanica-1/face-embedding-api/blob/main/processing/face_embeddings.py"
click node_localdata "https://github.com/germanica-1/face-embedding-api/tree/main/data"
click node_attendance "https://github.com/germanica-1/face-embedding-api/blob/main/processing/recog_logs.py"
click node_email "https://github.com/germanica-1/face-embedding-api/blob/main/processing/email_send.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_service,node_routes,node_client toneBlue
class node_faceproc,node_supabase toneAmber
class node_supabase_helper,node_face_embeddings,node_localdata toneMint
class node_attendance,node_email toneRose
class node_emailjs toneIndigo
```

## Components

### HTTP API

- [Flask Service](https://github.com/germanica-1/face-embedding-api/blob/main/app.py): `app.py`
- [Match and Sync Routes](https://github.com/germanica-1/face-embedding-api/blob/main/app/routes.py): `app/routes.py`

### Face Processing

- [Face Detection and Embedding](https://github.com/germanica-1/face-embedding-api/blob/main/processing/face_processing.py): `processing/face_processing.py`

### Student Records

- [Student Embedding Updates](https://github.com/germanica-1/face-embedding-api/blob/main/processing/supabase_helper.py): `processing/supabase_helper.py`
- [Embedding Sync](https://github.com/germanica-1/face-embedding-api/blob/main/processing/face_embeddings.py): `processing/face_embeddings.py`
- [Local Embedding Files](https://github.com/germanica-1/face-embedding-api/tree/main/data): `data`

### Attendance Alerts

- [Attendance Logging](https://github.com/germanica-1/face-embedding-api/blob/main/processing/recog_logs.py): `processing/recog_logs.py`
- [EmailJS Sender](https://github.com/germanica-1/face-embedding-api/blob/main/processing/email_send.py): `processing/email_send.py`

### Other components

- **Frontend / Pi**
- **Supabase**
- **EmailJS**

## Connections

- Frontend / Pi → Flask Service: sends images
- Flask Service → Match and Sync Routes: registers routes
- Flask Service → Student Embedding Updates: fetches and updates embeddings
- Flask Service → Face Detection and Embedding: processes faces
- Match and Sync Routes → Embedding Sync: syncs embeddings
- Match and Sync Routes → Attendance Logging: logs matched face
- Match and Sync Routes → Local Embedding Files: reads student JSON
- Embedding Sync → Supabase: fetches students
- Embedding Sync → Local Embedding Files: writes embedding mirror
- Student Embedding Updates → Supabase: reads and updates students
- Attendance Logging → Supabase: writes attendance and reads email
- Attendance Logging → EmailJS Sender: sends notification
- EmailJS Sender → EmailJS: posts email
- Flask Service → Frontend / Pi: returns API result