# wahib-elbessali/smartagency architecture

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

- Interactive diagram: https://gitdiagram.com/wahib-elbessali/smartagency
- Repository: https://github.com/wahib-elbessali/smartagency

## Overview

This repository implements a multi-agency operations platform with a browser console, a management/API backend, and a separately deployed computer-vision service. The main user workflow is to manage cameras and operational records in the console, send requests through the backend, and view attendance, alerts, and other AI results. AI capabilities include camera calibration and zoning, person tracking, face recognition and wanted-person alerts, emotion, fire, and weapon detection. The excerpts establish the AI service’s route mounting and the backend’s startup consumers; detailed persistence and most cross-service call sites were not sampled, so those links are omitted.

Main entry points: [`ai/features/main.py`](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/main.py) (AI API), [`backend/app/main.py`](https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/main.py) (Backend API), [`frontend/src/screens/Screen.tsx`](https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/screens/Screen.tsx) (Operations screens), [`frontend/src/api/client.ts`](https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser console"]
  node_screens["Operations screens<br/>[Screen.tsx]"]
  node_frontend_api["API client<br/>[client.ts]"]
  node_frontend_app["App routing<br/>[App.tsx]"]
end

subgraph group_backend["Management backend"]
  node_backend_app["Backend API<br/>[main.py]"]
  node_domain_routes["Domain routes"]
  node_ai_client["AI client<br/>[ai_client.py]"]
  node_domain_services["Domain services"]
  node_database[("Application database<br/>[connection.py]")]
  node_mqtt_consumers["MQTT consumers"]
  node_attendance_ws["Attendance stream<br/>[attendance.py]"]
end

subgraph group_ai["AI service"]
  node_ai_app["AI API<br/>[main.py]"]
  node_calibration["Calibration<br/>[engine.py]"]
  node_tracking["Person tracking<br/>[engine.py]"]
  node_face["Face recognition<br/>[engine.py]"]
  node_wanted["Wanted detection<br/>[engine.py]"]
  node_emotion["Emotion detection<br/>[engine.py]"]
  node_fire["Fire detection<br/>[engine.py]"]
  node_weapon["Weapon detection<br/>[engine.py]"]
  node_cloud_app["Cloud AI option<br/>[main.py]"]
end

subgraph group_integration["External systems"]
  node_camera_source["Camera feeds"]
  node_mqtt_broker["MQTT broker"]
  node_cloud_bridge["Model bridge<br/>[bridge_server.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_frontend_app
node_frontend_app -->|"routes to"| node_screens
node_screens -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_backend_app
node_backend_app -->|"mounts routers"| node_domain_routes
node_backend_app -->|"starts"| node_mqtt_consumers
node_backend_app -->|"mounts stream"| node_attendance_ws
node_mqtt_broker -->|"delivers messages"| node_mqtt_consumers
node_domain_routes -->|"AI requests"| node_ai_client
node_ai_client -->|"calls service"| node_ai_app
node_ai_app -->|"routes calibration"| node_calibration
node_ai_app -->|"routes tracking"| node_tracking
node_ai_app -->|"routes face tasks"| node_face
node_ai_app -->|"routes wanted tasks"| node_wanted
node_ai_app -->|"routes emotion tasks"| node_emotion
node_ai_app -->|"routes fire tasks"| node_fire
node_ai_app -->|"routes weapon tasks"| node_weapon
node_camera_source -->|"provides frames"| node_ai_app
node_cloud_app -.->|"uses remote models"| node_cloud_bridge

click node_screens "https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/screens/Screen.tsx"
click node_frontend_api "https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/api/client.ts"
click node_frontend_app "https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/App.tsx"
click node_backend_app "https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/main.py"
click node_domain_routes "https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/api"
click node_ai_client "https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/integrations/ai_client.py"
click node_domain_services "https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/services"
click node_database "https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/database/connection.py"
click node_mqtt_consumers "https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/mqtt"
click node_attendance_ws "https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/websocket/attendance.py"
click node_ai_app "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/main.py"
click node_calibration "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/calibration/engine.py"
click node_tracking "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/person_tracking/engine.py"
click node_face "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/face_recognition/engine.py"
click node_wanted "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/wanted_detection/engine.py"
click node_emotion "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/emotion_detection/engine.py"
click node_fire "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/fire_detection/engine.py"
click node_weapon "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/weapon_detection/engine.py"
click node_cloud_app "https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/cloud/main.py"
click node_cloud_bridge "https://github.com/wahib-elbessali/smartagency/blob/master/ai/molab_bridge/bridge_server.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_screens,node_frontend_api,node_frontend_app toneBlue
class node_backend_app,node_domain_routes,node_ai_client,node_domain_services,node_database,node_mqtt_consumers,node_attendance_ws toneAmber
class node_ai_app,node_calibration,node_tracking,node_face,node_wanted,node_emotion,node_fire,node_weapon,node_cloud_app toneMint
class node_camera_source,node_mqtt_broker,node_cloud_bridge toneRose
class node_operator toneIndigo
```

## Components

### Browser console

- [Operations screens](https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/screens/Screen.tsx): `frontend/src/screens/Screen.tsx`
- [API client](https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [App routing](https://github.com/wahib-elbessali/smartagency/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### Management backend

- [Backend API](https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/main.py): `backend/app/main.py`
- [Domain routes](https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/api): `backend/app/api`
- [AI client](https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/integrations/ai_client.py): `backend/app/integrations/ai_client.py`
- [Domain services](https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/services): `backend/app/services`
- [Application database](https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/database/connection.py): `backend/app/database/connection.py`
- [MQTT consumers](https://github.com/wahib-elbessali/smartagency/tree/master/backend/app/mqtt): `backend/app/mqtt`
- [Attendance stream](https://github.com/wahib-elbessali/smartagency/blob/master/backend/app/websocket/attendance.py): `backend/app/websocket/attendance.py`

### AI service

- [AI API](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/main.py): `ai/features/main.py`
- [Calibration](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/calibration/engine.py): `ai/features/calibration/engine.py`
- [Person tracking](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/person_tracking/engine.py): `ai/features/person_tracking/engine.py`
- [Face recognition](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/face_recognition/engine.py): `ai/features/face_recognition/engine.py`
- [Wanted detection](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/wanted_detection/engine.py): `ai/features/wanted_detection/engine.py`
- [Emotion detection](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/emotion_detection/engine.py): `ai/features/emotion_detection/engine.py`
- [Fire detection](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/fire_detection/engine.py): `ai/features/fire_detection/engine.py`
- [Weapon detection](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/weapon_detection/engine.py): `ai/features/weapon_detection/engine.py`
- [Cloud AI option](https://github.com/wahib-elbessali/smartagency/blob/master/ai/features/cloud/main.py): `ai/features/cloud/main.py`

### External systems

- **Camera feeds**
- **MQTT broker**
- [Model bridge](https://github.com/wahib-elbessali/smartagency/blob/master/ai/molab_bridge/bridge_server.py): `ai/molab_bridge/bridge_server.py`

### Other components

- **Operator**

## Connections

- Operator → App routing: uses
- App routing → Operations screens: routes to
- Operations screens → API client: requests data
- API client → Backend API: calls API
- Backend API → Domain routes: mounts routers
- Backend API → MQTT consumers: starts
- Backend API → Attendance stream: mounts stream
- MQTT broker → MQTT consumers: delivers messages
- Domain routes → AI client: AI requests
- AI client → AI API: calls service
- AI API → Calibration: routes calibration
- AI API → Person tracking: routes tracking
- AI API → Face recognition: routes face tasks
- AI API → Wanted detection: routes wanted tasks
- AI API → Emotion detection: routes emotion tasks
- AI API → Fire detection: routes fire tasks
- AI API → Weapon detection: routes weapon tasks
- Camera feeds → AI API: provides frames
- Cloud AI option → Model bridge: uses remote models