# ansible/eda-server architecture

> Architecture diagram of the GitHub repository ansible/eda-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ansible/eda-server
- Repository: https://github.com/ansible/eda-server

## Overview

##### Project type and purpose
- This is a full-stack, event-driven orchestration platform (“EDA Controller”) built on Django.
- It exposes a REST/WS API, processes activations (rulebooks) via pluggable container engines (Podman/Kubernetes), manages tasks via RQ/async queues (Redis), persists state in PostgreSQL, and collects analytics.

##### File structure
- **src/aap_eda/api**: Django REST API layer (views, serializers, authentication, filters).
- **src/aap_eda/wsapi**: WebSocket consumers and routing.
- **src/aap_eda/core**: Core Django app—models, migrations, management commands, URL routing.
- **src/aap_eda/services**: Business-logic services (activation manager, status manager, container-engine factory).
- **src/aap_eda/tasks**: Background tasks/orchestrator that enqueue and schedule work.
- **src/aap_eda/analytics**: Collectors for usage/metrics.
- **src/aap_eda/conf & settings**: Configuration registry and Django settings modules.
- **scripts/** and **tools/**: Dev and deployment scripts (Docker, k8s manifests).
- Third-party integrations: AWX (Ansible Tower), external event streams (Kafka, RabbitMQ, pg_notify).

##### Key architecture insights from README/docs
- Deployment guide references PostgreSQL, Redis, nginx, TLS, Kubernetes deployments for API, workers, scheduler, UI.
- CI pipeline runs tests and builds container images.

##### Main components & interactions
a. API Layer
- Django REST Framework (src/aap_eda/api) behind NGINX (ingress).
- WebSocket endpoint (src/aap_eda/wsapi) for real-time event/status updates.
b. Persistence & Messaging
- PostgreSQL: relational data store (core models, activations, analytics).
- Redis: RQ queue for tasks (activation queue, analytics jobs, scheduler).
- Event Streams: external brokers or pg_notify for inbound events.
c. Background Workers
- Scheduler process (management command “scheduler”) dispatches activation requests to Redis.
- RQ workers (rqworker cmd) pick up tasks, call services/orchestrator.
- Orchestrator & Activation Manager: choose container engine (Podman/K8s), launch rulebook runs.
d. Container Engines
- Podman or Kubernetes abstractions (src/aap_eda/services/activation/engine).
- Each activation is run in its own container/pod, logs captured via Tee logger into DB.
e. Analytics
- Analytics collectors run periodically or per activation to gather metrics into the data warehouse.
f. External Integrations
- AWX token retrieval for credentials.
- Event streams authenticated via HMAC/JWT/OAuth2.
- SMS gateway for notifications.

##### Architectural patterns & principles
- **Layered Architecture**: Presentation (API/WS), Application (views/serializers/tasks), Domain (services/core), Infrastructure (DB, Redis, container engines).
- **Queuing & Pub-Sub**: Redis as work queue; pluggable brokers for events.
- **Polyglot Container Engines**: Factory pattern selects Podman or K8s at runtime.
- **Micro-Deployment**: Multiple k8s Deployments (api, default-worker, activation-worker, scheduler, UI).
- **Twelve-Factor App**: Config via env vars, external backing services, stateless containers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Ingress Layer"
        Client["Client"]:::external
        ING["NGINX Ingress / Load Balancer"]:::frontend
    end

    subgraph "API Layer"
        API["API Pod\n(Django REST)"]:::frontend
        WS["WebSocket Pod\n(Django Channels)"]:::frontend
    end

    subgraph "Business Logic Layer"
        SCH["Scheduler Pod\n(core.management.commands/scheduler)"]:::worker
        RW["Default Worker Pod\n(core.management.commands/rqworker)"]:::worker
        AW["Activation Worker Pod"]:::worker
        ORC["Background Orchestrator\n(tasks/orchestrator.py)"]:::worker
        ARQ["Activation Request Queue\n(tasks/activation_request_queue.py)"]:::worker
        ANL["Analytics Tasks\n(tasks/analytics.py)"]:::worker
    end

    subgraph "Services Layer"
        AM["Activation Manager\n(services/activation/activation_manager.py)"]:::service
        SM["Status Manager\n(services/activation/status_manager.py)"]:::service
        CF["Container-Engine Factory\n(services/activation/engine/factory.py)"]:::service
        ENGP["Podman Engine\n(services/activation/engine/podman.py)"]:::service
        ENGK["Kubernetes Engine\n(services/activation/engine/kubernetes.py)"]:::service
        ACOL["Analytics Collectors\n(analytics/analytics_collectors.py)"]:::service
        PGN["PostgreSQL Notify Service\n(services/pg_notify.py)"]:::service
        REG["Configuration Registry\n(conf/registry.py)"]:::service
        SET["Settings Modules\n(settings)"]:::service
    end

    subgraph "Data & Messaging"
        PG["PostgreSQL"]:::db
        RD["Redis (RQ / PubSub)"]:::db
        EB["Event Brokers\n(Kafka/RabbitMQ/pg_notify)"]:::external
    end

    subgraph "External Integrations"
        AWX["AWX Integration Utility\n(core/utils/awx.py)"]:::external
        SMG["External SMS Gateway\n(core/utils/external_sms.py)"]:::external
    end

    Client -->|HTTP/WS| ING
    ING -->|REST API| API
    ING -->|WebSocket| WS

    API -->|reads/writes| PG
    API -->|enqueue jobs| RD
    API -->|publishes events| EB
    API -->|fetch AWX creds| AWX

    SCH -->|schedules activations| RD
    SCH -->|invokes| AM

    RW -->|dequeues tasks| RD
    AW -->|dequeues tasks| RD

    ORC -->|orchestrates| AM
    ARQ -->|queues activation| RD
    ANL -->|queues analytics| RD
    ACOL -->|writes metrics| PG

    AM -->|select engine| CF
    CF -->|uses| ENGP
    CF -->|uses| ENGK

    EB -->|incoming events| API
    PG -->|notify events| PGN
    PGN -->|publishes| RD

    AM -->|send notifications| SMG

    click API "https://github.com/ansible/eda-server/tree/main/src/aap_eda/api"
    click WS "https://github.com/ansible/eda-server/tree/main/src/aap_eda/wsapi"
    click SCH "https://github.com/ansible/eda-server/blob/main/src/aap_eda/core/management/commands/scheduler.py"
    click RW "https://github.com/ansible/eda-server/blob/main/src/aap_eda/core/management/commands/rqworker.py"
    click AM "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/activation/activation_manager.py"
    click SM "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/activation/status_manager.py"
    click CF "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/activation/engine/factory.py"
    click ENGP "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/activation/engine/podman.py"
    click ENGK "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/activation/engine/kubernetes.py"
    click ORC "https://github.com/ansible/eda-server/blob/main/src/aap_eda/tasks/orchestrator.py"
    click ARQ "https://github.com/ansible/eda-server/blob/main/src/aap_eda/tasks/activation_request_queue.py"
    click ANL "https://github.com/ansible/eda-server/blob/main/src/aap_eda/tasks/analytics.py"
    click ACOL "https://github.com/ansible/eda-server/blob/main/src/aap_eda/analytics/analytics_collectors.py"
    click PGN "https://github.com/ansible/eda-server/blob/main/src/aap_eda/services/pg_notify.py"
    click REG "https://github.com/ansible/eda-server/blob/main/src/aap_eda/conf/registry.py"
    click SET "https://github.com/ansible/eda-server/tree/main/src/aap_eda/settings"
    click AWX "https://github.com/ansible/eda-server/blob/main/src/aap_eda/core/utils/awx.py"
    click SMG "https://github.com/ansible/eda-server/blob/main/src/aap_eda/core/utils/external_sms.py"

    classDef frontend fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef db fill:#10B981,stroke:#047857,color:#fff
    classDef worker fill:#F59E0B,stroke:#B45309,color:#fff
    classDef service fill:#FBBF24,stroke:#B45309,color:#000
    classDef external fill:#8B5CF6,stroke:#6D28D9,color:#fff
```
