# nasa-ammos/aerie architecture

> Architecture diagram of the GitHub repository nasa-ammos/aerie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nasa-ammos/aerie
- Repository: https://github.com/nasa-ammos/aerie

## Overview

##### MAIN COMPONENTS
a. API Layer & Gateway
- Hasura GraphQL Engine: auto-generated schema on Postgres; exposes tables & “Actions” that call custom services.
- Optional API proxy / NGINX (deployment/proxy).
b. Microservices (“Server” modules)
- merlin-server: planning & simulation HTTP/GraphQL endpoints.
- scheduler-server: scheduling HTTP/GraphQL endpoints.
- sequencing-server: sequence-generation HTTP endpoints.
- action-server (TypeScript): executes user-defined activity commands.
- stateless-aerie: CLI tool for offline plan simulation.
c. Background Workers
- merlin-worker: listens for simulation‐completed notifications (Postgres NOTIFY) & processes result cells.
- scheduler-worker: listens for scheduling requests & produces schedule results.
d. Shared Database & Event Bus
- Postgres DB: all domain data tables (merlin, scheduler, sequencing schemas).
- Hasura metadata & migrations (deployment/hasura).
- Pub/Sub via Postgres NOTIFY channels for workers.
e. Supporting Libraries & Utilities
- merlin-driver, merlin-framework, merlin-sdk: discrete‐event simulation engine & mission model interface.
- scheduler-driver: goal‐oriented scheduler library.
- constraints, parsing-utilities, permissions, orchestration-utils, type-utils: core Java libraries plugged into servers & drivers.
f. Clients & Tests
- Web UI (external repo) → GraphQL.
- e2e-tests, load-tests, db-tests drive APIs.
- Examples and scripts show DSL usage.

##### RELATIONSHIPS & DATA FLOWS
- Client → Hasura GraphQL → either direct SQL queries or Hasura Actions → HTTP call to corresponding “server” microservice.
- “Server” microservice → reads/writes Postgres tables → triggers DB notifications.
- Worker service → subscribes to Postgres notifications → processes tasks (simulation, scheduling) → writes back results.
- Custom DSL compilers (constraints-dsl-compiler, scheduling-dsl-compiler) invoked at build or runtime inside servers/workers.
- Deployment via Docker Compose or Kubernetes: services fronted by an API gateway.

##### ARCHITECTURAL PATTERNS & PRINCIPLES
- Microservices: one service per domain → clear separation of concerns.
- CQRS / Event-Driven: Commands via GraphQL Actions; results via DB write + NOTIFY/Listen.
- Plugin pattern: mission models & DSLs loaded dynamically (via Java ServiceLoader).
- Shared database schema but isolated logical schemas (merlin, scheduler, sequencing).
- Annotation processing: Java compile-time code generation for mission models & DSL mappers.

