# nerontad/proyecto-de-titulo architecture

> Architecture diagram of the GitHub repository nerontad/proyecto-de-titulo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nerontad/proyecto-de-titulo
- Repository: https://github.com/nerontad/proyecto-de-titulo

## Overview

1. **High-level shape**
   - This is a three-part system: an **IoT sensing edge**, a **Python backend**, and a **React frontend**.
   - The core product goal is to reduce false positives by **fusing visual evidence from cameras with environmental sensor data**.

2. **Edge / device layer**
   - `frontend/arduino/sensor_node/sensor_node.ino` is the embedded sensor node firmware.
   - It is the source of environmental readings that likely feed the backend through network messaging rather than direct HTTP.
   - This boundary matters because the system is not only browser-based; it includes a physical device layer.

3. **Backend runtime and entrypoints**
   - The backend is a **Python service** with a typical API server layout under `backend/app`.
   - `backend/run.py` and `backend/app/main.py` are the startup path.
   - `backend/Dockerfile` and `backend/.env.example` indicate containerized deployment with environment-driven configuration.

4. **API layer**
   - `backend/app/routers/*` holds the HTTP/WebSocket endpoints, grouped by domain:
     - auth, usuarios, ubicacion, camara, dispositivo, tipos, alerta, lectura, telegram, websocket.
   - These routers are the external contract for the frontend and for any integrations that push data or receive alert status.

5. **Domain and persistence boundary**
   - `backend/app/repositories/*` provides persistence access for each business entity: alerts, cameras, devices, readings, users, locations, videos, device types.
   - This suggests a data-centric design where routers call services, and services/repositories isolate the database layer.
   - `backend/app/database/connection.py` is the DB connection boundary; the exact DB is not shown, but the repository pattern implies a relational or ORM-backed store.

6. **Business logic / orchestration**
   - `backend/app/services/motor_alertas.py` is the central alert engine.
   - This is likely where sensor readings and vision outputs are correlated to decide whether an incident becomes an alert.
   - `backend/app/services/vision_service.py`, `video_service.py`, and `stream_service.py` handle camera/video ingestion and analysis.
   - `best.onnx` at the repo root is the inference model artifact used by the vision pipeline.

7. **Ingestion and streaming**
   - `backend/app/services/mqtt_client.py` is the IoT ingestion path, presumably receiving sensor node telemetry.
   - `backend/app/services/stream_service.py` and `backend/app/services/video_service.py` suggest camera stream capture and frame extraction before inference.
   - A likely flow is: camera stream -> frame processing -> ONNX inference -> alert candidate.

8. **Notifications and real-time delivery**
   - There are two notification families in the backend:
     - `backend/app/services/notificacion/*`
     - `backend/app/services/notificadores/*`
   - These appear to implement concrete channels such as **Telegram** and **WebSocket**.
   - `backend/app/routers/websocket.py` and `backend/app/services/notificacion/notificacion_websocket.py` indicate live updates to connected clients.
   - `backend/app/services/telegram_service.py` plus the Telegram router indicate outbound alert delivery to chat users.

9. **Security and identity**
   - `backend/app/services/auth_service.py`, `backend/app/utils/security.py`, and `backend/app/middleware/security.py` form the auth/security boundary.
   - `backend/app/routers/auth.py` plus `backend/app/routers/usuario.py` indicate user lifecycle and login flows.
   - This likely protects both the API and real-time channels, with role-based or token-based access.

10. **Frontend application**
   - `frontend/` is a **Vite + React** SPA.
   - `src/pages/*` shows the main user-facing screens: dashboard, alerts, cameras, devices, login, profile, registration, password recovery.
   - `src/components/*` contains reusable UI blocks for alert badges, sensor cards, video player, navigation shells, and private routing.
   - `src/context/AuthContext.jsx`, `src/hooks/useAuth.js`, and `src/components/PrivateRoute.jsx` show that auth state gates protected routes.

