# gustavo1986-2015/centro_de_comando_apis architecture

> Architecture diagram of the GitHub repository gustavo1986-2015/centro_de_comando_apis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gustavo1986-2015/centro_de_comando_apis
- Repository: https://github.com/gustavo1986-2015/centro_de_comando_apis

## Overview

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`](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/main.py) (Main app), [`app/core/queue_interface.py`](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/queue_interface.py) (Queue API), [`app/api/routers/dashboard.py`](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/dashboard.py) (Dashboard), [`app/api/routers/admin_config.py`](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/admin_config.py) (Admin config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["Main app<br/>ASGI entrypoint<br/>[main.py]"]
  node_launcher_py["Launcher<br/>local startup<br/>[launcher.py]"]
  node_simulador_vivo_py["Simulator<br/>[simulador_vivo.py]"]
end

subgraph group_ingress["Ingress"]
  node_webhooks["Webhooks<br/>HTTP ingress<br/>[schmitz.py]"]
  node_dynamic_webhook["Dynamic hook<br/>HTTP ingress<br/>[dynamic_webhook.py]"]
  node_dashboard_router["Dashboard<br/>operator ui<br/>[dashboard.py]"]
  node_admin_router["Admin config<br/>admin api<br/>[admin_config.py]"]
  node_audit_router["Audit logs<br/>admin api<br/>[audit_logs.py]"]
  node_diagnostics["Diagnostics<br/>ops api<br/>[health.py]"]
end

subgraph group_domain["Domain"]
  node_provider_mapper["Provider mapper<br/>vendor translation<br/>[mapper.py]"]
  node_dynamic_mapper["Dynamic mapper<br/>mapping helper<br/>[dynamic_mapper.py]"]
  node_canonical_schema["Canonical schema<br/>pydantic schema<br/>[canonical.py]"]
  node_db_models[("DB models<br/>sqlalchemy models<br/>[db_models.py]")]
  node_config_models["Config models<br/>domain config<br/>[config_models.py]"]
  node_database_py[("Database<br/>sqlite bootstrap<br/>[database.py]")]
end

subgraph group_core["Core"]
  node_queue_iface["Queue API<br/>queue abstraction<br/>[queue_interface.py]"]
  node_sqlite_queue[("SQLite queue<br/>queue backend<br/>[sqlite_queue.py]")]
  node_redis_queue[("Redis queue<br/>queue backend<br/>[redis_queue.py]")]
  node_config_cache["Config cache<br/>runtime cache<br/>[config_cache.py]"]
  node_crypto["Secrets crypto<br/>secret handling<br/>[crypto.py]"]
  node_auth["Auth guard<br/>security<br/>[auth.py]"]
  node_auditor["Auditor<br/>audit trail<br/>[auditor.py]"]
  node_logging_config["Logging<br/>observability<br/>[logging_config.py]"]
end

subgraph group_worker["Worker"]
  node_pull_engine["Pull engine<br/>polling worker<br/>[pull_engine.py]"]
  node_worker_processor["Processor<br/>dispatch worker<br/>[processor.py]"]
  node_rc_soap["RC SOAP<br/>external integration<br/>[rc_soap.py]"]
end

subgraph group_ui["UI"]
  node_templates_static["UI assets<br/>frontend assets<br/>[index.html]"]
end

node_main_py -->|"serves"| node_webhooks
node_main_py -->|"serves"| node_dynamic_webhook
node_main_py -->|"serves"| node_dashboard_router
node_main_py -->|"serves"| node_admin_router
node_main_py -->|"serves"| node_audit_router
node_main_py -->|"serves"| node_diagnostics
node_launcher_py -->|"starts"| node_main_py
node_simulador_vivo_py -.->|"feeds"| node_webhooks
node_webhooks -->|"normalizes"| node_provider_mapper
node_dynamic_webhook -->|"maps"| node_dynamic_mapper
node_provider_mapper -->|"produces"| node_canonical_schema
node_dynamic_mapper -->|"produces"| node_canonical_schema
node_pull_engine -->|"pulls into"| node_canonical_schema
node_provider_mapper -->|"enqueues"| node_queue_iface
node_dynamic_webhook -->|"enqueues"| node_queue_iface
node_pull_engine -->|"enqueues"| node_queue_iface
node_queue_iface -->|"implements"| node_sqlite_queue
node_queue_iface -.->|"option"| node_redis_queue
node_queue_iface -->|"drains to"| node_worker_processor
node_worker_processor -->|"dispatches"| node_rc_soap
node_worker_processor -->|"uses"| node_config_cache
node_worker_processor -->|"uses"| node_crypto
node_admin_router -->|"updates"| node_config_cache
node_admin_router -->|"protects"| node_crypto
node_dashboard_router -->|"guarded by"| node_auth
node_admin_router -->|"guarded by"| node_auth
node_audit_router -->|"guarded by"| node_auth
node_diagnostics -->|"guarded by"| node_auth
node_dashboard_router -->|"renders"| node_templates_static
node_dashboard_router -->|"shows"| node_auditor
node_audit_router -->|"reads"| node_auditor
node_auditor -->|"emits"| node_logging_config
node_db_models -->|"persists via"| node_database_py
node_config_models -->|"shape"| node_db_models

click node_main_py "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/main.py"
click node_launcher_py "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/launcher.py"
click node_simulador_vivo_py "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/simulador_vivo.py"
click node_webhooks "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/schmitz.py"
click node_dynamic_webhook "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/dynamic_webhook.py"
click node_pull_engine "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/worker/pull_engine.py"
click node_provider_mapper "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/providers/schmitz/mapper.py"
click node_dynamic_mapper "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/dynamic_mapper.py"
click node_canonical_schema "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/schemas/canonical.py"
click node_db_models "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/models/db_models.py"
click node_config_models "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/models/config_models.py"
click node_queue_iface "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/queue_interface.py"
click node_sqlite_queue "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/sqlite_queue.py"
click node_redis_queue "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/redis_queue.py"
click node_worker_processor "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/worker/processor.py"
click node_rc_soap "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/services/rc_soap.py"
click node_config_cache "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/config_cache.py"
click node_crypto "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/crypto.py"
click node_auth "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/auth.py"
click node_auditor "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/auditor.py"
click node_logging_config "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/logging_config.py"
click node_dashboard_router "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/dashboard.py"
click node_admin_router "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/admin_config.py"
click node_audit_router "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/audit_logs.py"
click node_diagnostics "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/health.py"
click node_templates_static "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/templates/index.html"
click node_database_py "https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/database.py"

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_main_py,node_launcher_py,node_simulador_vivo_py toneBlue
class node_webhooks,node_dynamic_webhook,node_dashboard_router,node_admin_router,node_audit_router,node_diagnostics toneAmber
class node_provider_mapper,node_dynamic_mapper,node_canonical_schema,node_db_models,node_config_models,node_database_py toneMint
class node_queue_iface,node_sqlite_queue,node_redis_queue,node_config_cache,node_crypto,node_auth,node_auditor,node_logging_config toneRose
class node_pull_engine,node_worker_processor,node_rc_soap toneIndigo
class node_templates_static toneTeal
```

