# koubaa-hmc/edo architecture

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

- Interactive diagram: https://gitdiagram.com/koubaa-hmc/edo
- Repository: https://github.com/koubaa-hmc/edo

## Overview

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: [`components/socket-rdmo`](https://github.com/koubaa-hmc/edo/tree/main/components/socket-rdmo) (Socket RDMO), [`schema/ontology`](https://github.com/koubaa-hmc/edo/tree/main/schema/ontology) (Ontology), [`docker-compose_w_semantic_layer.yml`](https://github.com/koubaa-hmc/edo/blob/main/docker-compose_w_semantic_layer.yml) (Compose Semantic), [`core`](https://github.com/koubaa-hmc/edo/tree/main/core) (Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_semantic["Semantic Layer"]
  node_ontology["Ontology<br/>domain schema"]
end

subgraph group_services["Service Layer"]
  node_core["Core<br/>shared logic"]
  node_socket_rdmo["Socket RDMO<br/>socket service"]
  node_kafka_bus(("Kafka Bus<br/>event fabric"))
  node_producer_side["Producers<br/>event source"]
  node_consumer_side["Consumers<br/>event sink"]
  node_api_boundary["Service API<br/>interface boundary"]
end

subgraph group_client["Client Layer"]
  node_frontend["Frontend<br/>vue ui"]
end

subgraph group_deployment["Deployment"]
  node_compose_default["Compose<br/>deployment manifest<br/>[docker-compose.yml]"]
  node_compose_semantic["Compose Semantic<br/>deployment manifest"]
  node_infrastructure["Infrastructure<br/>ops support"]
  node_repo_shell{{"EDO<br/>composition repo"}}
end

node_ontology -.->|"schema"| node_core
node_ontology -.->|"models"| node_socket_rdmo
node_core -.->|"base logic"| node_socket_rdmo
node_repo_shell -.->|"pins"| node_ontology
node_repo_shell -.->|"pins"| node_socket_rdmo
node_repo_shell -.->|"contains"| node_core
node_repo_shell -.->|"contains"| node_frontend
node_repo_shell -->|"assembles"| node_compose_default
node_repo_shell -->|"assembles"| node_compose_semantic
node_compose_default -->|"starts"| node_kafka_bus
node_compose_semantic -->|"includes"| node_ontology
node_compose_semantic -->|"starts"| node_kafka_bus
node_infrastructure -.->|"supports"| node_compose_default
node_infrastructure -.->|"supports"| node_compose_semantic
node_producer_side -->|"publish"| node_kafka_bus
node_kafka_bus -->|"consume"| node_socket_rdmo
node_socket_rdmo -->|"republish"| node_kafka_bus
node_socket_rdmo -.->|"exposes"| node_api_boundary
node_api_boundary -->|"serves"| node_frontend
node_kafka_bus -->|"deliver"| node_consumer_side

click node_ontology "https://github.com/koubaa-hmc/edo/tree/main/schema/ontology"
click node_core "https://github.com/koubaa-hmc/edo/tree/main/core"
click node_socket_rdmo "https://github.com/koubaa-hmc/edo/tree/main/components/socket-rdmo"
click node_frontend "https://github.com/koubaa-hmc/edo/tree/main/frontend/vue-frontend"
click node_compose_default "https://github.com/koubaa-hmc/edo/blob/main/docker-compose.yml"
click node_compose_semantic "https://github.com/koubaa-hmc/edo/blob/main/docker-compose_w_semantic_layer.yml"
click node_infrastructure "https://github.com/koubaa-hmc/edo/tree/main/infrastructure"

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_ontology toneBlue
class node_core,node_socket_rdmo,node_kafka_bus,node_producer_side,node_consumer_side,node_api_boundary toneAmber
class node_frontend toneMint
class node_compose_default,node_compose_semantic,node_infrastructure,node_repo_shell toneRose
```

## Components

### Semantic Layer

Shared ontology and generated domain models.

- [Ontology](https://github.com/koubaa-hmc/edo/tree/main/schema/ontology): domain schema · Semantic source of truth for energy-domain messages. · `schema/ontology`

### Service Layer

Kafka-connected processing and integration services.

- [Core](https://github.com/koubaa-hmc/edo/tree/main/core): shared logic · Reusable orchestrator abstractions and cross-cutting service behavior. · `core`
- [Socket RDMO](https://github.com/koubaa-hmc/edo/tree/main/components/socket-rdmo): socket service · Independent Kafka socket for domain-specific processing and integration. · `components/socket-rdmo`
- **Kafka Bus**: event fabric · Central message backbone connecting services.
- **Producers**: event source · Ontology-backed publishers entering the bus.
- **Consumers**: event sink · Downstream readers of processed or forwarded messages.
- **Service API**: interface boundary · Backend interface exposed to clients and external consumers.

### Client Layer

User-facing frontend.

- [Frontend](https://github.com/koubaa-hmc/edo/tree/main/frontend/vue-frontend): vue ui · User-facing interface for inspecting system state and data. · `frontend/vue-frontend`

### Deployment

Composition and runtime wiring.

- [Compose](https://github.com/koubaa-hmc/edo/blob/main/docker-compose.yml): deployment manifest · Primary local composition entry point. · `docker-compose.yml`
- [Compose Semantic](https://github.com/koubaa-hmc/edo/blob/main/docker-compose_w_semantic_layer.yml): deployment manifest · Alternate composition including semantic-layer components. · `docker-compose_w_semantic_layer.yml`
- [Infrastructure](https://github.com/koubaa-hmc/edo/tree/main/infrastructure): ops support · Runtime support and environment wiring. · `infrastructure`
- **EDO**: composition repo · Workspace that pins together ontology, services, frontend, and deployment.

## Connections

- 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.