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}