# event-driven-io/emmett architecture

> Architecture diagram of the GitHub repository event-driven-io/emmett, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/event-driven-io/emmett
- Repository: https://github.com/event-driven-io/emmett

## Overview

##### Main Components
- Core Framework (Emmett): This is the heart of the system, responsible for handling command processing, event storage, subscriptions, projections, and utility functions (e.g., serialization, streaming, and validation).
- Event Store Implementations: Different modules provide integration with various storage systems (PostgreSQL, MongoDB, EventStoreDB, SQLite, In-Memory). Each can be represented as a distinct component that plugs into the core.
- Integration Modules: Packages like “emmett-expressjs” and “emmett-fastify” serve as adapters between the event sourcing logic and web frameworks. They enable the framework to expose APIs and integrate with the application’s HTTP layer.
- Testing and Utility Modules: There are packages for test containers and testing utilities that support unit, integration, and end-to-end testing strategies.
- Samples and Documentation: The “samples” directory shows real-world sample implementations that combine the above components, and the “src/docs” directory provides comprehensive documentation, including API references and usage guides.

##### Relationships and Data Flow
- How client or user actions (through web APIs in sample projects) trigger commands that are processed by the integration modules (Express.js/Fastify).
- That commands are passed to the core framework, which then creates events that are persisted by one of the available event store modules.
- How events trigger downstream behaviors such as subscriptions, projections (read model building), and potential message bus communications.
- Testing modules interacting with the core functionality for both simulating event flows and validating outcomes.

##### Architectural Patterns & Design Principles
- Modular design and separation of concerns; each package handles a specific part of the event sourcing workflow.
- Flexibility in choosing the event store (e.g., using different implementations to suit various environments).

##### Technologies
- Node.js and TypeScript (for core framework and type safety)
- Express.js/Fastify (for HTTP API integrations)
- Docker and TestContainers (for containerized testing environments)
- Various database technologies (PostgreSQL, MongoDB, etc.) for event store implementations

##### Elements
◦ Application logic (core framework and domain logic)
◦ External systems (databases, web frameworks)
◦ Utility/support components (testing tools, documentation)

- Do not oversimplify: include as many components as practical to capture the essence of how the multiple packages interact.
- Drawing separate layers—an Infrastructure layer for storage and containers (databases, docker configuration), an API/Integration layer (Express.js/Fastify), and an Application layer (core event sourcing logic, command and event handling).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        CL["Client / User Request"]:::external
    end

    subgraph "API/Integration Layer"
        EJS["Express.js Adapter"]:::integration
        FAST["Fastify Adapter"]:::integration
    end

    subgraph "Application Core"
        CORE["Core Framework (Emmett)"]:::core
    end

    subgraph "Event Stores"
        ESDB["EventStoreDB Implementation"]:::datastore
        MONGO["MongoDB Implementation"]:::datastore
        PG["PostgreSQL Implementation"]:::datastore
        SQLITE["SQLite Implementation"]:::datastore
    end

    subgraph "Testing & Utilities"
        TESTS["Testing Utilities"]:::testing
        CONTAINERS["Test Containers for Event Stores"]:::testing
    end

    subgraph "Additional Resources"
        SAMPLES["Sample Implementations"]:::resources
        DOCS["Documentation and API References"]:::resources
    end

    CL -->|"sendsRequest"| EJS
    CL -->|"sendsRequest"| FAST

    EJS -->|"forwardsCommands"| CORE
    FAST -->|"forwardsCommands"| CORE

    CORE -->|"persistsEventsTo"| ESDB
    CORE -->|"persistsEventsTo"| MONGO
    CORE -->|"persistsEventsTo"| PG
    CORE -->|"persistsEventsTo"| SQLITE

    SAMPLES -->|"demonstratesUsageOf"| EJS
    SAMPLES -->|"demonstratesUsageOf"| CORE
    DOCS -->|"describes"| CORE

    TESTS -.->|"tests"| CORE
    TESTS -.->|"tests"| ESDB
    TESTS -.->|"tests"| MONGO
    TESTS -.->|"tests"| PG
    TESTS -.->|"tests"| SQLITE

    CONTAINERS -.->|"provisions"| ESDB
    CONTAINERS -.->|"provisions"| MONGO
    CONTAINERS -.->|"provisions"| PG
    CONTAINERS -.->|"provisions"| SQLITE

    click CORE "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett"
    click ESDB "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-esdb"
    click MONGO "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-mongodb"
    click PG "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-postgresql"
    click SQLITE "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-sqlite"
    click EJS "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-expressjs"
    click FAST "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-fastify"
    click TESTS "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-tests"
    click CONTAINERS "https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-testcontainers"
    click SAMPLES "https://github.com/event-driven-io/emmett/tree/main/samples/webApi"
    click DOCS "https://github.com/event-driven-io/emmett/tree/main/src/docs"

    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef integration fill:#bbf,stroke:#333,stroke-width:2px;
    classDef core fill:#bfb,stroke:#333,stroke-width:2px;
    classDef datastore fill:#ffb,stroke:#333,stroke-width:2px;
    classDef testing fill:#fbf,stroke:#333,stroke-width:2px;
    classDef resources fill:#aff,stroke:#333,stroke-width:2px;
```
