How nerontad/pyrosense works
1. Monorepo with three main execution domains
- backend/: Python API and event-processing core.
- frontend/: React/Vite single-page app for operators.
- frontend/arduino/sensor_node/: embedded sensor firmware that feeds the IoT side.
- The project’s purpose is explicit: fuse camera-based vision and environmental sensors to reduce false alarms.
2. Backend is the system hub
- backend/app/main.py and run.py are the application entrypoints.
- The backend is organized as a layered API service: routers → services → repositories → database.
- config.py, .env.example, and middleware/security.py indicate environment-driven configuration and request/security controls at the API boundary.
3. API surface is split by domain
- Routers expose distinct bounded contexts: auth, usuario, camara, dispositivo, ubicacion, lectura, alerta, tipos, vision, telegram, and websocket.
- This suggests the backend is not a single generic API; it is domain-based, with separate flows for identity, asset management, telemetry, alerts, and real-time delivery.
4. Core domain data model is persisted via repositories
- Repository classes exist per major entity: usuario, camara, dispositivo, ubicacion, lectura, alerta, tipo_dispositivo, and video_alerta.
- database/connection.py is the persistence boundary.
- The design implies a relational persistence layer accessed through repository abstraction rather than direct DB access from routers.
5. Sensor/IoT ingestion path
- services/mqtt_client.py is the likely ingress for sensor telemetry from Arduino/IoT nodes.
- lectura routes and repository indicate incoming sensor readings are stored and later used by alert logic.
- The frontend Arduino node is a separate producer of environmental data, not part of the web UI runtime.
6. Vision pipeline for camera-based detection
- services/vision_service.py, video_service.py, stream_service.py, and utils/crypto_rtsp.py form the camera/stream subsystem.
- best.onnx is the model artifact for inference, so vision is running as an ONNX-based detection pipeline.
- Camera streams are likely RTSP-based and may use encrypted RTSP credential handling.
7. Alert fusion and decisioning is centralized
- services/motor_alertas.py is the key orchestration component that likely combines:
- sensor readings,
- vision detections,
- alert thresholds/heuristics,
- and persistence of alert events.
- This is the architectural center of the “reduce false alarms by fusing two evidence sources” requirement.
8. Notification delivery is multi-channel
- services/notificacion/ contains a strategy-style notification subsystem with Telegram and WebSocket implementations.
- telegram_service.py and routers/telegram.py expose Telegram-specific integration and webhook/retry handling.
- websocket.py plus frontend WebSocket hooks indicate live alert updates to connected dashboards.
9. Frontend is an operator console, not the processing layer
- Built with React/Vite (src/main.jsx, App.jsx, pages/, components/).
- Pages cover login, dashboard, alerts, cameras, devices, profile, registration, and password recovery.
- AuthContext, PrivateRoute, and useWebSocket show that the UI depends on backend auth plus real-time alert streams.
- frontend/src/services/api.js is the HTTP boundary to the backend API.
10. External integrations matter to the architecture
- Telegram: outbound alerts and webhook handling.
- Firebase: present in both backend and frontend, likely for cloud messaging/auth/storage support or auxiliary integration.
- MQTT: sensor transport layer between embedded devices and backend.
- IP cameras / RTSP: primary visual input source.
11. Operational and delivery boundaries
- Backend is containerized via backend/Dockerfile.
- Frontend has its own docker-compose.yml and vercel.json, showing it can be deployed separately from the backend.
- This is a split-deployment system: operator UI and backend service are independently deployable.
12. Testing focuses on the critical signal-processing and integration paths
- Tests cover alert logic, MQTT behavior, notification strategy, Telegram retry/webhook flows, schema validation, crypto/RTSP utility behavior, and vision postprocessing (letterbox, nms).
- That test distribution reinforces the architectural center: sensor ingestion, vision inference, and alert dissemination.
13. Useful architecture diagram framing
- Left side: Arduino sensor nodes and IP cameras as data producers.
- Center: Backend API + services performing ingestion, persistence, vision inference, alert fusion, and notification.
- Right side: React dashboard consuming REST and WebSocket updates.
- Bottom: database and external services (MQTT broker, Telegram, Firebase).
Main entry points: motor_alertas.py Alert motor · main.py App entry · vision_service.py Vision pipeline · App.jsx UI app
Components 24
Backend
Python API, persistence, and alert processing hub
- App entry · Starts the API service and wires the application
backend/app/main.py - Config · Environment-driven settings and deployment configuration
backend/app/config.py - Security · Request/security boundary for the API
backend/app/middleware/security.py - API routers · HTTP surface split by business domain
backend/app/routers - Services · Core orchestration for ingestion, vision, alerts, and delivery
backend/app/services - Repositories · Persistence abstraction for domain entities
backend/app/repositories - Database · Relational persistence boundary
backend/app/database/connection.py - MQTT client · Consumes telemetry from IoT devices
backend/app/services/mqtt_client.py - Vision pipeline · Camera stream processing and ONNX-based detection
backend/app/services/vision_service.py - Stream service · Manages camera video input and stream handling
backend/app/services/stream_service.py - Alert motor · Combines sensor and vision evidence into alert decisions
backend/app/services/motor_alertas.py - Notifier · Routes alert delivery to Telegram and WebSocket
backend/app/services/notificacion - Telegram svc · Telegram-specific outbound notifications and webhook handling
backend/app/services/telegram_service.py - WebSocket · Live alert updates for connected clients
backend/app/routers/websocket.py
Frontend
React operator console and browser runtime
- UI app · Operator-facing single-page application
frontend/src/App.jsx - Auth & WS · Authentication context and live update hooks
frontend/src/context/AuthContext.jsx - Pages · Dashboards and operator workflows
frontend/src/pages - API client · Browser boundary to backend REST endpoints
frontend/src/services/api.js
Edge Devices
Embedded sensor producer
- Sensor node · Arduino firmware publishing environmental readings
frontend/arduino/sensor_node/sensor_node.ino
External Systems
Third-party brokers, services, and model artifact
- IP cameras · External camera inputs feeding the vision pipeline
- MQTT broker · Transport layer for sensor telemetry
- Telegram · Outbound messaging and webhook ecosystem
- Firebase · Auxiliary backend/frontend cloud dependency
backend/app/services/firebase_service.py - ONNX model · Detection model used by the vision subsystem
best.onnx
Connections 25
- App entry → Config: loads · Bootstraps runtime settings from environment
- App entry → Security: applies · Installs API boundary controls
- App entry → API routers: mounts · Exposes domain HTTP routes
- API routers → Services: calls · Routes delegate to business logic
- Services → Repositories: persists via · Domain operations write and read through repositories
- Repositories → Database: uses · Repository layer reaches the database connection
- MQTT client → MQTT broker: subscribes · Consumes IoT telemetry from the broker
- Sensor node → MQTT broker: publishes · Sends environmental sensor readings
- MQTT client → Alert motor: feeds · Telemetry becomes alert inputs
- Vision pipeline → Stream service: reads · Vision pipeline consumes camera streams
- Stream service → IP cameras: connects to · Streams originate from IP cameras
- Vision pipeline → ONNX model: infers with · Runs detection against the ONNX model
- Vision pipeline → Alert motor: feeds · Detections contribute to fusion decisions
- Alert motor → Repositories: stores alerts · Alert events are persisted
- Alert motor → Notifier: dispatches · Chosen alerts are sent to notification channels
- Notifier → Telegram svc: uses · Telegram is one delivery strategy
- Telegram svc → Telegram: sends to · Outbound messages and webhook interactions
- Notifier → WebSocket: pushes · WebSocket updates for live dashboards
- WebSocket → Auth & WS: streams to · Browser subscribes to live alert updates
- UI app → Auth & WS: uses · UI depends on auth and WebSocket state
- UI app → Pages: renders · Operator screens are composed from pages
- Pages → API client: calls · Pages fetch and mutate backend data
- API client → API routers: requests · REST client targets the API surface
- Services → Firebase: integrates · Backend may use Firebase as an auxiliary service
- UI app → Firebase: integrates · Frontend also depends on Firebase features