## Components

### Runtime

Primary execution paths and entrypoints

- [Main app](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/main.py): ASGI entrypoint · FastAPI/Uvicorn application entrypoint · `main.py`
- [Launcher](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/launcher.py): local startup · Convenience startup wrapper for local runs · `launcher.py`
- [Simulator](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/simulador_vivo.py): live simulator · Local traffic or payload simulation tool · `simulador_vivo.py`

### Ingress

HTTP and pull-based input boundaries

- [Webhooks](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/schmitz.py): HTTP ingress · Provider push endpoints for incoming events · `app/api/routers/schmitz.py`
- [Dynamic hook](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/dynamic_webhook.py): HTTP ingress · Dynamic webhook receiver and routing boundary · `app/api/routers/dynamic_webhook.py`
- [Dashboard](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/dashboard.py): operator ui · Browser-based operational console and SSE updates · `app/api/routers/dashboard.py`
- [Admin config](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/admin_config.py): admin api · Operational configuration management endpoints · `app/api/routers/admin_config.py`
- [Audit logs](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/audit_logs.py): admin api · Audit and raw log inspection endpoints · `app/api/routers/audit_logs.py`
- [Diagnostics](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/api/routers/health.py): ops api · Health, database viewing, vehicle search, and inspector tools · `app/api/routers/health.py`

### Domain

Canonical model and persistence

- [Provider mapper](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/providers/schmitz/mapper.py): vendor translation · Provider-specific normalization into canonical events · `app/providers/schmitz/mapper.py`
- [Dynamic mapper](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/dynamic_mapper.py): mapping helper · Shared dynamic provider mapping logic · `app/core/dynamic_mapper.py`
- [Canonical schema](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/schemas/canonical.py): pydantic schema · Trusted internal event model and validation boundary · `app/schemas/canonical.py`
- [DB models](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/models/db_models.py): sqlalchemy models · Persistent records for config, history, and state · `app/models/db_models.py`
- [Config models](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/models/config_models.py): domain config · Typed configuration and admin data models · `app/models/config_models.py`
- [Database](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/database.py): sqlite bootstrap · Database connection and session wiring · `app/database.py`

### Core

Shared mechanics and operational services

- [Queue API](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/queue_interface.py): queue abstraction · Interface used to decouple ingress from dispatch · `app/core/queue_interface.py`
- [SQLite queue](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/sqlite_queue.py): queue backend · Primary local queue implementation · `app/core/sqlite_queue.py`
- [Redis queue](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/redis_queue.py): queue backend · Alternative queue backend stub or option · `app/core/redis_queue.py`
- [Config cache](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/config_cache.py): runtime cache · Caches operational settings for fast access · `app/core/config_cache.py`
- [Secrets crypto](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/crypto.py): secret handling · Encrypts and decrypts stored secrets · `app/core/crypto.py`
- [Auth guard](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/auth.py): security · Shared authentication for admin and diagnostic surfaces · `app/core/auth.py`
- [Auditor](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/auditor.py): audit trail · Captures raw payloads and admin actions · `app/core/auditor.py`
- [Logging](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/core/logging_config.py): observability · Structured and retention-oriented logging setup · `app/core/logging_config.py`

### Worker

Asynchronous processing and outbound delivery

- [Pull engine](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/worker/pull_engine.py): polling worker · Periodic fetch path for provider APIs · `app/worker/pull_engine.py`
- [Processor](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/worker/processor.py): dispatch worker · Drains queue, throttles, retries, and sends outbound · `app/worker/processor.py`
- [RC SOAP](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/services/rc_soap.py): external integration · SOAP/Zeep boundary to Recurso Confiable · `app/services/rc_soap.py`

### UI

Operator dashboard frontend

- [UI assets](https://github.com/gustavo1986-2015/centro_de_comando_apis/blob/main/app/templates/index.html): frontend assets · HTML templates and static dashboard resources · `app/templates/index.html`

## Connections

- 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
