Inter-Service Data Flow

Complete mapping of all API calls and data exchanges between the three AESOP microservices.

Complete Flow Map

POST (push) — solid GET (pull) — dashed aesop_intell Intelligence — port 8000 aesop_modelisation Infrastructure — port 8001 aesop_simulation Simulation — port 8002 POST /webhooks/intell-entity/ push extracted entities POST /webhooks/intell-alert/ push infra alerts GET /entities/?domain=X scenario context GET /l1-reports/?domain=X intelligence briefings GET /simulation/{id}/state/ infrastructure state GET /pnaiv/ — health indicators GET /is/{id}/nodes/ — IS node positions for map POST /webhooks/simulation-action/ combat effects on infrastructure POST /webhooks/simulation-event/ sim events for analysis

Sequence: Combat Damages Infrastructure

aesop_simulation aesop_modelisation aesop_intell Combat resolve 1. VC3 vs VC4 — power plant destroyed POST /webhooks/simulation-action/ {is_node_id, damage} Cascade prop. 3. Power down → grid degrade → telecom impact GET /simulation/{id}/state/ 4. Returns degraded IS indicators Update panel 5. cap_infrastructure drops in belligerant view Infrastructure state change event 6. Notify intelligence service Generate alert 7. L1 intelligence alert created

Architecture Decisions

REST API vs WebSocket

All inter-service communication uses synchronous REST APIs. This keeps service boundaries simple, stateless, and easy to debug with standard HTTP tooling.

  • REST (HTTP) — between microservices (POST for push, GET for pull)
  • WebSocket — only for real-time multiplayer UI updates within aesop_simulation

WebSockets are scoped to the simulation front-end: turn progression, unit movements, and chat between players connected to the same game session. They never cross service boundaries.

Shared H3 Spatial Convention

All three services use the H3 hexagonal grid system at the same resolution for spatial data. This guarantees interoperability without coordinate conversion.

  • aesop_intell — entities geolocated via H3 cell index
  • aesop_modelisation — IS nodes positioned on H3 grid
  • aesop_simulation — units and terrain mapped to H3 cells

A single H3 resolution is shared across all services so that a cell ID from intelligence can be directly matched to an infrastructure node or a simulation unit position without ambiguity.

Data Format: JSON Contracts

All API payloads are JSON with explicit field contracts between services. Key data structures:

  • Entity — {id, type, domain, h3_cell, attributes, source, timestamp}
  • Alert — {id, severity, domain, description, entities[], timestamp}
  • Infrastructure State — {is_node_id, status, health_pct, cascaded_from[], h3_cell}
  • Simulation Action — {action_type, source_unit, target_node, damage, turn}
Why no message broker? The current architecture uses direct HTTP calls between services. This is simpler to deploy and debug for a three-service system. If AESOP scales to more services or needs guaranteed async delivery, a message broker (e.g., Redis Streams, RabbitMQ) would be the natural next step. See Limitations & Options for details.
POST = Push, GET = Pull. In the flow map above, solid arrows represent POST requests where a service actively pushes data to another (event-driven). Dashed arrows represent GET requests where a service pulls data on demand (query-driven). This distinction matters for understanding data ownership and timing.