How nerontad/proyecto-de-titulo works
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: main.py App main · routers Domain APIs · motor_alertas.py Alert engine · App.jsx React app
Components 24
Edge device
Arduino sensor node firmware
- Sensor node · Embedded Arduino firmware that reads environmental sensors
frontend/arduino/sensor_node/sensor_node.ino
Backend
Python API, ingestion, vision, and alert processing
- Backend entry · Python service bootstrap and application startup
backend/run.py - App main · Creates and wires the backend application
backend/app/main.py - Config · Environment and runtime configuration
backend/app/config.py - Security middleware · Request-level security checks and protection
backend/app/middleware/security.py - Auth API · Login and authentication endpoints
backend/app/routers/auth.py - Domain APIs · Business-domain HTTP endpoints for users, devices, cameras, alerts, readings, locations, types, telegram, and websocket
backend/app/routers - Auth service · Authentication and session logic
backend/app/services/auth_service.py - MQTT ingest · Receives IoT telemetry from the sensor edge
backend/app/services/mqtt_client.py - Stream service · Coordinates camera stream intake
backend/app/services/stream_service.py - Video service · Frame and video handling for camera sources
backend/app/services/video_service.py - Vision service · Runs inference and visual analysis with the ONNX model
backend/app/services/vision_service.py - Alert engine · Fuses sensor and vision evidence into alerts
backend/app/services/motor_alertas.py - Notifications · Outbound notification channels such as Telegram and WebSocket
backend/app/services/notificacion - Telegram service · Sends alerts to Telegram recipients
backend/app/services/telegram_service.py - Repositories · Data-access layer for alerts, cameras, devices, readings, users, locations, and videos
backend/app/repositories - Database · Database connection boundary
backend/app/database/connection.py - ONNX model · Vision inference model artifact
best.onnx
Frontend
React SPA for operators
- React app · Operator-facing single-page application
frontend/src/App.jsx - API client · REST client for backend APIs
frontend/src/services/api.js - Live updates · WebSocket-driven real-time updates
frontend/src/hooks/useWebSocket.js - Auth UI · Client-side auth state and protected routes
frontend/src/context/AuthContext.jsx - Pages · Dashboard, alerts, devices, cameras, login, profile, registration, and recovery screens
frontend/src/pages - UI components · Reusable UI blocks such as badges, cards, video player, shells, and navigation
frontend/src/components
Connections 24
- 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