# alan-youngzhe/ordine-fork architecture

> Architecture diagram of the GitHub repository alan-youngzhe/ordine-fork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alan-youngzhe/ordine-fork
- Repository: https://github.com/alan-youngzhe/ordine-fork

## Overview

1. **What this repo is**
   Ordine is a monorepo for an AI-agent orchestration platform. The core idea is: users define typed objects, operations, and DAG pipelines; the system executes them with configurable AI agents or scripts and records jobs, traces, and results.

2. **Primary runtime surfaces**
   There are four real entry points: the main browser app in `apps/app`, the API server in `apps/server`, the local bootstrap/installer flow in `apps/create`, and the desktop shell in `apps/desktop-app` (Tauri + bundled server). `apps/cli` is a small command-line control surface, mostly for daemon/API interactions and local workflows.

3. **User-facing product boundary**
   The main UI is a React/Vite app using TanStack Router, tRPC client calls, and a large set of page modules under `apps/app/src/pages`. The key interactive areas are pipelines, operations, jobs, skills, agents, connectors, settings, and the workspace canvas. The workspace page is the most orchestration-heavy UI: it edits pipeline graphs, manages agent conversations, and polls run state.

4. **API boundary**
   The app exposes API routes under `apps/app/src/routes/api` for auth, local session, and tRPC. The server exposes the shared backend routes under `apps/server/src/routes` and `apps/server/src/integrations/trpc`. In practice, the browser UI talks to backend data and actions through tRPC, while some server-side agent endpoints are also available for non-browser consumers.

5. **Core domain logic lives in `packages/services`**
   This package is the main business-logic layer. It contains services for pipelines, operations, jobs, projects, skills, settings, usage, connectors, distillations, refinements, routine scheduling, filesystem access, GitHub projects, and agent runtimes. Most app/server route handlers should be thin adapters over these services.

6. **Execution engines**
   Two packages do the heavy runtime work:
   - `packages/pipeline-engine` executes DAG pipelines, resolves node/edge semantics, applies actions, and validates connection rules.
   - `packages/agent-engine` and `packages/agent` wrap external AI runtimes and tool protocols such as Claude, Codex, Hermes, OpenClaw, and MCP-style integrations.
   The pipeline runner service in `packages/services/src/pipelineRunnerService` bridges these engines to the product domain: it converts pipeline definitions into executions, controls run phases, and persists run progress.

7. **Persistence and data model**
   Database structure is defined in `packages/db-schema`, with DAOs in `packages/models`, a DB wrapper in `packages/db`, and generated migrations in `apps/app/drizzle`. The schema covers pipelines, jobs, operations, skills, agents, connectors, projects, runtime configs, conversations, annotations, traces, distillations, refinements, and usage. This is the primary source of truth for the application state.

8. **Local vs hosted database topology**
   The system can run against either embedded PGLite or a PostgreSQL instance. The `apps/create` package exists to provision a local single-user installation with embedded PostgreSQL, run migrations, and start the app without external setup. The README’s “local mode” is effectively a self-hosted topology where auth is skipped and a default user is created.

9. **Desktop distribution**
   `apps/desktop-app` wraps the web UI in a Tauri shell and bundles a server process via a custom sidecar/server integration. This makes the product runnable as a local desktop application while still reusing the same app and backend concepts.

10. **Extensibility model**
   Plugins are first-class. `packages/plugin` defines the plugin contract, `packages/plugins` contains built-in plugins like the GitHub project plugin, and the app’s plugin pages manage installed/available plugin features. Plugins extend object types, operations, and workflow capabilities rather than acting as isolated extensions.

11. **Content and prompt assets**
   `apps/docs` and `skills/` are not runtime code paths, but they matter architecturally because they define the product’s operational knowledge: how to create pipelines, run operations, manage jobs, and use the agent system. `apps/scripts` seeds and migrates content like best practices, operations, rules, and skill pipelines into the database.

12. **Shared infrastructure packages**
   Several packages provide cross-cutting infrastructure: `packages/schemas` for Zod schemas and contract types, `packages/ui` for shared components, `packages/views` for reusable page views, `packages/shared` for generic helpers and environment handling, `packages/logger` for logging, and `packages/obs` for tracing/observability. These packages keep the app/server/domain layers aligned on types and runtime behavior.

13. **Important architectural boundary**
   The active system is split cleanly into: presentation (`apps/app`, `apps/desktop-app`), application/API (`apps/server`, app API routes), domain services (`packages/services`), execution engines (`packages/pipeline-engine`, `packages/agent*`), and persistence (`packages/db*`, `apps/app/drizzle`). Legacy implementations live under `archive/` and are not part of the current mainline architecture.

