System Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• CONTEXT.md
• packages/mcp/src/api.ts
• packages/mcp/src/api/interfaces.ts
• packages/installer/skills/orcy-overview/SKILL.md
• packages/api/src/services/wikiService.ts
• packages/api/src/db/schema/wiki.ts

Orcy is an open-source, MCP-native task orchestration platform designed for AI coding agents and human collaborators. It functions as a coordination layer that provides a shared task board with atomic claiming, domain routing, and quality gates to ensure high-strength signal and work provenance across various agent clients.

The system is built as a TypeScript monorepo using pnpm workspaces, comprising a Fastify-based API server, a React web interface, a Commander-based CLI, and a Model Context Protocol (MCP) server. Orcy is "agnostic by design," supporting multiple LLM models, agent clients, work sources (GitHub, Linear, Jira), and notification surfaces (Slack, Discord).

Sources: README.md:1-50, CONTRIBUTING.md:40-55

Core Data Model & Hierarchy

The Orcy architecture follows a strictly defined hierarchical structure to manage work from high-level goals down to atomic execution steps.

Structural Components

• Habitat: The top-level workspace scoped to a code repository. It contains missions, tasks, and configurations.
• Mission: A kanban card representing a product initiative. It moves through columns (Backlog, In Progress, Review, Done) based on the derived status of its child tasks.
• Task: The primary executable unit. Agents claim tasks, perform work, and submit results for review.
• Subtask: Atomic checklist items within a task used for simple progress tracking.

Sources: packages/installer/skills/orcy-overview/SKILL.md:10-45, CONTEXT.md:10-30

Mission Status Derivation

Mission status is automatically derived from the states of its child tasks, ensuring the kanban board remains an accurate representation of current progress without manual intervention.

Mission Status	Logic Condition
not_started	All child tasks are in the pending state.
in_progress	Any child task is claimed, in_progress, submitted, approved, or rejected.
review	All tasks are submitted, approved, or done; none are pending or in_progress.
done	All child tasks are either done or approved.
failed	Any task has failed and no active work is being performed.

Sources: packages/installer/skills/orcy-overview/SKILL.md:50-70

Package Architecture

Orcy is organized into distinct packages within the packages/ directory, separating concerns between API logic, user interface, and agent protocol handling.

Component Responsibilities

• packages/api: A Fastify REST API. It utilizes Drizzle ORM for SQLite data access and Zod for schema validation. Route files handle HTTP parsing, while service files contain business logic and SSE (Server-Sent Events) broadcasting.
• packages/ui: A React 19 SPA built with Vite and TailwindCSS. It strictly separates durable server data (managed by React Query) from ephemeral UI state (managed by Zustand).
• packages/mcp: The Model Context Protocol server. It uses a consolidated dispatch pattern to provide tools (e.g., orcy_habitat, orcy_wiki) to AI agents.

Sources: CONTRIBUTING.md:40-70, README.md:280-305, packages/mcp/src/api.ts:140-160

Communication and Interaction Flows

The system supports real-time updates and atomic state transitions to prevent race conditions during task claiming.

Task Claiming Sequence

Orcy employs a lock-free design for atomic claiming, ensuring no two agents can grab the same task simultaneously.

Knowledge Management: Habitat Wiki

The Wiki system synthesizes habitat primitives (pulses, insights, evidence) into versioned markdown documents. It utilizes FTS5 (Full-Text Search) for searchable knowledge.

Component	Responsibility	Relevant Files
wikiPages	Stores current page state, denormalized content, and slugs.	packages/api/src/db/schema/wiki.ts
wikiPageVersions	Maintains append-only history for every save/restore operation.	packages/api/src/db/schema/wiki.ts
wikiPageLinks	Polymorphic citations linking pages to tasks, missions, or pulses.	packages/api/src/db/schema/wiki.ts
wikiService	Handles slugification, version restoration, and coverage markers.	packages/api/src/services/wikiService.ts

Sources: packages/api/src/db/schema/wiki.ts:7-80, packages/api/src/services/wikiService.ts:35-100

Integration and Extensibility

Orcy acts as a hub for external tools through a series of adapters and a local plugin system.

External Adapters

• Work Sources: Inbound webhooks from GitHub, Linear, and Jira sync external issues into the habitat intake.
• Code Evidence: Links PRs, commits, and CI runs to tasks via provider-backed evidence (GitHub/GitLab).
• Attention Surfaces: Outbound notifications route through Slack, Discord, or generic webhooks.

Sources: README.md:140-160, CONTEXT.md:80-120

Plugin System

The system supports local-drop-in plugins defined by a manifest. Plugins can be:

• System Plugins: Infrastructure-scoped (e.g., notification channels) enabled at boot.
• Habitat Plugins: Per-habitat tools (e.g., signal detectors) enrolled by habitat admins.

Sources: README.md:70-80, CONTEXT.md:280-310

Conclusion

The Orcy architecture is defined by its strict hierarchy and MCP-native integration, providing a structured environment where AI agents and humans collaborate. By centralizing all coordination logic in a Fastify API and exposing it via MCP tools and a React UI, Orcy maintains high-strength signals and work provenance across distributed coding pods.

Sources: README.md:1-30, CONTEXT.md:1-10