# koto7-io/koto7-tuma architecture

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

- Interactive diagram: https://gitdiagram.com/koto7-io/koto7-tuma
- Repository: https://github.com/koto7-io/koto7-tuma

## Overview

Tuma durably accepts provider webhooks, verifies source signatures, persists events, then dispatches Temporal delivery workflows that retry destination requests and expose exhausted failures for replay. Operators manage connections, issues, metrics, alerting, settings, and a simulated playground through the React console. The excerpts establish the inbound persistence and workflow dispatch; several backend capabilities are supported by README descriptions and indexed references, but their detailed handlers were not sampled.

Main entry points: [`internal/api/server.go`](https://github.com/koto7-io/koto7-tuma/blob/main/internal/api/server.go) (HTTP API), [`internal/storage/store.go`](https://github.com/koto7-io/koto7-tuma/blob/main/internal/storage/store.go) (Event and connection store), [`web/src/pages`](https://github.com/koto7-io/koto7-tuma/tree/main/web/src/pages) (Management pages), [`web/src/lib/api.ts`](https://github.com/koto7-io/koto7-tuma/blob/main/web/src/lib/api.ts) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Webhook intake"]
  node_api_server["HTTP API<br/>[server.go]"]
  node_source_adapters["Source adapters<br/>[adapters.go]"]
  node_event_store[("Event and connection store<br/>[store.go]")]
end

subgraph group_delivery["Delivery operations"]
  node_delivery_workflow["Retry workflow<br/>[delivery.go]"]
  node_issues_metrics["Issues and metrics<br/>[stats.go]"]
end

subgraph group_console["Operator console"]
  node_console_routes["Console routing<br/>[App.tsx]"]
  node_console_pages["Management pages"]
  node_api_client["Browser API client<br/>[api.ts]"]
  node_shared_ui["Shared console UI"]
end

subgraph group_alerts["Alerting and settings"]
  node_alert_evaluator["Alert evaluator<br/>[evaluator.go]"]
  node_notification_settings["Notification settings<br/>[settings.go]"]
  node_notification_delivery["Email and Slack<br/>[service.go]"]
end

subgraph group_playground["Playground"]
  node_playground_page["Playground UI<br/>[PlaygroundPage.tsx]"]
  node_playground_api["Playground API<br/>[playground.go]"]
  node_playground_sim["Event simulation<br/>[simulate.go]"]
end

node_provider(("Webhook provider"))
node_postgres[("Postgres")]
node_temporal["Temporal"]
node_destination(("Destination app"))
node_browser_user(("Console operator"))
node_smtp["SMTP service"]
node_slack["Slack"]

node_provider -->|"posts webhook"| node_api_server
node_api_server -->|"verifies signature"| node_source_adapters
node_api_server -->|"persists event"| node_event_store
node_event_store -->|"stores durably"| node_postgres
node_api_server -->|"starts workflow"| node_temporal
node_temporal -->|"dispatches workflow"| node_delivery_workflow
node_delivery_workflow -->|"delivers with retries"| node_destination
node_delivery_workflow -->|"records outcomes"| node_event_store
node_browser_user -->|"uses console"| node_console_routes
node_console_routes -->|"routes to"| node_console_pages
node_console_pages -->|"requests data"| node_api_client
node_api_client -->|"calls endpoints"| node_api_server
node_console_pages -->|"renders"| node_shared_ui
node_console_pages -.->|"shows issues and metrics"| node_issues_metrics
node_alert_evaluator -->|"reads delivery state"| node_event_store
node_alert_evaluator -->|"sends alerts"| node_notification_delivery
node_notification_settings -->|"loads saved settings"| node_event_store
node_notification_settings -->|"provides effective config"| node_notification_delivery
node_notification_delivery -.->|"sends email"| node_smtp
node_notification_delivery -.->|"sends direct messages"| node_slack
node_browser_user -->|"runs demo"| node_playground_page
node_playground_page -->|"controls simulation"| node_api_client
node_api_client -->|"calls demo endpoints"| node_playground_api
node_playground_api -->|"simulates events"| node_playground_sim

click node_api_server "https://github.com/koto7-io/koto7-tuma/blob/main/internal/api/server.go"
click node_source_adapters "https://github.com/koto7-io/koto7-tuma/blob/main/internal/adapters/adapters.go"
click node_event_store "https://github.com/koto7-io/koto7-tuma/blob/main/internal/storage/store.go"
click node_delivery_workflow "https://github.com/koto7-io/koto7-tuma/blob/main/internal/workflow/delivery.go"
click node_issues_metrics "https://github.com/koto7-io/koto7-tuma/blob/main/internal/storage/stats.go"
click node_console_routes "https://github.com/koto7-io/koto7-tuma/blob/main/web/src/App.tsx"
click node_console_pages "https://github.com/koto7-io/koto7-tuma/tree/main/web/src/pages"
click node_api_client "https://github.com/koto7-io/koto7-tuma/blob/main/web/src/lib/api.ts"
click node_shared_ui "https://github.com/koto7-io/koto7-tuma/tree/main/web/src/components"
click node_alert_evaluator "https://github.com/koto7-io/koto7-tuma/blob/main/internal/alerting/evaluator.go"
click node_notification_settings "https://github.com/koto7-io/koto7-tuma/blob/main/internal/notifysettings/settings.go"
click node_notification_delivery "https://github.com/koto7-io/koto7-tuma/blob/main/internal/notification/service.go"
click node_playground_page "https://github.com/koto7-io/koto7-tuma/blob/main/web/src/pages/PlaygroundPage.tsx"
click node_playground_api "https://github.com/koto7-io/koto7-tuma/blob/main/internal/api/playground.go"
click node_playground_sim "https://github.com/koto7-io/koto7-tuma/blob/main/internal/playground/simulate.go"

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_api_server,node_source_adapters,node_event_store toneBlue
class node_delivery_workflow,node_issues_metrics,node_postgres toneAmber
class node_console_routes,node_console_pages,node_api_client,node_shared_ui,node_provider toneMint
class node_alert_evaluator,node_notification_settings,node_notification_delivery toneRose
class node_playground_page,node_playground_api,node_playground_sim,node_temporal,node_destination,node_browser_user,node_smtp,node_slack toneIndigo
```

## Components

### Webhook intake

- [HTTP API](https://github.com/koto7-io/koto7-tuma/blob/main/internal/api/server.go): `internal/api/server.go`
- [Source adapters](https://github.com/koto7-io/koto7-tuma/blob/main/internal/adapters/adapters.go): `internal/adapters/adapters.go`
- [Event and connection store](https://github.com/koto7-io/koto7-tuma/blob/main/internal/storage/store.go): `internal/storage/store.go`

### Delivery operations

- [Retry workflow](https://github.com/koto7-io/koto7-tuma/blob/main/internal/workflow/delivery.go): `internal/workflow/delivery.go`
- [Issues and metrics](https://github.com/koto7-io/koto7-tuma/blob/main/internal/storage/stats.go): `internal/storage/stats.go`

### Operator console

- [Console routing](https://github.com/koto7-io/koto7-tuma/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Management pages](https://github.com/koto7-io/koto7-tuma/tree/main/web/src/pages): `web/src/pages`
- [Browser API client](https://github.com/koto7-io/koto7-tuma/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Shared console UI](https://github.com/koto7-io/koto7-tuma/tree/main/web/src/components): `web/src/components`

### Alerting and settings

- [Alert evaluator](https://github.com/koto7-io/koto7-tuma/blob/main/internal/alerting/evaluator.go): `internal/alerting/evaluator.go`
- [Notification settings](https://github.com/koto7-io/koto7-tuma/blob/main/internal/notifysettings/settings.go): `internal/notifysettings/settings.go`
- [Email and Slack](https://github.com/koto7-io/koto7-tuma/blob/main/internal/notification/service.go): `internal/notification/service.go`

### Playground

- [Playground UI](https://github.com/koto7-io/koto7-tuma/blob/main/web/src/pages/PlaygroundPage.tsx): `web/src/pages/PlaygroundPage.tsx`
- [Playground API](https://github.com/koto7-io/koto7-tuma/blob/main/internal/api/playground.go): `internal/api/playground.go`
- [Event simulation](https://github.com/koto7-io/koto7-tuma/blob/main/internal/playground/simulate.go): `internal/playground/simulate.go`

### Other components

- **Webhook provider**
- **Postgres**
- **Temporal**
- **Destination app**
- **Console operator**
- **SMTP service**
- **Slack**

## Connections

- Webhook provider → HTTP API: posts webhook
- HTTP API → Source adapters: verifies signature (evidence: `internal/api/server.go`)
- HTTP API → Event and connection store: persists event (evidence: `internal/api/server.go`)
- Event and connection store → Postgres: stores durably
- HTTP API → Temporal: starts workflow (evidence: `internal/api/server.go`)
- Temporal → Retry workflow: dispatches workflow
- Retry workflow → Destination app: delivers with retries
- Retry workflow → Event and connection store: records outcomes (evidence: `internal/workflow/delivery.go`)
- Console operator → Console routing: uses console (evidence: `web/src/App.tsx`)
- Console routing → Management pages: routes to (evidence: `web/src/App.tsx`)
- Management pages → Browser API client: requests data (evidence: `web/src/pages/ConnectionsPage.tsx`)
- Browser API client → HTTP API: calls endpoints (evidence: `web/src/lib/api.ts`)
- Management pages → Shared console UI: renders (evidence: `web/src/pages/ConnectionsPage.tsx`)
- Management pages → Issues and metrics: shows issues and metrics
- Alert evaluator → Event and connection store: reads delivery state (evidence: `internal/alerting/evaluator.go`)
- Alert evaluator → Email and Slack: sends alerts (evidence: `internal/alerting/evaluator.go`)
- Notification settings → Event and connection store: loads saved settings (evidence: `internal/notifysettings/settings.go`)
- Notification settings → Email and Slack: provides effective config (evidence: `internal/notifysettings/settings.go`)
- Email and Slack → SMTP service: sends email
- Email and Slack → Slack: sends direct messages
- Console operator → Playground UI: runs demo
- Playground UI → Browser API client: controls simulation (evidence: `web/src/lib/api.ts`)
- Browser API client → Playground API: calls demo endpoints (evidence: `web/src/lib/api.ts`)
- Playground API → Event simulation: simulates events (evidence: `internal/api/playground.go`)
