Event Service Agent Kata

Design Documentation

This section contains domain models, architecture patterns, and module specifications for the Event Service Agent system.

📋 Overview Documents

Core Design

Domain Model - Core domain concepts, entities, and multi-tenancy model
Database Schema - Entity relationships, indexes, and multi-tenancy patterns
Hexagonal Architecture Layers - Layering strategy and port/adapter patterns
Messages - Commands, events, and message envelope specifications
Modules & Interactions - Module boundaries and async communication patterns
Ports - Port interface contracts and adapter responsibilities

🔧 Module Specifications

Each module follows hexagonal architecture with clear boundaries:

API Module

HTTP API layer for accepting service call requests.

REST endpoints (/service-calls)
Request validation and tenant isolation
Command publishing to orchestration

Timer Module

Time-based scheduling and notifications.

Timer scheduling workflow
Due timer polling
Event publishing on expiration

Orchestration Module

Service call lifecycle orchestration.

State machine transitions
Saga coordination
Event sourcing

Execution Module

External HTTP service call execution.

HTTP client adapter
Retry policies
Result capture

🏗️ Architecture Principles

All modules adhere to these constraints (enforced in code reviews):

Single Writer Principle

Only Orchestration writes to domain tables. All other modules consume via events.

No Cross-Module DB Access

Modules query only their own tables (enforced by ports).

No Synchronous Cross-Module Calls

All inter-module communication via EventBusPort (message broker).

Idempotency Everywhere

All command/event handlers must be idempotent; keyed by (tenantId, serviceCallId).

Multi-Tenancy By Default

Every query must filter by tenant_id; every message must carry tenantId.

Architecture Decisions (ADRs) - Why we made these design choices
Development Plan - Current implementation status
Contributing Guide - How to implement these patterns

Note: Message schemas shown in messages.md are wire format contracts for documentation. The source of truth for runtime validation is the Effect Schema implementations in each module’s domain/ folder. See ADR-0011 for schema strategy.

This site is open source. Improve this page.