alan-youngzhe/ordine-fork

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.