# sudodevstudio/dittoly architecture

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

- Interactive diagram: https://gitdiagram.com/sudodevstudio/dittoly
- Repository: https://github.com/sudodevstudio/dittoly
- Video tour (about a minute): https://gitdiagram.com/sudodevstudio/dittoly/video

## Overview

Dittoly is a self-hosted orchestration platform: Super-Modules connect apps, Flows define approved processes, and the engine executes runs using members’ own access or delegated teammate access. The graph follows that workflow and preserves major documented capabilities, including governance, integrations, and larger Super Flows. Some subsystem links are documented in the README; source-level evidence is limited to the supplied excerpts and SOURCE INDEX, so unsampled wiring is not inferred.

Main entry points: [`src/engine/engine.ts`](https://github.com/sudodevstudio/dittoly/blob/main/src/engine/engine.ts) (Run Engine), [`src/flows/service.ts`](https://github.com/sudodevstudio/dittoly/blob/main/src/flows/service.ts) (Flow Service), [`src/engine/jobs.ts`](https://github.com/sudodevstudio/dittoly/blob/main/src/engine/jobs.ts) (Durable Jobs), [`src/modules/registry.ts`](https://github.com/sudodevstudio/dittoly/blob/main/src/modules/registry.ts) (Super-Modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Flow Design"]
  node_ai_drafting["AI Drafting<br/>[generate-flow.ts]"]
  node_flow_service["Flow Service<br/>[service.ts]"]
  node_flow_definition["Flow Definitions<br/>[definition.ts]"]
  node_super_flows["Super Flows<br/>[service.ts]"]
end

subgraph group_execution["Run Execution"]
  node_engine["Run Engine<br/>[engine.ts]"]
  node_job_queue["Durable Jobs<br/>[jobs.ts]"]
  node_sandbox["Sandbox Runner<br/>[engine.ts]"]
  node_egress["Egress Policy<br/>[egress.ts]"]
end

subgraph group_governance["Access Governance"]
  node_approvals["Flow Approvals<br/>[approvals.ts]"]
  node_members["Member Identity<br/>[members.ts]"]
  node_teams["Teams<br/>[teams.ts]"]
  node_delegation["Delegated Access<br/>[engine.ts]"]
  node_audit["Audit Trail<br/>[audit.ts]"]
end

subgraph group_integrations["Integrations"]
  node_module_registry["Super-Modules<br/>[registry.ts]"]
  node_module_manifest["Module Manifests<br/>[manifest.ts]"]
  node_mcp["MCP Gateway<br/>[server.ts]"]
  node_webhooks["Webhooks<br/>[service.ts]"]
  node_watches["External Watches<br/>[service.ts]"]
end

subgraph group_platform["Platform Capabilities"]
  node_tables[("Data Tables<br/>[service.ts]")]
  node_marketplace["Marketplace<br/>[service.ts]"]
  node_git_sync["Git Sync<br/>[service.ts]"]
  node_insights["Insights<br/>[service.ts]"]
  node_export["App Export<br/>[service.ts]"]
  node_db[("PostgreSQL Store<br/>[db.ts]")]
end

node_member(("Member"))

node_member -->|"describes process"| node_ai_drafting
node_ai_drafting -->|"drafts Flow"| node_flow_service
node_member -->|"approves version"| node_approvals
node_flow_service -->|"requests approval"| node_approvals
node_flow_service -->|"resolves capabilities"| node_module_manifest
node_member -->|"starts approved run"| node_engine
node_engine -->|"enqueues advance"| node_job_queue
node_job_queue -.->|"dispatches run work"| node_engine
node_engine -->|"executes module actions"| node_module_registry
node_module_registry -->|"validates modules"| node_module_manifest
node_engine -->|"enforces egress"| node_egress
node_engine -->|"reads and writes rows"| node_tables
node_member -->|"signs in"| node_members
node_members -->|"participates in teams"| node_teams
node_engine -.->|"handles run access"| node_delegation
node_flow_service -->|"enqueues decisions"| node_job_queue
node_mcp -->|"starts runs"| node_engine
node_webhooks -->|"triggers runs"| node_engine
node_watches -->|"starts watched flows"| node_engine
node_marketplace -->|"uses module catalog"| node_module_registry
node_marketplace -->|"uses Flow catalog"| node_flow_service
node_git_sync -->|"syncs modules"| node_module_registry
node_git_sync -->|"queues work"| node_job_queue
node_export -.->|"exports Flow apps"| node_flow_definition
node_engine -->|"records run events"| node_audit
node_members -->|"stores identities"| node_db
node_flow_service -->|"stores Flows"| node_db
node_insights -->|"reads metrics"| node_db

click node_ai_drafting "https://github.com/sudodevstudio/dittoly/blob/main/src/ai/generate-flow.ts"
click node_flow_service "https://github.com/sudodevstudio/dittoly/blob/main/src/flows/service.ts"
click node_flow_definition "https://github.com/sudodevstudio/dittoly/blob/main/src/flows/definition.ts"
click node_super_flows "https://github.com/sudodevstudio/dittoly/blob/main/src/plans/service.ts"
click node_approvals "https://github.com/sudodevstudio/dittoly/blob/main/src/governance/approvals.ts"
click node_module_registry "https://github.com/sudodevstudio/dittoly/blob/main/src/modules/registry.ts"
click node_module_manifest "https://github.com/sudodevstudio/dittoly/blob/main/src/modules/manifest.ts"
click node_engine "https://github.com/sudodevstudio/dittoly/blob/main/src/engine/engine.ts"
click node_job_queue "https://github.com/sudodevstudio/dittoly/blob/main/src/engine/jobs.ts"
click node_sandbox "https://github.com/sudodevstudio/dittoly/blob/main/src/sandbox/engine.ts"
click node_egress "https://github.com/sudodevstudio/dittoly/blob/main/src/runtime/egress.ts"
click node_members "https://github.com/sudodevstudio/dittoly/blob/main/src/core/members.ts"
click node_teams "https://github.com/sudodevstudio/dittoly/blob/main/src/core/teams.ts"
click node_delegation "https://github.com/sudodevstudio/dittoly/blob/main/src/engine/engine.ts"
click node_audit "https://github.com/sudodevstudio/dittoly/blob/main/src/core/audit.ts"
click node_mcp "https://github.com/sudodevstudio/dittoly/blob/main/src/mcp/server.ts"
click node_webhooks "https://github.com/sudodevstudio/dittoly/blob/main/src/webhooks/service.ts"
click node_watches "https://github.com/sudodevstudio/dittoly/blob/main/src/watches/service.ts"
click node_tables "https://github.com/sudodevstudio/dittoly/blob/main/src/tables/service.ts"
click node_marketplace "https://github.com/sudodevstudio/dittoly/blob/main/src/marketplace/service.ts"
click node_git_sync "https://github.com/sudodevstudio/dittoly/blob/main/src/git-sync/service.ts"
click node_insights "https://github.com/sudodevstudio/dittoly/blob/main/src/insights/service.ts"
click node_export "https://github.com/sudodevstudio/dittoly/blob/main/src/export/service.ts"
click node_db "https://github.com/sudodevstudio/dittoly/blob/main/src/db/db.ts"

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_ai_drafting,node_flow_service,node_flow_definition,node_super_flows toneBlue
class node_engine,node_job_queue,node_sandbox,node_egress toneAmber
class node_approvals,node_members,node_teams,node_delegation,node_audit toneMint
class node_module_registry,node_module_manifest,node_mcp,node_webhooks,node_watches toneRose
class node_tables,node_marketplace,node_git_sync,node_insights,node_export,node_db,node_member toneIndigo
```

## Components

### Flow Design

- [AI Drafting](https://github.com/sudodevstudio/dittoly/blob/main/src/ai/generate-flow.ts): `src/ai/generate-flow.ts`
- [Flow Service](https://github.com/sudodevstudio/dittoly/blob/main/src/flows/service.ts): `src/flows/service.ts`
- [Flow Definitions](https://github.com/sudodevstudio/dittoly/blob/main/src/flows/definition.ts): `src/flows/definition.ts`
- [Super Flows](https://github.com/sudodevstudio/dittoly/blob/main/src/plans/service.ts): `src/plans/service.ts`

### Run Execution

- [Run Engine](https://github.com/sudodevstudio/dittoly/blob/main/src/engine/engine.ts): `src/engine/engine.ts`
- [Durable Jobs](https://github.com/sudodevstudio/dittoly/blob/main/src/engine/jobs.ts): `src/engine/jobs.ts`
- [Sandbox Runner](https://github.com/sudodevstudio/dittoly/blob/main/src/sandbox/engine.ts): `src/sandbox/engine.ts`
- [Egress Policy](https://github.com/sudodevstudio/dittoly/blob/main/src/runtime/egress.ts): `src/runtime/egress.ts`

### Access Governance

- [Flow Approvals](https://github.com/sudodevstudio/dittoly/blob/main/src/governance/approvals.ts): `src/governance/approvals.ts`
- [Member Identity](https://github.com/sudodevstudio/dittoly/blob/main/src/core/members.ts): `src/core/members.ts`
- [Teams](https://github.com/sudodevstudio/dittoly/blob/main/src/core/teams.ts): `src/core/teams.ts`
- [Delegated Access](https://github.com/sudodevstudio/dittoly/blob/main/src/engine/engine.ts): `src/engine/engine.ts`
- [Audit Trail](https://github.com/sudodevstudio/dittoly/blob/main/src/core/audit.ts): `src/core/audit.ts`

### Integrations

- [Super-Modules](https://github.com/sudodevstudio/dittoly/blob/main/src/modules/registry.ts): `src/modules/registry.ts`
- [Module Manifests](https://github.com/sudodevstudio/dittoly/blob/main/src/modules/manifest.ts): `src/modules/manifest.ts`
- [MCP Gateway](https://github.com/sudodevstudio/dittoly/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Webhooks](https://github.com/sudodevstudio/dittoly/blob/main/src/webhooks/service.ts): `src/webhooks/service.ts`
- [External Watches](https://github.com/sudodevstudio/dittoly/blob/main/src/watches/service.ts): `src/watches/service.ts`

### Platform Capabilities

- [Data Tables](https://github.com/sudodevstudio/dittoly/blob/main/src/tables/service.ts): `src/tables/service.ts`
- [Marketplace](https://github.com/sudodevstudio/dittoly/blob/main/src/marketplace/service.ts): `src/marketplace/service.ts`
- [Git Sync](https://github.com/sudodevstudio/dittoly/blob/main/src/git-sync/service.ts): `src/git-sync/service.ts`
- [Insights](https://github.com/sudodevstudio/dittoly/blob/main/src/insights/service.ts): `src/insights/service.ts`
- [App Export](https://github.com/sudodevstudio/dittoly/blob/main/src/export/service.ts): `src/export/service.ts`
- [PostgreSQL Store](https://github.com/sudodevstudio/dittoly/blob/main/src/db/db.ts): `src/db/db.ts`

### Other components

- **Member**

## Connections

- Member → AI Drafting: describes process (evidence: `README.md`)
- AI Drafting → Flow Service: drafts Flow (evidence: `README.md`)
- Member → Flow Approvals: approves version (evidence: `README.md`)
- Flow Service → Flow Approvals: requests approval (evidence: `src/flows/service.ts`)
- Flow Service → Module Manifests: resolves capabilities (evidence: `src/flows/service.ts`)
- Member → Run Engine: starts approved run (evidence: `README.md`)
- Run Engine → Durable Jobs: enqueues advance (evidence: `src/engine/engine.ts`)
- Durable Jobs → Run Engine: dispatches run work (evidence: `src/engine/engine.ts`)
- Run Engine → Super-Modules: executes module actions (evidence: `src/engine/engine.ts`)
- Super-Modules → Module Manifests: validates modules (evidence: `src/modules/registry.ts`)
- Run Engine → Egress Policy: enforces egress (evidence: `src/engine/engine.ts`)
- Run Engine → Data Tables: reads and writes rows (evidence: `src/engine/engine.ts`)
- Member → Member Identity: signs in (evidence: `README.md`)
- Member Identity → Teams: participates in teams (evidence: `src/core/teams.ts`)
- Run Engine → Delegated Access: handles run access (evidence: `src/engine/engine.ts`)
- Flow Service → Durable Jobs: enqueues decisions (evidence: `src/flows/service.ts`)
- MCP Gateway → Run Engine: starts runs (evidence: `src/mcp/server.ts`)
- Webhooks → Run Engine: triggers runs (evidence: `src/webhooks/service.ts`)
- External Watches → Run Engine: starts watched flows (evidence: `src/watches/service.ts`)
- Marketplace → Super-Modules: uses module catalog (evidence: `src/marketplace/service.ts`)
- Marketplace → Flow Service: uses Flow catalog (evidence: `src/marketplace/service.ts`)
- Git Sync → Super-Modules: syncs modules (evidence: `src/git-sync/service.ts`)
- Git Sync → Durable Jobs: queues work (evidence: `src/git-sync/service.ts`)
- App Export → Flow Definitions: exports Flow apps
- Run Engine → Audit Trail: records run events (evidence: `src/engine/engine.ts`)
- Member Identity → PostgreSQL Store: stores identities (evidence: `src/core/members.ts`)
- Flow Service → PostgreSQL Store: stores Flows (evidence: `src/flows/service.ts`)
- Insights → PostgreSQL Store: reads metrics (evidence: `src/insights/service.ts`)