Main entry points: [`packages/services`](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services) (Domain services), [`apps/app`](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app) (Web app), [`apps/server`](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server) (API server), [`packages/services/src/pipelineRunnerService`](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services/src/pipelineRunnerService) (Pipeline runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_apps_app["Web app<br/>React/Vite UI"]
  node_apps_server["API server<br/>HTTP/TRPC backend"]
  node_apps_create["Installer<br/>Local bootstrap"]
  node_apps_desktop["Desktop shell<br/>Tauri wrapper"]
  node_apps_cli["CLI<br/>Control surface"]
  node_app_routes["App API<br/>Auth/local/tRPC routes"]
  node_app_pages["Product pages<br/>UI modules"]
  node_workspace_page["Workspace<br/>Orchestration UI"]
  node_server_routes["Server routes<br/>Domain adapters"]
  node_server_trpc["Server tRPC<br/>RPC router"]
end

subgraph group_packages["Packages"]
  node_services["Domain services<br/>Business logic"]
  node_pipeline_runner["Pipeline runner<br/>Execution bridge"]
  node_pipeline_engine["Pipeline engine<br/>DAG executor"]
  node_agent_engines["Agent runtimes<br/>AI/tool wrappers"]
  node_db_schema[("DB schema<br/>Canonical data model")]
  node_models["DAOs<br/>Data access"]
  node_db[("DB wrapper<br/>Connection layer")]
  node_schemas["Contracts<br/>Zod schemas"]
  node_plugin_system["Plugins<br/>Extension API"]
  node_infra_pkgs["Infra packages<br/>Shared utilities"]
end

subgraph group_content["Content"]
  node_docs_skills["Docs & skills<br/>Knowledge assets"]
end

node_apps_app -->|"uses"| node_app_routes
node_apps_app -->|"renders"| node_app_pages
node_app_pages -->|"contains"| node_workspace_page
node_apps_desktop -->|"hosts"| node_apps_app
node_apps_desktop -->|"bundles"| node_apps_server
node_apps_create -->|"boots"| node_apps_app
node_apps_create -->|"initializes"| node_db
node_apps_cli -->|"drives"| node_apps_server
node_apps_server -->|"exposes"| node_server_routes
node_apps_server -->|"hosts"| node_server_trpc
node_server_routes -->|"adapts"| node_services
node_server_trpc -->|"calls"| node_services
node_app_routes -->|"calls"| node_services
node_services -->|"orchestrates"| node_pipeline_runner
node_pipeline_runner -->|"executes"| node_pipeline_engine
node_pipeline_runner -->|"invokes"| node_agent_engines
node_services -->|"persists via"| node_models
node_models -->|"uses"| node_db
node_db -->|"maps to"| node_db_schema
node_services -->|"shares contracts"| node_schemas
node_app_pages -->|"extends via"| node_plugin_system
node_services -->|"loads plugins"| node_plugin_system
node_docs_skills -.->|"guides"| node_services
node_docs_skills -.->|"teaches"| node_pipeline_runner
node_infra_pkgs -->|"supports"| node_apps_app
node_infra_pkgs -->|"supports"| node_apps_server
node_infra_pkgs -->|"supports"| node_services

click node_apps_app "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app"
click node_apps_server "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server"
click node_apps_create "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/create"
click node_apps_desktop "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/desktop-app"
click node_apps_cli "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/cli"
click node_app_routes "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/routes/api"
click node_app_pages "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/pages"
click node_workspace_page "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/pages/WorkspacePage"
click node_server_routes "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server/src/routes"
click node_server_trpc "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server/src/integrations/trpc"
click node_services "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services"
click node_pipeline_runner "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services/src/pipelineRunnerService"
click node_pipeline_engine "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/pipeline-engine"
click node_agent_engines "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/agent/src"
click node_db_schema "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/db-schema"
click node_models "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/models"
click node_db "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/db"
click node_schemas "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/schemas"
click node_plugin_system "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/plugin"
click node_infra_pkgs "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/shared"
click node_docs_skills "https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/docs"

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_apps_app,node_apps_server,node_apps_create,node_apps_desktop,node_apps_cli,node_app_routes,node_app_pages,node_workspace_page,node_server_routes,node_server_trpc toneBlue
class node_services,node_pipeline_runner,node_pipeline_engine,node_agent_engines,node_db_schema,node_models,node_db,node_schemas,node_plugin_system,node_infra_pkgs toneAmber
class node_docs_skills toneMint
```

## Components

### Apps

Runtime entry points and user-facing surfaces

- [Web app](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app): React/Vite UI · Primary browser application with routes, pages, and client-side API calls · `apps/app`
- [API server](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server): HTTP/TRPC backend · Shared backend server exposing route handlers and tRPC endpoints · `apps/server`
- [Installer](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/create): Local bootstrap · Provisioning flow for embedded PostgreSQL, migrations, and first launch · `apps/create`
- [Desktop shell](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/desktop-app): Tauri wrapper · Desktop distribution that embeds the web app and bundles a server sidecar · `apps/desktop-app`
- [CLI](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/cli): Control surface · Command-line interface for daemon and API workflows · `apps/cli`
- [App API](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/routes/api): Auth/local/tRPC routes · Browser-app API routes for auth, local session, and tRPC · `apps/app/src/routes/api`
- [Product pages](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/pages): UI modules · Primary product pages for pipelines, operations, jobs, skills, agents, connectors, settings, plugins, and workspace · `apps/app/src/pages`
- [Workspace](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/app/src/pages/WorkspacePage): Orchestration UI · Canvas-centric editor for pipeline graphs, agent conversations, and run polling · `apps/app/src/pages/WorkspacePage`
- [Server routes](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server/src/routes): Domain adapters · Backend route handlers for core resources and product actions · `apps/server/src/routes`
- [Server tRPC](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/server/src/integrations/trpc): RPC router · Server-side tRPC composition and router integration · `apps/server/src/integrations/trpc`

### Packages

Shared domain, execution, persistence, and infrastructure

- [Domain services](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services): Business logic · Main service layer for pipelines, operations, jobs, projects, skills, connectors, routines, settings, usage, and agent runtimes · `packages/services`
- [Pipeline runner](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/services/src/pipelineRunnerService): Execution bridge · Bridges product pipelines to execution phases, run progress, and persistence · `packages/services/src/pipelineRunnerService`
- [Pipeline engine](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/pipeline-engine): DAG executor · Executes DAG pipelines, resolves node and edge semantics, and applies actions · `packages/pipeline-engine`
- [Agent runtimes](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/agent/src): AI/tool wrappers · Claude, Codex, Hermes, OpenClaw, MCP, scan, and structured-agent integrations · `packages/agent/src`
- [DB schema](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/db-schema): Canonical data model · Database schema for pipelines, jobs, operations, skills, agents, connectors, projects, traces, distillations, refinements, settings, and usage · `packages/db-schema`
- [DAOs](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/models): Data access · Entity-level persistence objects used by services · `packages/models`
- [DB wrapper](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/db): Connection layer · Database wrapper used by DAOs and application code · `packages/db`
- [Contracts](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/schemas): Zod schemas · Shared runtime schemas and contract types across domain layers · `packages/schemas`
- [Plugins](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/plugin): Extension API · Plugin contract, registry, and built-in extensions such as GitHub project support · `packages/plugin`
- [Infra packages](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/packages/shared): Shared utilities · Shared UI, views, helpers, logging, observability, and filesystem utilities · `packages/shared`

### Content

Docs, skills, and seeded operational knowledge

- [Docs & skills](https://github.com/alan-youngzhe/ordine-fork/tree/develop-fork/apps/docs): Knowledge assets · Documentation, skill guides, and seeded operational content · `apps/docs`

## Connections

- Web app → App API: uses · Browser UI reaches auth, local session, and tRPC entrypoints
- Web app → Product pages: renders · Top-level browser app is composed from product pages
- Product pages → Workspace: contains · Workspace is the orchestration-heavy product surface
- Desktop shell → Web app: hosts · Desktop shell embeds the browser app
- Desktop shell → API server: bundles · Desktop distribution includes a server sidecar
- Installer → Web app: boots · Installer provisions and launches the local app
- Installer → DB wrapper: initializes · Local setup prepares embedded PostgreSQL and migrations
- CLI → API server: drives · CLI interacts with daemon and API workflows
- API server → Server routes: exposes · Server HTTP surface is composed from route handlers
- API server → Server tRPC: hosts · Server tRPC integration powers remote calls
- Server routes → Domain services: adapts · Route handlers are thin adapters over services
- Server tRPC → Domain services: calls · RPC layer delegates business actions to services
- App API → Domain services: calls · Browser-side API routes delegate to backend services
- Domain services → Pipeline runner: orchestrates · Pipeline service coordinates execution and persistence
- Pipeline runner → Pipeline engine: executes · Runner bridges product pipelines into DAG execution
- Pipeline runner → Agent runtimes: invokes · Runner uses agent runtimes and tool protocols for AI steps
- Domain services → DAOs: persists via · Services read and write entities through DAOs
- DAOs → DB wrapper: uses · DAOs use the DB wrapper for storage access
- DB wrapper → DB schema: maps to · Database wrapper operates over the canonical schema
- Domain services → Contracts: shares contracts · Services rely on shared schemas and domain types
- Product pages → Plugins: extends via · Plugin pages manage installed and available extensions
- Domain services → Plugins: loads plugins · Plugin contract influences object, operation, and workflow capabilities
- Docs & skills → Domain services: guides · Docs and skills encode intended operational workflows
- Docs & skills → Pipeline runner: teaches · Skill assets describe how to run and compose pipelines and operations
- Infra packages → Web app: supports · Shared UI and helper packages underpin the browser app
- Infra packages → API server: supports · Shared logging, env, and utility packages support backend runtime
- Infra packages → Domain services: supports · Cross-cutting helpers and schemas keep domain layers aligned