alfredodompablo/monica

1. System boundary

MONICA is split into four main execution domains: a Next.js web application, a Python AI inference service, a PostgreSQL-backed data layer, and several PlatformIO-based firmware targets for IoT devices. The web app is the orchestration layer; the embedded devices and AI service are separate runtime boundaries.

2. Web application core

The main product lives under src/ and is built with Next.js App Router. It serves the public site, the dashboard, and the admin area. UI composition is mostly React components in src/components, with dashboard-specific pages under src/app/dashboard and admin login/settings screens under src/app/admin.

3. API layer inside Next.js

Instead of a separate Node backend, the application exposes backend functionality through Next.js route handlers in src/app/api/**. These endpoints cover authentication, users, nodes, readings, sensor-readings, network logs/commands, and waste detections. This means the web app is both frontend and primary application server.

4. Authentication and admin boundary

Authentication is handled by NextAuth through src/app/api/auth/[...nextauth]/route.ts and helper logic in src/lib/auth.ts. Admin-focused routes and components suggest RBAC-style separation between regular dashboard users and privileged operators. The src/proxy.ts file likely enforces request routing or auth checks at the app boundary.

5. Data persistence layer

PostgreSQL is the system of record, accessed through Prisma (src/lib/prisma.ts, src/prisma/schema.prisma). The schema is migrated and seeded from src/prisma/migrations, seed.ts, and seed_csv.ts. Historical sensor data is preloaded from src/prisma/datos_Cuauhtemoc.csv, which means the app supports both live telemetry and backfilled datasets.

6. IoT telemetry flow

Sensor and network data appear to originate from the firmware projects, then enter the web app through API endpoints such as /api/sensor-readings, /api/nodes, /api/readings, and network command/log routes. The presence of lora_protocol.h in the firmware folders indicates LoRa-based device communication, with a concentrator bridging field nodes to the application backend.

7. Firmware subsystems

There are four separate embedded targets: firmware, firmware_cam, firmware_cam_light, and firmware_concentrator. This suggests distinct hardware roles: environmental sensing nodes, camera-enabled nodes, a lighter camera variant, and a concentrator/gateway. Shared protocol definitions live in include/lora_protocol.h, while secret placeholders indicate device-specific credentials are injected per build.

8. AI inference pipeline

The AI service is isolated in ai_service/ and runs as a Python FastAPI microservice. It ships with a trained model artifact at ai_service/model/best.pt, implying local inference rather than a remote model API. The README describes a YOLOv11-seg workflow for waste segmentation, so this service is responsible for processing images and returning detection results.

9. Waste detection storage flow

Waste detection endpoints in the Next.js app connect the AI service and object storage. The documented flow is: client submits an image to /api/waste-detections, the app calls the AI service, and image artifacts are stored in MinIO/S3 via helpers in src/lib/s3.ts. Metadata stays in PostgreSQL, while the actual images are retrieved later through /api/waste-detections/[id]/image.

10. Object storage boundary

MinIO is used as the S3-compatible object store for original images and derived assets. This keeps binary media out of PostgreSQL and allows the UI to fetch galleries and detection images independently from the metadata queries. The bucket name and endpoint are externalized through environment variables.

11. UI and state management

The dashboard is organized around reusable domain components such as maps, charts, node tables, reading modals, gallery sections, and network managers. src/contexts/NodeContext.tsx and src/components/Providers.tsx indicate shared client-side state, especially for selected nodes and map-driven interactions. This is a presentation layer on top of the API and database.

12. Operational scripts and support tooling

The repo includes seed/reset scripts, key generation utilities, and a small scratch/monitor_nodes.py helper for node monitoring. There is also an openapi.json in public/, which suggests the API is documented and probably consumed externally. Docker Compose is used for local infrastructure bootstrapping, while PM2 is used to run both the Python service and the Next.js app in production-style deployments.

13. Architectural summary

The clearest diagram is: field devices and cameras feed telemetry and images into the system; the Next.js app exposes APIs and the operator UI; PostgreSQL stores relational state and history; MinIO stores binary media; the Python AI microservice processes images; and authentication gates admin and operational actions. The main integration points are HTTP between the web app and AI service, S3 between the web app and object storage, and LoRa/device protocols between firmware and the concentrator.