# eventum-generator/eventum architecture

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

- Interactive diagram: https://gitdiagram.com/eventum-generator/eventum
- Repository: https://github.com/eventum-generator/eventum

## Overview

#### Purpose and Entry Points
Eventum is a Python synthetic-event generation platform. A configured pipeline schedules inputs, renders or replays events, and fans them out to destinations in live or bulk modes. Primary entry points are CLI commands in `eventum/cli/commands/eventum.py`, application startup in `eventum/app/main.py`, and the combined server in `eventum/server/main.py`. Default application/startup configuration lives in `config/eventum.yml` and `config/startup.yml`.

#### Generator Core and Pipeline
The core builds validated generator configurations, initializes plugins, and executes an input → event → output pipeline. `eventum/core/generator.py` represents generator construction, `eventum/core/executor.py` drives execution, and `eventum/core/queue.py` provides the pipeline buffering boundary. Explicit stages in `eventum/core/stages/input_stage.py`, `eventum/core/stages/event_stage.py`, and `eventum/core/stages/output_stage.py` isolate scheduling, event production, and delivery.

#### Plugin Architecture
Plugins are the main extension boundary, loaded and registered through `eventum/plugins/loader.py` and `eventum/plugins/registry.py`, with common contracts under `eventum/plugins/base/plugin.py`. Input plugins emit timestamps or work items; examples include cron, HTTP, timer, and statistical time patterns under `eventum/plugins/input/plugins/`. Event plugins transform inputs into event payloads; template rendering is centered in `eventum/plugins/event/plugins/template/plugin.py`. Output plugins serialize and deliver generated events under `eventum/plugins/output/plugins/`.

#### Scheduling, Event Rendering, and Outputs
Input scheduling supports cron, fixed/static sequences, HTTP-triggered input, linspace, timestamps, timers, and time-pattern distributions, coordinated by `eventum/plugins/input/scheduler.py`. Template event generation uses Jinja-like templates plus Faker/Mimesis integrations in `eventum/plugins/event/plugins/template/modules/`. Outputs support stdout, files, HTTP, TCP/UDP, Kafka, ClickHouse, and OpenSearch; representative implementations are `eventum/plugins/output/plugins/kafka/plugin.py`, `eventum/plugins/output/plugins/clickhouse/plugin.py`, and `eventum/plugins/output/plugins/opensearch/plugin.py`. These external systems are integration boundaries rather than internal persistence dependencies.

#### Application Lifecycle, Workspaces, and Security
Application mode manages multiple independent generator instances, their lifecycle, configuration workspaces, and startup state. Key orchestration components are `eventum/app/manager.py`, `eventum/app/workspace.py`, and `eventum/app/startup/service.py`. The REST-facing application state is separated from engine execution through dependency injection in `eventum/api/dependencies/app.py`. Credentials/secrets are handled by the encrypted-keyring-oriented security layer in `eventum/security/manage.py` and `eventum/security/auth.py`.

#### Server, REST API, and Studio
The server composes API, MCP, and static UI services, with lifecycle/shutdown coordination in `eventum/server/main.py` and `eventum/server/shutdown.py`. The REST API is assembled in `eventum/api/main.py`; routers expose generators, instances, previews, scenarios, secrets, startup state, and auth, notably `eventum/api/routers/generators/routes.py`, `eventum/api/routers/preview/routes.py`, and `eventum/api/routers/scenarios/routes.py`. The bundled Eventum Studio is a TypeScript/React/Vite frontend rooted at `eventum/ui/src/main.tsx`, with API client bindings in `eventum/ui/src/api/client.ts` and project editing workspace in `eventum/ui/src/pages/ProjectPage/`.

#### MCP and Operational Interfaces
An MCP server gives AI assistants controlled access to authoring, live operation, previews, scenarios, secrets, and workspace files. Its server and context boundary are `eventum/mcp/server.py` and `eventum/mcp/context.py`; callable capabilities are grouped in `eventum/mcp/tools/`. Server-side MCP injection and authentication are isolated in `eventum/server/services/mcp/injector.py` and `eventum/server/services/mcp/auth.py`. Docker deployment is defined by `Dockerfile`; integration infrastructure includes ClickHouse, Kafka, and OpenSearch in `tests/docker/docker-compose.yml`.