11. **Frontend data flow**
   - `frontend/src/services/api.js` is the REST API client to the backend.
   - `frontend/src/hooks/useWebSocket.js` is the real-time path for live alert or telemetry updates.
   - `frontend/src/services/firebase.js` indicates a Firebase integration on the client side, likely for auth or messaging support, though the main application flow still centers on the backend API.

12. **Operational concerns and testing**
   - Backend tests (`backend/tests/test_auth.py`, `test_motor_alertas.py`, `test_mqtt.py`) confirm the main architectural hotspots: authentication, alert logic, and MQTT ingestion.
   - `frontend/docker-compose.yml`, `frontend/vercel.json`, and frontend build tooling show the UI is designed for separate deployment.
   - `backend/test_config.py` and `config_stream.py` suggest environment-specific stream/model configuration outside the core code paths.

13. **How the pieces connect**
   - Sensor node telemetry enters through MQTT into the backend.
   - Camera/video streams enter through the streaming/video services.
   - The alert engine fuses both evidence sources, persists results via repositories, and publishes notifications.
   - The frontend consumes persisted data over REST and receives live status over WebSocket, presenting operators with dashboards, alert views, and camera views.

14. **Main architecture boundaries to draw**
   - Edge device boundary: Arduino sensor node.
   - Ingestion boundary: MQTT and camera stream input.
   - Core processing boundary: alert engine + vision inference.
   - Persistence boundary: repositories/database.
   - Delivery boundary: REST API, WebSocket, Telegram.
   - Presentation boundary: React SPA.

