How koubaa-hmc/edo works
1. Repository role
- edo is not a single application; it is the composition repository for an ontology-aware, Kafka-driven energy data orchestrator.
- Its main job is to pin together the ontology, shared core logic, individual socket services, frontend, and deployment wiring.
2. Top-level architecture pattern
- The system is organized as service-oriented microservices around a central Kafka bus.
- Functional services are intentionally decoupled, while the ontology acts as the shared semantic contract between them.
3. Semantic / schema layer
- schema/ontology is the semantic source of truth.
- This layer contains ontology definitions and generated model artifacts used to interpret and validate energy-domain messages across services.
- In the architecture diagram, this sits beside all services as a shared domain model, not inside any one service.
4. Socket microservices
- components/socket-rdmo is one of the functional microservices (“socket” pattern).
- Sockets are independent consumers/producers on Kafka that implement specific data-processing or integration responsibilities.
- They depend on the ontology so they can exchange semantically annotated messages rather than raw payloads.
5. Core/shared logic
- core represents shared orchestrator logic and reusable abstractions.
- Architecturally, this is the common service foundation: Kafka interaction patterns, common interfaces, and any cross-cutting orchestration behavior.
- It reduces duplication across sockets and keeps integration behavior consistent.
6. Frontend
- frontend/vue-frontend is the user-facing UI layer.
- It likely interacts with the backend services indirectly, exposing system state, configuration, or data views rather than containing business logic itself.
- For the diagram, place it as a separate client tier consuming backend APIs or service outputs.
7. Infrastructure and deployment
- infrastructure and the two Compose files define how the runtime is assembled.
- docker-compose.yml is the primary composition entry point; docker-compose_w_semantic_layer.yml suggests an alternate deployment including semantic-layer components.
- These files are the operational boundary that wires Kafka, sockets, and supporting services together.
8. Data flow
- The main flow is: ontology-backed producers publish to Kafka → socket services consume/process → results are republished or forwarded → other sockets or clients consume them.
- Kafka is the central integration fabric; services should be drawn as peers connected through the bus, not as a direct point-to-point mesh.
9. Dependency boundary
- The repository uses submodules, so schema/ontology and components/socket-rdmo are versioned as independent codebases and only referenced here.
- That means edo is an orchestration shell, not the source of truth for the subcomponent implementations.
- This is important for diagrams: the parent repo coordinates versions, but the actual services live in their own repositories.
10. Practical deployment view
- The runtime boundary is roughly:
- semantic model layer,
- Kafka infrastructure,
- service sockets,
- optional frontend.
- The architecture is optimized for independent service updates, with Compose-based local/prototype deployment and submodule-driven component management.
11. Key architectural takeaway
- If you draw this system, center it on Kafka + ontology.
- Treat edo as the integration workspace that binds together semantic definitions, microservices, and deployment configuration into one reproducible environment.
Main entry points: socket-rdmo Socket RDMO · ontology Ontology · docker-compose_w_semantic_layer.yml Compose Semantic · core Core
Components 12
Semantic Layer
Shared ontology and generated domain models.
- Ontology · Semantic source of truth for energy-domain messages.
schema/ontology
Service Layer
Kafka-connected processing and integration services.
- Core · Reusable orchestrator abstractions and cross-cutting service behavior.
core - Socket RDMO · Independent Kafka socket for domain-specific processing and integration.
components/socket-rdmo - Kafka Bus · Central message backbone connecting services.
- Producers · Ontology-backed publishers entering the bus.
- Consumers · Downstream readers of processed or forwarded messages.
- Service API · Backend interface exposed to clients and external consumers.
Client Layer
User-facing frontend.
- Frontend · User-facing interface for inspecting system state and data.
frontend/vue-frontend
Deployment
Composition and runtime wiring.
- Compose · Primary local composition entry point.
docker-compose.yml - Compose Semantic · Alternate composition including semantic-layer components.
docker-compose_w_semantic_layer.yml - Infrastructure · Runtime support and environment wiring.
infrastructure - EDO · Workspace that pins together ontology, services, frontend, and deployment.
Connections 20
- Ontology → Core: schema · Shared semantic contract consumed by common service logic.
- Ontology → Socket RDMO: models · Socket service interprets messages through ontology-backed models.
- Core → Socket RDMO: base logic · Socket inherits shared orchestrator patterns and abstractions.
- EDO → Ontology: pins · Repository workspace references the ontology submodule.
- EDO → Socket RDMO: pins · Repository workspace references the socket service submodule.
- EDO → Core: contains · Shared core logic lives in the composition workspace.
- EDO → Frontend: contains · Frontend is part of the composed workspace.
- EDO → Compose: assembles · Primary deployment composition for the repository.
- EDO → Compose Semantic: assembles · Alternate deployment including semantic-layer components.
- Compose → Kafka Bus: starts · Compose wires the Kafka event fabric into the runtime.
- Compose Semantic → Ontology: includes · Semantic-layer deployment brings ontology artifacts into runtime.
- Compose Semantic → Kafka Bus: starts · Semantic deployment also assembles the Kafka bus.
- Infrastructure → Compose: supports · Infrastructure underpins the default runtime composition.
- Infrastructure → Compose Semantic: supports · Infrastructure underpins the semantic-layer composition.
- Producers → Kafka Bus: publish · Producers send ontology-backed events into Kafka.
- Kafka Bus → Socket RDMO: consume · Socket service consumes events from the bus.
- Socket RDMO → Kafka Bus: republish · Processed results are sent back onto Kafka for downstream use.
- Socket RDMO → Service API: exposes · Socket-backed processing surfaces through service interfaces.
- Service API → Frontend: serves · Frontend consumes backend APIs or service outputs.
- Kafka Bus → Consumers: deliver · Kafka distributes processed events to downstream consumers.