# aksubudhi/attendance-system architecture

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

- Interactive diagram: https://gitdiagram.com/aksubudhi/attendance-system
- Repository: https://github.com/aksubudhi/attendance-system

## Overview

##### Project type and purpose
- Full-stack attendance system with a decoupled React frontend (Vite) and Python FastAPI backend
- Purpose: real-time facial recognition attendance tracking, camera configuration, user management, and reporting

##### File structure
- Top-level “frontend” and “backend” directories
– frontend/src: React pages (Attendance, Cameras, Dashboard, Employees, Login) and reusable components
– backend: FastAPI entrypoint (api.py), core logic (services.py), DB setup (setup_db.py), configuration, static assets and templates for fallback/SSR if used
- Config and environment files: backend/config.py, Dockerfile, .gitignore, package.json, requirements.txt
- WebSocket and RTSP integration indicated by camera_urls.json, attendance.js, and WebSocket client code in frontend/api/client.js

##### README for additional insights
- Architecture: clearly split into Python FastAPI server + React application
- Tech stack: React, Vite, FastAPI, PostgreSQL with pgvector, insightface, FAISS, JWT auth, WebSockets
- Features: real-time camera feeds, face embedding storage/search, protected routes, Excel export

a. Main components
1. External RTSP Cameras (source of video frames)
2. Frontend (React + Vite)
– UI pages, WebSocket client for live feeds, HTTP client for REST endpoints
3. API Gateway / FastAPI Server
– REST endpoints (employee management, auth, logs, config)
– WebSocket endpoint for streaming processed frames and attendance events
4. Face Recognition Service (insightface + FAISS)
– Processes incoming frames, extracts embeddings, performs identification
5. PostgreSQL Database with pgvector
– Stores user profiles, face embeddings (vectors), attendance logs, camera configs
6. JWT Authentication Module
– Issues and verifies tokens for protected routes
b. Relationships and interactions
- Cameras → FastAPI (pulls or receives frames via RTSP)
- FastAPI → Face Recognition Service (internal function calls in services.py)
- Face Recognition Service → PostgreSQL (store/search embeddings)
- FastAPI WebSocket → Frontend (broadcast processed frames/attendance events)
- Frontend HTTP → FastAPI (CRUD for employees, cameras, logs)
- Frontend UI ←→ JWT Auth (login, protected route gating)
c. Architectural patterns and principles
- Decoupled front-end/back-end (clear separation of concerns)
- Async I/O (FastAPI’s asynchronous endpoints for high throughput)
- Event-driven streaming via WebSockets
- Modular service layer (services.py, client_attendance_api.py)
- Vector similarity search (FAISS + pgvector) for millisecond face identification
d. Key technologies, frameworks, and libraries
- React + Vite for frontend bundling and HMR
- FastAPI + uvicorn for lightweight asynchronous API
- insightface for face detection/embedding
- FAISS for nearest-neighbor search
- PostgreSQL + pgvector for persistent vector store
- JWT for authentication, WebSockets for real‐time updates

##### Diagramming recommendations
– Blue for frontend/UI
– Green for backend/API
– Orange for external services (face recognition, DB, cameras)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Devices
    subgraph "External Devices"
        Cameras["RTSP Cameras"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend (React + Vite)"
        Pages["UI Pages"]:::frontend
        Components["Reusable Components"]:::frontend
        Client["HTTP & WebSocket Client"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (FastAPI)"
        API["FastAPI Server (api.py)"]:::backend
        Auth["JWT Authentication Module"]:::backend
        AttendanceUtil["Attendance Client Utility"]:::backend
        Config["App Configuration"]:::backend
        CameraConfig["RTSP Camera Config"]:::backend
        Static["Static Assets"]:::backend
        Templates["HTML Templates"]:::backend
        Logs["Logging (app.log)"]:::backend
        Docker["Dockerfile"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% Service & Data Layer
    subgraph "Service & Data Layer"
        Services["Business Logic / Face Recognition (services.py)"]:::external
        DBInit["DB Init & Migrations (setup_db.py)"]:::backend
        Database["PostgreSQL + pgvector"]:::external
    end

    %% Interactions
    Cameras -->|RTSP frames| API
    API -->|"uses"| Services
    Services -->|SQL queries| Database
    Services -->|"init"| DBInit
    API -->|WS stream| Client
    Client -->|HTTP requests| API
    Pages -->|render UI| Client
    Components -->|used by| Pages
    Pages -->|protected by| Auth
    API -->|auth checks| Auth
    API -->|reads config| Config
    API -->|reads cam URLs| CameraConfig
    API -->|calls attendance util| AttendanceUtil
    API -->|serves assets| Static
    API -->|renders templates| Templates
    API -->|writes logs| Logs

    %% Click Events
    click Cameras "https://github.com/aksubudhi/attendance-system/blob/main/backend/camera_urls.json"
    click Pages "https://github.com/aksubudhi/attendance-system/tree/main/frontend/src/pages/"
    click Components "https://github.com/aksubudhi/attendance-system/tree/main/frontend/src/components/"
    click Client "https://github.com/aksubudhi/attendance-system/blob/main/frontend/src/api/client.js"
    click API "https://github.com/aksubudhi/attendance-system/blob/main/backend/api.py"
    click Services "https://github.com/aksubudhi/attendance-system/blob/main/backend/services.py"
    click DBInit "https://github.com/aksubudhi/attendance-system/blob/main/backend/setup_db.py"
    click Config "https://github.com/aksubudhi/attendance-system/blob/main/backend/config.py"
    click CameraConfig "https://github.com/aksubudhi/attendance-system/blob/main/backend/camera_urls.json"
    click AttendanceUtil "https://github.com/aksubudhi/attendance-system/blob/main/backend/client_attendance_api.py"
    click Static "https://github.com/aksubudhi/attendance-system/tree/main/backend/static/"
    click Templates "https://github.com/aksubudhi/attendance-system/tree/main/backend/templates/"
    click Logs "https://github.com/aksubudhi/attendance-system/blob/main/backend/logs/app.log"
    click Docker "https://github.com/aksubudhi/attendance-system/tree/main/backend/Dockerfile"
    click Requirements "https://github.com/aksubudhi/attendance-system/blob/main/backend/requirements.txt"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#333
    classDef backend fill:#D0F0C0,stroke:#333
    classDef external fill:#FFE5B4,stroke:#333
```
