# chengchen/event-piper architecture

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

- Interactive diagram: https://gitdiagram.com/chengchen/event-piper
- Repository: https://github.com/chengchen/event-piper

## Overview

##### Project type and purpose
- This is a small, single-purpose event-streaming microservice written in Elixir/OTP. It listens to PostgreSQL `NOTIFY` events on the `new_events` channel, reads from the `events` table, and pushes Server-Sent Events (SSE) over HTTP to live subscribers. It also supports on-demand historical replay by querying the same table.

##### File structure
- Top-level:
- config/ – environment and release configs (dev, test, prod, releases)
- lib/event_piper.ex – the application entrypoint and supervision tree
- lib/api/api_router.ex – HTTP routing (Plug + Cowboy) and SSE endpoint
- lib/business/ – core event logic:
- repo.ex: database interaction layer (Postgrex or Ecto wrapper)
- event.ex: domain model for events
- event_listener.ex: PostgreSQL LISTEN/NOTIFY subscriber and dispatcher
- postgresql/schema.sql – table schema for `events` and trigger/channel setup
- Dockerfile, Makefile – containerization and build/test orchestration
- test/ – integration tests
- mix.exs – project dependencies (Plug, Cowboy, Postgrex, etc.)

##### README for additional insights
- It confirms the single-connection LISTEN/NOTIFY approach, SSE “push” API on `/events`, `X-Consumer-Id` header for subscriber segregation, and `Last-Event-Id` header for replay.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        Clients["SSE Clients"]:::external
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["PostgreSQL Database"]:::external
        Schema["Schema & Triggers"]:::external
    end

    %% Elixir Service
    subgraph "Elixir Service" 
        Entry["EventPiper (Supervisor)"]:::service
        APIRouter["HTTP Server & SSE Router"]:::component
        Subscriber["Subscriber Manager & Broadcaster"]:::component
        subgraph "Business Logic"
            Repo["Event Repository"]:::component
            EventModel["Event Domain Model"]:::component
            Listener["PostgreSQL Listener"]:::component
        end
    end

    %% DevOps & CI
    subgraph "DevOps / CI"
        Config["Configuration (dev/test/prod/releases)"]:::external
        Docker["Dockerfile"]:::external
        Make["Makefile"]:::external
        Test["Integration Tests"]:::external
        Mix["mix.exs & mix.lock"]:::external
    end

    %% Connections
    Clients -->|"GET /events\nX-Consumer-Id\nLast-Event-Id"| APIRouter
    APIRouter -->|"register client"| Subscriber
    APIRouter -->|"historical fetch"| Repo
    Repo -->|"SELECT events"| DB
    Listener -->|"LISTEN new_events"| DB
    DB -->|"NOTIFY new_events"| Listener
    Listener -->|"new events"| Subscriber
    Subscriber -->|"push SSE"| Clients

    %% Configuration & DevOps flows
    Config -->|applies to| Entry
    Docker -->|packages| Entry
    Make -->|build & test| Entry
    Test -->|validates| Entry
    Mix -->|defines deps| Entry
    Schema -->|defines| DB

    %% Click Events
    click Schema "https://github.com/chengchen/event-piper/blob/master/postgresql/schema.sql"
    click Entry "https://github.com/chengchen/event-piper/blob/master/lib/event_piper.ex"
    click APIRouter "https://github.com/chengchen/event-piper/blob/master/lib/api/api_router.ex"
    click Repo "https://github.com/chengchen/event-piper/blob/master/lib/business/repo.ex"
    click EventModel "https://github.com/chengchen/event-piper/blob/master/lib/business/event.ex"
    click Listener "https://github.com/chengchen/event-piper/blob/master/lib/business/event_listener.ex"
    click Config "https://github.com/chengchen/event-piper/blob/master/config/config.exs"
    click Docker "https://github.com/chengchen/event-piper/tree/master/Dockerfile"
    click Make "https://github.com/chengchen/event-piper/tree/master/Makefile"
    click Test "https://github.com/chengchen/event-piper/blob/master/test/integration_test.exs"
    click Mix "https://github.com/chengchen/event-piper/blob/master/mix.exs"

    %% Styles
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef service fill:#90ee90,stroke:#333,stroke-width:1px
    classDef component fill:#ffff99,stroke:#333,stroke-width:1px
```