##### TECHNOLOGIES & FRAMEWORKS
- Java + Spring-style custom server code (no Spring, plain Java/Vert.x or Express).
- Node.js/TypeScript for sequencing-server & action-server.
- Hasura GraphQL Engine for auto-generated CRUD + Actions.
- Postgres with PL/pgSQL functions & triggers.
- Docker, Docker Compose, Kubernetes manifests under deployment/.
- Gradle builds for all Java modules.
- Jest & Mocha for JS/TS unit tests; JUnit for Java.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients & Tests"
        direction TB
        UI["Web UI"]:::client
        CLI["Stateless CLI"]:::client
        E2E["End-to-End Tests"]:::client
        DBTests["DB Integration Tests"]:::client
        LoadTests["Load Testing Suite"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Hasura["Hasura GraphQL Engine"]:::api
        Proxy["NGINX API Proxy"]:::api
    end

    %% Microservices
    subgraph "Microservices"
        direction TB
        MerlinSvc["merlin-server (Java)"]:::service
        SchedulerSvc["scheduler-server (Java)"]:::service
        SequencingSvc["sequencing-server (TS)"]:::service
        ActionSvc["action-server (TS)"]:::service
    end

    %% Workers
    subgraph "Background Workers"
        direction TB
        MerlinWorker["merlin-worker"]:::worker
        SchedulerWorker["scheduler-worker"]:::worker
    end

    %% Database & Event Bus
    subgraph "Database & Event Bus"
        direction TB
        Postgres["Postgres DB"]:::db
        Metadata["Hasura Metadata & Migrations"]:::db
        InitScripts["Postgres Init Scripts"]:::db
        EventBus["Postgres NOTIFY Channels"]:::db
    end

    %% Shared Libraries
    subgraph "Shared Libraries & Utils"
        direction TB
        MerlinDriver["merlin-driver"]:::lib
        MerlinFramework["merlin-framework"]:::lib
        FrameworkProc["merlin-framework-processor"]:::lib
        FrameworkJUnit["merlin-framework-junit"]:::lib
        MerlinSDK["merlin-sdk"]:::lib
        SchedulerDrv["scheduler-driver"]:::lib
        ConstraintsLib["constraints"]:::lib
        ParsingUtils["parsing-utilities"]:::lib
        Permissions["permissions"]:::lib
        Orchestration["orchestration-utils"]:::lib
        TypeUtils["type-utils"]:::lib
    end

    %% Flows
    UI -->|"GraphQL Queries/Mutations"| Proxy
    CLI -->|"GraphQL Queries/Mutations"| Hasura
    E2E -->|HTTP/GraphQL| Hasura
    DBTests -->|SQL/GraphQL| Hasura
    LoadTests -->|HTTP Load| Proxy

    Proxy -->|"forwards to"| Hasura
    Hasura -->|"Direct CRUD or Actions"| MerlinSvc
    Hasura -->|"Direct CRUD or Actions"| SchedulerSvc
    Hasura -->|"Actions"| SequencingSvc
    Hasura -->|"Actions"| ActionSvc

    MerlinSvc -->|Reads/Writes| Postgres
    SchedulerSvc -->|Reads/Writes| Postgres
    SequencingSvc -->|Writes| Postgres
    ActionSvc -->|Writes| Postgres

    Postgres -->|NOTIFY| MerlinWorker
    Postgres -->|NOTIFY| SchedulerWorker

    MerlinWorker -->|Processes & Writes| Postgres
    SchedulerWorker -->|Processes & Writes| Postgres

    %% Libraries used by services/workers
    MerlinSvc --> MerlinDriver
    MerlinSvc --> MerlinFramework
    MerlinSvc --> FrameworkProc
    SchedulerSvc --> SchedulerDrv
    SequencingSvc --> ParsingUtils
    SequencingSvc --> Permissions
    ActionSvc --> Orchestration
    ActionSvc --> TypeUtils
    MerlinWorker --> MerlinSDK
    SchedulerWorker --> SchedulerDrv

    %% Click events
    click Hasura "https://github.com/nasa-ammos/aerie/tree/develop/deployment/hasura"
    click Proxy "https://github.com/nasa-ammos/aerie/tree/develop/deployment/proxy"
    click MerlinSvc "https://github.com/nasa-ammos/aerie/tree/develop/merlin-server/"
    click SchedulerSvc "https://github.com/nasa-ammos/aerie/tree/develop/scheduler-server/"
    click SequencingSvc "https://github.com/nasa-ammos/aerie/tree/develop/sequencing-server/"
    click ActionSvc "https://github.com/nasa-ammos/aerie/tree/develop/action-server/"
    click CLI "https://github.com/nasa-ammos/aerie/tree/develop/stateless-aerie/"
    click MerlinWorker "https://github.com/nasa-ammos/aerie/tree/develop/merlin-worker/"
    click SchedulerWorker "https://github.com/nasa-ammos/aerie/tree/develop/scheduler-worker/"
    click Metadata "https://github.com/nasa-ammos/aerie/tree/develop/deployment/hasura/metadata"
    click InitScripts "https://github.com/nasa-ammos/aerie/tree/develop/deployment/postgres-init-db/"
    click dockerPostgres "https://github.com/nasa-ammos/aerie/blob/develop/docker/Dockerfile.postgres"
    click dockerHasura "https://github.com/nasa-ammos/aerie/blob/develop/docker/Dockerfile.hasura"
    click MerlinDriver "https://github.com/nasa-ammos/aerie/tree/develop/merlin-driver/"
    click MerlinFramework "https://github.com/nasa-ammos/aerie/tree/develop/merlin-framework/"
    click FrameworkProc "https://github.com/nasa-ammos/aerie/tree/develop/merlin-framework-processor/"
    click FrameworkJUnit "https://github.com/nasa-ammos/aerie/tree/develop/merlin-framework-junit/"
    click MerlinSDK "https://github.com/nasa-ammos/aerie/tree/develop/merlin-sdk/"
    click SchedulerDrv "https://github.com/nasa-ammos/aerie/tree/develop/scheduler-driver/"
    click ConstraintsLib "https://github.com/nasa-ammos/aerie/tree/develop/constraints/"
    click ParsingUtils "https://github.com/nasa-ammos/aerie/tree/develop/parsing-utilities/"
    click Permissions "https://github.com/nasa-ammos/aerie/tree/develop/permissions/"
    click Orchestration "https://github.com/nasa-ammos/aerie/tree/develop/orchestration-utils/"
    click TypeUtils "https://github.com/nasa-ammos/aerie/tree/develop/type-utils/"
    click E2E "https://github.com/nasa-ammos/aerie/tree/develop/e2e-tests/"
    click DBTests "https://github.com/nasa-ammos/aerie/tree/develop/db-tests/"
    click LoadTests "https://github.com/nasa-ammos/aerie/tree/develop/load-tests/"
    click examples "https://github.com/nasa-ammos/aerie/tree/develop/examples/"

    %% Styles
    classDef client fill:#DAD2FF,stroke:#7266BA,color:#7266BA
    classDef api fill:#D0E8FF,stroke:#2196F3,color:#0D47A1
    classDef service fill:#C8FACC,stroke:#43A047,color:#1B5E20
    classDef worker fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef db fill:#FFF9C4,stroke:#FDD835,color:#F57F17
    classDef lib fill:#E0E0E0,stroke:#9E9E9E,color:#424242
```