Main entry points: [`eventum/app/manager.py`](https://github.com/eventum-generator/eventum/blob/master/eventum/app/manager.py) (Generator manager), [`eventum/plugins/loader.py`](https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/loader.py) (Plugin loader & registry), [`eventum/mcp/server.py`](https://github.com/eventum-generator/eventum/blob/master/eventum/mcp/server.py) (MCP server & tools), [`eventum/api/main.py`](https://github.com/eventum-generator/eventum/blob/master/eventum/api/main.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI commands<br/>Python CLI<br/>[eventum.py]"]
  node_server["Combined server<br/>Python server<br/>[main.py]"]
  node_ui["Eventum Studio<br/>React/Vite UI<br/>[main.tsx]"]
  node_api["REST API<br/>API assembly<br/>[main.py]"]
  node_api_routes["Generator, preview &amp; scenario routes<br/>API routers<br/>[routes.py]"]
end

subgraph group_application["Application Runtime"]
  node_app["Application startup<br/>Application bootstrap<br/>[main.py]"]
  node_manager["Generator manager<br/>Lifecycle manager<br/>[manager.py]"]
  node_workspace["Workspaces &amp; startup state<br/>Configuration workspace<br/>[workspace.py]"]
  node_security["Secrets &amp; auth<br/>Security layer<br/>[manage.py]"]
end

subgraph group_engine["Generation Engine"]
  node_generator["Generator construction<br/>Generator core<br/>[generator.py]"]
  node_executor["Pipeline executor<br/>Execution engine<br/>[executor.py]"]
  node_input_stage["Input stage<br/>Pipeline stage<br/>[input_stage.py]"]
  node_queue["Pipeline queue<br/>Buffer boundary<br/>[queue.py]"]
  node_event_stage["Event stage<br/>Pipeline stage<br/>[event_stage.py]"]
  node_output_stage["Output stage<br/>Pipeline stage<br/>[output_stage.py]"]
end

subgraph group_plugins["Plugin System"]
  node_loader_registry["Plugin loader &amp; registry<br/>Plugin discovery<br/>[loader.py]"]
  node_input_scheduler["Input scheduler<br/>Input plugin coordinator<br/>[scheduler.py]"]
  node_template_events["Template event plugin<br/>[plugin.py]"]
  node_outputs["Output plugins<br/>Delivery integrations<br/>[plugin.py]"]
end

subgraph group_extensions["Extension Services"]
  node_mcp["MCP server &amp; tools<br/>AI control interface<br/>[server.py]"]
  node_mcp_injection["MCP injection &amp; auth<br/>Server MCP boundary<br/>[injector.py]"]
end

node_destinations[("External destinations<br/>External systems")]

node_cli -->|"starts"| node_app
node_server -->|"starts"| node_app
node_server -->|"hosts"| node_api
node_server -->|"injects"| node_mcp_injection
node_ui -->|"uses"| node_api
node_api -->|"assembles"| node_api_routes
node_api_routes -->|"operates"| node_manager
node_api -->|"authenticates"| node_security
node_app -->|"initializes"| node_manager
node_app -->|"loads"| node_workspace
node_manager -->|"constructs"| node_generator
node_manager -->|"runs"| node_executor
node_workspace -->|"supplies configuration"| node_generator
node_generator -->|"initializes plugins"| node_loader_registry
node_executor -->|"drives"| node_input_stage
node_input_stage -->|"enqueues inputs"| node_queue
node_queue -->|"buffers inputs"| node_event_stage
node_event_stage -->|"emits events"| node_output_stage
node_loader_registry -->|"registers"| node_input_scheduler
node_loader_registry -->|"registers"| node_template_events
node_loader_registry -->|"registers"| node_outputs
node_input_stage -->|"uses input plugins"| node_input_scheduler
node_event_stage -->|"renders with"| node_template_events
node_output_stage -->|"uses output plugins"| node_outputs
node_outputs -->|"delivers to"| node_destinations
node_mcp_injection -->|"hosts"| node_mcp
node_mcp -->|"controls"| node_manager
node_mcp -->|"edits"| node_workspace
node_mcp -->|"accesses via policy"| node_security

click node_cli "https://github.com/eventum-generator/eventum/blob/master/eventum/cli/commands/eventum.py"
click node_server "https://github.com/eventum-generator/eventum/blob/master/eventum/server/main.py"
click node_ui "https://github.com/eventum-generator/eventum/blob/master/eventum/ui/src/main.tsx"
click node_api "https://github.com/eventum-generator/eventum/blob/master/eventum/api/main.py"
click node_api_routes "https://github.com/eventum-generator/eventum/blob/master/eventum/api/routers/generators/routes.py"
click node_app "https://github.com/eventum-generator/eventum/blob/master/eventum/app/main.py"
click node_manager "https://github.com/eventum-generator/eventum/blob/master/eventum/app/manager.py"
click node_workspace "https://github.com/eventum-generator/eventum/blob/master/eventum/app/workspace.py"
click node_security "https://github.com/eventum-generator/eventum/blob/master/eventum/security/manage.py"
click node_generator "https://github.com/eventum-generator/eventum/blob/master/eventum/core/generator.py"
click node_executor "https://github.com/eventum-generator/eventum/blob/master/eventum/core/executor.py"
click node_input_stage "https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/input_stage.py"
click node_queue "https://github.com/eventum-generator/eventum/blob/master/eventum/core/queue.py"
click node_event_stage "https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/event_stage.py"
click node_output_stage "https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/output_stage.py"
click node_loader_registry "https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/loader.py"
click node_input_scheduler "https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/input/scheduler.py"
click node_template_events "https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/event/plugins/template/plugin.py"
click node_outputs "https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/output/plugins/kafka/plugin.py"
click node_mcp "https://github.com/eventum-generator/eventum/blob/master/eventum/mcp/server.py"
click node_mcp_injection "https://github.com/eventum-generator/eventum/blob/master/eventum/server/services/mcp/injector.py"

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_cli,node_server,node_ui,node_api,node_api_routes toneBlue
class node_app,node_manager,node_workspace,node_security toneAmber
class node_generator,node_executor,node_input_stage,node_queue,node_event_stage,node_output_stage toneMint
class node_loader_registry,node_input_scheduler,node_template_events,node_outputs toneRose
class node_mcp,node_mcp_injection toneIndigo
class node_destinations toneNeutral
```

## Components

### Interfaces

- [CLI commands](https://github.com/eventum-generator/eventum/blob/master/eventum/cli/commands/eventum.py): Python CLI · `eventum/cli/commands/eventum.py`
- [Combined server](https://github.com/eventum-generator/eventum/blob/master/eventum/server/main.py): Python server · Composes API, MCP, and static UI services. · `eventum/server/main.py`
- [Eventum Studio](https://github.com/eventum-generator/eventum/blob/master/eventum/ui/src/main.tsx): React/Vite UI · Project editing frontend. · `eventum/ui/src/main.tsx`
- [REST API](https://github.com/eventum-generator/eventum/blob/master/eventum/api/main.py): API assembly · `eventum/api/main.py`
- [Generator, preview & scenario routes](https://github.com/eventum-generator/eventum/blob/master/eventum/api/routers/generators/routes.py): API routers · `eventum/api/routers/generators/routes.py`

### Application Runtime

- [Application startup](https://github.com/eventum-generator/eventum/blob/master/eventum/app/main.py): Application bootstrap · `eventum/app/main.py`
- [Generator manager](https://github.com/eventum-generator/eventum/blob/master/eventum/app/manager.py): Lifecycle manager · Manages independent generator instances. · `eventum/app/manager.py`
- [Workspaces & startup state](https://github.com/eventum-generator/eventum/blob/master/eventum/app/workspace.py): Configuration workspace · `eventum/app/workspace.py`
- [Secrets & auth](https://github.com/eventum-generator/eventum/blob/master/eventum/security/manage.py): Security layer · Encrypted-keyring-oriented credential management. · `eventum/security/manage.py`

### Generation Engine

- [Generator construction](https://github.com/eventum-generator/eventum/blob/master/eventum/core/generator.py): Generator core · Builds validated generator configurations. · `eventum/core/generator.py`
- [Pipeline executor](https://github.com/eventum-generator/eventum/blob/master/eventum/core/executor.py): Execution engine · `eventum/core/executor.py`
- [Input stage](https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/input_stage.py): Pipeline stage · Schedules timestamps or work items. · `eventum/core/stages/input_stage.py`
- [Pipeline queue](https://github.com/eventum-generator/eventum/blob/master/eventum/core/queue.py): Buffer boundary · `eventum/core/queue.py`
- [Event stage](https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/event_stage.py): Pipeline stage · Produces event payloads. · `eventum/core/stages/event_stage.py`
- [Output stage](https://github.com/eventum-generator/eventum/blob/master/eventum/core/stages/output_stage.py): Pipeline stage · Serializes and delivers events. · `eventum/core/stages/output_stage.py`

### Plugin System

- [Plugin loader & registry](https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/loader.py): Plugin discovery · Loads and registers plugin implementations. · `eventum/plugins/loader.py`
- [Input scheduler](https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/input/scheduler.py): Input plugin coordinator · Supports cron, HTTP, timers, sequences, and distributions. · `eventum/plugins/input/scheduler.py`
- [Template event plugin](https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/event/plugins/template/plugin.py): Event plugin · Renders templates with Faker and Mimesis integrations. · `eventum/plugins/event/plugins/template/plugin.py`
- [Output plugins](https://github.com/eventum-generator/eventum/blob/master/eventum/plugins/output/plugins/kafka/plugin.py): Delivery integrations · Stdout, files, HTTP/TCP/UDP, Kafka, ClickHouse, and OpenSearch. · `eventum/plugins/output/plugins/kafka/plugin.py`

### Extension Services

- [MCP server & tools](https://github.com/eventum-generator/eventum/blob/master/eventum/mcp/server.py): AI control interface · Provides controlled authoring and live-operation capabilities. · `eventum/mcp/server.py`
- [MCP injection & auth](https://github.com/eventum-generator/eventum/blob/master/eventum/server/services/mcp/injector.py): Server MCP boundary · `eventum/server/services/mcp/injector.py`

### Other components

- **External destinations**: External systems · Kafka, ClickHouse, OpenSearch, network, and file targets.

## Connections

- CLI commands → Application startup: starts
- Combined server → Application startup: starts
- Combined server → REST API: hosts
- Combined server → MCP injection & auth: injects
- Eventum Studio → REST API: uses
- REST API → Generator, preview & scenario routes: assembles
- Generator, preview & scenario routes → Generator manager: operates
- REST API → Secrets & auth: authenticates
- Application startup → Generator manager: initializes
- Application startup → Workspaces & startup state: loads
- Generator manager → Generator construction: constructs
- Generator manager → Pipeline executor: runs
- Workspaces & startup state → Generator construction: supplies configuration
- Generator construction → Plugin loader & registry: initializes plugins
- Pipeline executor → Input stage: drives
- Input stage → Pipeline queue: enqueues inputs
- Pipeline queue → Event stage: buffers inputs
- Event stage → Output stage: emits events
- Plugin loader & registry → Input scheduler: registers
- Plugin loader & registry → Template event plugin: registers
- Plugin loader & registry → Output plugins: registers
- Input stage → Input scheduler: uses input plugins
- Event stage → Template event plugin: renders with
- Output stage → Output plugins: uses output plugins
- Output plugins → External destinations: delivers to
- MCP injection & auth → MCP server & tools: hosts
- MCP server & tools → Generator manager: controls
- MCP server & tools → Workspaces & startup state: edits
- MCP server & tools → Secrets & auth: accesses via policy