How gustavo1986-2015/centro_de_comando_apis works
1. What this system is
This repository is a centralized telemetry hub built on FastAPI/Uvicorn. Its core job is to receive GPS/event data from multiple third-party providers, normalize it into a single canonical model, and forward it asynchronously to an external SOAP system called RC (Recurso Confiable) while exposing operational monitoring in a browser dashboard.
2. Main runtime shape
The app is split into three major execution paths: HTTP API ingress, background processing, and operator UI/monitoring. main.py is the primary entrypoint for the ASGI app, while the worker lives separately under app/worker. launcher.py and simulador_vivo.py appear to support local startup/testing and live simulation.
3. Ingress layer: push and pull
Incoming data enters in two ways:
- Push/webhooks through routers like schmitz.py and dynamic_webhook.py.
- Pull jobs through app/worker/pull_engine.py, which periodically fetches from external APIs.
Both paths feed the same downstream pipeline, so the architecture is intentionally provider-specific at the edge and canonical internally.
4. Provider translation boundary
Provider knowledge is isolated in app/providers/*, especially providers/schmitz/mapper.py. These mappers translate each vendor’s raw payload into the shared canonical schema in app/schemas/canonical.py. That boundary is important: once normalized, the rest of the system does not care which provider produced the event.
5. Canonical model and validation
app/schemas and app/models define the typed domain. Pydantic is used to validate and sanitize incoming payloads, while SQLAlchemy models persist configuration, event history, and operational state. This gives the system a hard boundary between untrusted input and trusted internal records.
6. Asynchronous queue and worker pipeline
Ingest routers do not talk directly to RC. They enqueue work through the queue abstraction in app/core/queue_interface.py, with a real SQLite-backed implementation in sqlite_queue.py and a Redis option stubbed via redis_queue.py. The worker in app/worker/processor.py drains that queue, applies throttling/concurrency control, and handles retries/backoff so provider traffic is decoupled from outbound delivery.
7. Outbound integration to RC
The final dispatch path goes through app/services/rc_soap.py, which is the integration boundary to RC over SOAP/Zeep. This is the only component that knows the external contract for RC; everything upstream feeds it canonical events. The worker handles transient failures, circuit-breaking, and retry behavior around this call.
8. Persistence layout and sharding
The repo uses SQLite for local persistence, but the architecture is intentionally fragmented by provider/environment to avoid lock contention. Configuration and event state are persisted separately from raw payload/audit artifacts, and the design treats SQLite as a lightweight operational store rather than a central shared database.
9. Configuration, caching, and secrets
app/core/config_cache.py caches system settings, while app/core/crypto.py handles encryption/decryption of stored secrets. Config changes are managed through app/api/routers/admin_config.py, so runtime behavior can be adjusted without redeploying. This is a notable boundary: operational settings are mutable, but secret material is protected at rest.
10. Audit trail and log retention
app/core/auditor.py and app/api/routers/audit_logs.py support raw payload capture and admin action logging. The architecture keeps forensic raw logs separate from operational processing, with JSONL-style logging configured via app/core/logging_config.py. This means the system has both a data plane and an evidence/traceability plane.
11. Dashboard and operator visibility
The browser UI is served from app/api/routers/dashboard.py with static assets in app/static and markup in app/templates. The dashboard is not just presentation; it is an operational console that queries stats, displays real-time updates via SSE, and exposes administrative controls for logs, retention, and system state.
12. Monitoring and data exploration APIs
Additional routers provide focused operational views:
- vehicles.py for searching event history by vehicle/patent
- db_viewer.py for inspecting SQLite-backed records
- health.py for liveness/readiness
- inspector.py for a controlled outbound API tester
These are separate read/diagnostic boundaries from the ingest/dispatch pipeline.
13. Security perimeter
The monitoring/admin surfaces are protected by shared auth in app/core/auth.py. The inspector route adds stronger outbound-safety controls, and webhook routes use strict validation/secret checks before accepting data. In the diagram, it is worth showing auth as a cross-cutting guard on all human-facing and diagnostic endpoints.
14. Key architectural flow to diagram
The most important end-to-end chain is: provider webhook or pull job → mapper/normalizer → queue → worker → RC SOAP. Around that core sits a second loop: audit/logging → dashboard/admin APIs → operator actions/config changes → cached settings/secret handling. Those two loops are the center of the repo’s architecture.
15. Useful subsystems to place separately
If you are drawing the architecture, treat these as distinct boxes: api/routers for ingress/UI, core for shared mechanics, providers for vendor translation, schemas/models for domain/persistence, services for external integrations, worker for async dispatch, and static/templates for the dashboard frontend.
Main entry points: main.py Main app · queue_interface.py Queue API · dashboard.py Dashboard · admin_config.py Admin config
Components 27
Runtime
Primary execution paths and entrypoints
Ingress
HTTP and pull-based input boundaries
- Webhooks · Provider push endpoints for incoming events
app/api/routers/schmitz.py - Dynamic hook · Dynamic webhook receiver and routing boundary
app/api/routers/dynamic_webhook.py - Dashboard · Browser-based operational console and SSE updates
app/api/routers/dashboard.py - Admin config · Operational configuration management endpoints
app/api/routers/admin_config.py - Audit logs · Audit and raw log inspection endpoints
app/api/routers/audit_logs.py - Diagnostics · Health, database viewing, vehicle search, and inspector tools
app/api/routers/health.py
Domain
Canonical model and persistence
- Provider mapper · Provider-specific normalization into canonical events
app/providers/schmitz/mapper.py - Dynamic mapper · Shared dynamic provider mapping logic
app/core/dynamic_mapper.py - Canonical schema · Trusted internal event model and validation boundary
app/schemas/canonical.py - DB models · Persistent records for config, history, and state
app/models/db_models.py - Config models · Typed configuration and admin data models
app/models/config_models.py - Database · Database connection and session wiring
app/database.py
Core
Shared mechanics and operational services
- Queue API · Interface used to decouple ingress from dispatch
app/core/queue_interface.py - SQLite queue · Primary local queue implementation
app/core/sqlite_queue.py - Redis queue · Alternative queue backend stub or option
app/core/redis_queue.py - Config cache · Caches operational settings for fast access
app/core/config_cache.py - Secrets crypto · Encrypts and decrypts stored secrets
app/core/crypto.py - Auth guard · Shared authentication for admin and diagnostic surfaces
app/core/auth.py - Auditor · Captures raw payloads and admin actions
app/core/auditor.py - Logging · Structured and retention-oriented logging setup
app/core/logging_config.py
Worker
Asynchronous processing and outbound delivery
- Pull engine · Periodic fetch path for provider APIs
app/worker/pull_engine.py - Processor · Drains queue, throttles, retries, and sends outbound
app/worker/processor.py - RC SOAP · SOAP/Zeep boundary to Recurso Confiable
app/services/rc_soap.py
UI
Operator dashboard frontend
- UI assets · HTML templates and static dashboard resources
app/templates/index.html
Connections 34
- Main app → Webhooks: serves · ASGI app exposes provider ingress routes
- Main app → Dynamic hook: serves · ASGI app exposes dynamic webhook ingress
- Main app → Dashboard: serves · ASGI app exposes operator dashboard
- Main app → Admin config: serves · ASGI app exposes admin configuration APIs
- Main app → Audit logs: serves · ASGI app exposes audit APIs
- Main app → Diagnostics: serves · ASGI app exposes health and inspection tools
- Launcher → Main app: starts · Local launcher bootstraps the ASGI app
- Simulator → Webhooks: feeds · Simulator can exercise provider ingress
- Webhooks → Provider mapper: normalizes · Provider payloads are translated into canonical events
- Dynamic hook → Dynamic mapper: maps · Dynamic webhook uses shared mapping logic
- Provider mapper → Canonical schema: produces · Vendor payloads become canonical records
- Dynamic mapper → Canonical schema: produces · Mapped events are validated as canonical data
- Pull engine → Canonical schema: pulls into · Polled provider data is normalized internally
- Provider mapper → Queue API: enqueues · Normalized events are queued for async dispatch
- Dynamic hook → Queue API: enqueues · Ingress path hands work to the queue abstraction
- Pull engine → Queue API: enqueues · Polling path forwards work through the queue layer
- Queue API → SQLite queue: implements · Primary queue backend is SQLite-backed
- Queue API → Redis queue: option · Alternative queue backend exists as a Redis option
- Queue API → Processor: drains to · Worker consumes queued jobs
- Processor → RC SOAP: dispatches · Outbound delivery goes through the SOAP boundary
- Processor → Config cache: uses · Worker reads cached operational settings
- Processor → Secrets crypto: uses · Worker relies on protected secret material
- Admin config → Config cache: updates · Admin changes refresh runtime configuration
- Admin config → Secrets crypto: protects · Admin surface manages encrypted secrets
- Dashboard → Auth guard: guarded by · Operator UI requires authentication
- Admin config → Auth guard: guarded by · Admin configuration APIs require authentication
- Audit logs → Auth guard: guarded by · Audit access is authenticated
- Diagnostics → Auth guard: guarded by · Diagnostic tools are restricted
- Dashboard → UI assets: renders · Dashboard serves HTML and static assets
- Dashboard → Auditor: shows · Dashboard surfaces audit and operational state
- Audit logs → Auditor: reads · Audit endpoints expose captured logs
- Auditor → Logging: emits · Audit trail complements structured logging
- DB models → Database: persists via · SQLAlchemy models are backed by the database layer
- Config models → DB models: shape · Configuration records are represented in persisted models