Main entry points: [`backend/app/main.py`](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/main.py) (App main), [`backend/app/routers`](https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/routers) (Domain APIs), [`backend/app/services/motor_alertas.py`](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/motor_alertas.py) (Alert engine), [`frontend/src/App.jsx`](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/App.jsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge device"]
  node_sensor_node["Sensor node<br/>firmware<br/>[sensor_node.ino]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Backend entry<br/>startup<br/>[run.py]"]
  node_app_main["App main<br/>api bootstrap<br/>[main.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_security_middleware["Security middleware<br/>[security.py]"]
  node_auth_router["Auth API<br/>router<br/>[auth.py]"]
  node_domain_routers["Domain APIs<br/>routers"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_mqtt_client["MQTT ingest<br/>[mqtt_client.py]"]
  node_stream_service["Stream service<br/>[stream_service.py]"]
  node_video_service["Video service<br/>[video_service.py]"]
  node_vision_service["Vision service<br/>[vision_service.py]"]
  node_alert_motor{{"Alert engine<br/>orchestrator<br/>[motor_alertas.py]"}}
  node_notifications["Notifications<br/>delivery"]
  node_telegram_service["Telegram service<br/>channel"]
  node_repositories[("Repositories<br/>persistence")]
  node_database[("Database<br/>db connection<br/>[connection.py]")]
  node_onnx_model["ONNX model<br/>artifact<br/>[best.onnx]"]
end

subgraph group_frontend["Frontend"]
  node_spa_app["React app<br/>spa<br/>[App.jsx]"]
  node_api_client["API client<br/>frontend service<br/>[api.js]"]
  node_realtime_hook["Live updates<br/>frontend hook<br/>[useWebSocket.js]"]
  node_auth_ui["Auth UI<br/>frontend auth<br/>[AuthContext.jsx]"]
  node_pages["Pages<br/>views"]
  node_components["UI components"]
end

node_sensor_node -->|"telemetry"| node_mqtt_client
node_backend_entry -->|"starts"| node_app_main
node_app_main -->|"loads"| node_config
node_app_main -->|"installs"| node_security_middleware
node_app_main -->|"mounts"| node_auth_router
node_app_main -->|"mounts"| node_domain_routers
node_auth_router -->|"delegates"| node_auth_service
node_domain_routers -->|"reads/writes"| node_repositories
node_domain_routers -->|"triggers"| node_alert_motor
node_mqtt_client -->|"sensor data"| node_alert_motor
node_stream_service -->|"feeds"| node_video_service
node_video_service -->|"frames"| node_vision_service
node_vision_service -->|"inference"| node_onnx_model
node_alert_motor -->|"persists"| node_repositories
node_alert_motor -->|"publishes"| node_notifications
node_notifications -->|"telegram"| node_telegram_service
node_repositories -->|"connects"| node_database
node_spa_app -->|"calls"| node_api_client
node_spa_app -->|"subscribes"| node_realtime_hook
node_spa_app -->|"protects"| node_auth_ui
node_api_client -->|"http"| node_domain_routers
node_realtime_hook -->|"websocket"| node_domain_routers
node_auth_ui -->|"gates"| node_pages
node_pages -->|"composes"| node_components

click node_sensor_node "https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/arduino/sensor_node/sensor_node.ino"
click node_backend_entry "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/run.py"
click node_app_main "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/main.py"
click node_config "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/config.py"
click node_security_middleware "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/middleware/security.py"
click node_auth_router "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/routers/auth.py"
click node_domain_routers "https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/routers"
click node_auth_service "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/auth_service.py"
click node_mqtt_client "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/mqtt_client.py"
click node_stream_service "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/stream_service.py"
click node_video_service "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/video_service.py"
click node_vision_service "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/vision_service.py"
click node_alert_motor "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/motor_alertas.py"
click node_notifications "https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/services/notificacion"
click node_telegram_service "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/telegram_service.py"
click node_repositories "https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/repositories"
click node_database "https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/database/connection.py"
click node_onnx_model "https://github.com/nerontad/proyecto-de-titulo/blob/main/best.onnx"
click node_spa_app "https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/services/api.js"
click node_realtime_hook "https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/hooks/useWebSocket.js"
click node_auth_ui "https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/context/AuthContext.jsx"
click node_pages "https://github.com/nerontad/proyecto-de-titulo/tree/main/frontend/src/pages"
click node_components "https://github.com/nerontad/proyecto-de-titulo/tree/main/frontend/src/components"

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_sensor_node toneBlue
class node_backend_entry,node_app_main,node_config,node_security_middleware,node_auth_router,node_domain_routers,node_auth_service,node_mqtt_client,node_stream_service,node_video_service,node_vision_service,node_alert_motor,node_notifications,node_telegram_service,node_repositories,node_database,node_onnx_model toneAmber
class node_spa_app,node_api_client,node_realtime_hook,node_auth_ui,node_pages,node_components toneMint
```

## Components

### Edge device

Arduino sensor node firmware

- [Sensor node](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/arduino/sensor_node/sensor_node.ino): firmware · Embedded Arduino firmware that reads environmental sensors · `frontend/arduino/sensor_node/sensor_node.ino`

### Backend

Python API, ingestion, vision, and alert processing

- [Backend entry](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/run.py): startup · Python service bootstrap and application startup · `backend/run.py`
- [App main](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/main.py): api bootstrap · Creates and wires the backend application · `backend/app/main.py`
- [Config](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/config.py): settings · Environment and runtime configuration · `backend/app/config.py`
- [Security middleware](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/middleware/security.py): middleware · Request-level security checks and protection · `backend/app/middleware/security.py`
- [Auth API](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/routers/auth.py): router · Login and authentication endpoints · `backend/app/routers/auth.py`
- [Domain APIs](https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/routers): routers · Business-domain HTTP endpoints for users, devices, cameras, alerts, readings, locations, types, telegram, and websocket · `backend/app/routers`
- [Auth service](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/auth_service.py): service · Authentication and session logic · `backend/app/services/auth_service.py`
- [MQTT ingest](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/mqtt_client.py): service · Receives IoT telemetry from the sensor edge · `backend/app/services/mqtt_client.py`
- [Stream service](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/stream_service.py): service · Coordinates camera stream intake · `backend/app/services/stream_service.py`
- [Video service](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/video_service.py): service · Frame and video handling for camera sources · `backend/app/services/video_service.py`
- [Vision service](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/vision_service.py): service · Runs inference and visual analysis with the ONNX model · `backend/app/services/vision_service.py`
- [Alert engine](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/motor_alertas.py): orchestrator · Fuses sensor and vision evidence into alerts · `backend/app/services/motor_alertas.py`
- [Notifications](https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/services/notificacion): delivery · Outbound notification channels such as Telegram and WebSocket · `backend/app/services/notificacion`
- [Telegram service](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/services/telegram_service.py): channel · Sends alerts to Telegram recipients · `backend/app/services/telegram_service.py`
- [Repositories](https://github.com/nerontad/proyecto-de-titulo/tree/main/backend/app/repositories): persistence · Data-access layer for alerts, cameras, devices, readings, users, locations, and videos · `backend/app/repositories`
- [Database](https://github.com/nerontad/proyecto-de-titulo/blob/main/backend/app/database/connection.py): db connection · Database connection boundary · `backend/app/database/connection.py`
- [ONNX model](https://github.com/nerontad/proyecto-de-titulo/blob/main/best.onnx): artifact · Vision inference model artifact · `best.onnx`

### Frontend

React SPA for operators

- [React app](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/App.jsx): spa · Operator-facing single-page application · `frontend/src/App.jsx`
- [API client](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/services/api.js): frontend service · REST client for backend APIs · `frontend/src/services/api.js`
- [Live updates](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/hooks/useWebSocket.js): frontend hook · WebSocket-driven real-time updates · `frontend/src/hooks/useWebSocket.js`
- [Auth UI](https://github.com/nerontad/proyecto-de-titulo/blob/main/frontend/src/context/AuthContext.jsx): frontend auth · Client-side auth state and protected routes · `frontend/src/context/AuthContext.jsx`
- [Pages](https://github.com/nerontad/proyecto-de-titulo/tree/main/frontend/src/pages): views · Dashboard, alerts, devices, cameras, login, profile, registration, and recovery screens · `frontend/src/pages`
- [UI components](https://github.com/nerontad/proyecto-de-titulo/tree/main/frontend/src/components): ui · Reusable UI blocks such as badges, cards, video player, shells, and navigation · `frontend/src/components`

## Connections

- Sensor node → MQTT ingest: telemetry · Environmental readings enter the backend through MQTT
- Backend entry → App main: starts · Runtime bootstrap launches the application
- App main → Config: loads · Application startup reads environment configuration
- App main → Security middleware: installs · Security middleware is attached to the application
- App main → Auth API: mounts · Auth endpoints are registered in the API
- App main → Domain APIs: mounts · Domain routers define the external HTTP/WebSocket contract
- Auth API → Auth service: delegates · Authentication routes invoke auth logic
- Domain APIs → Repositories: reads/writes · Routers access persistence through repositories
- Domain APIs → Alert engine: triggers · Domain actions can feed the alert engine
- MQTT ingest → Alert engine: sensor data · Telemetry contributes to alert evaluation
- Stream service → Video service: feeds · Stream handling passes video sources to video processing
- Video service → Vision service: frames · Video frames are analyzed for visual evidence
- Vision service → ONNX model: inference · The ONNX artifact powers vision inference
- Alert engine → Repositories: persists · Alert outcomes are stored via repositories
- Alert engine → Notifications: publishes · Alert events are broadcast to delivery channels
- Notifications → Telegram service: telegram · Telegram is one concrete notification channel
- Repositories → Database: connects · Repositories use the database connection boundary
- React app → API client: calls · The SPA consumes REST endpoints through the API client
- React app → Live updates: subscribes · The SPA receives live updates over WebSocket
- React app → Auth UI: protects · Client auth state gates private routes and sessions
- API client → Domain APIs: http · Frontend requests target backend domain endpoints
- Live updates → Domain APIs: websocket · Real-time updates are received from backend websocket endpoints
- Auth UI → Pages: gates · Protected views depend on authentication state
- Pages → UI components: composes · Screens assemble reusable UI components
