project-architecture

Orient Architecture

System Overview

Orient is a pnpm monorepo implementing an AI-powered project management system. The architecture features a multi-MCP-server pattern with pluggable bot frontends (Slack, WhatsApp) connected to a shared AI/Agent infrastructure.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Messaging Frontends                             │
│   ┌─────────────────┐                         ┌─────────────────┐           │
│   │  WhatsApp Bot   │                         │   Slack Bot     │           │
│   │ (@orient/bot-wp)│                         │ (@orient/bot-sl)│           │
│   └────────┬────────┘                         └────────┬────────┘           │
│            └──────────────────┬────────────────────────┘                     │
│                               ▼                                              │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                      Agent Registry                                  │   │
│   │   (@orient/agents) - Context resolution, tool permissions, skills   │   │
│   └──────────────────────────────┬──────────────────────────────────────┘   │
│                                  ▼                                           │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                   OpenCode Server (AI Processing)                    │   │
│   │    ├── coding-server  (MCP for dev tasks)                           │   │
│   │    ├── assistant-server (MCP for JIRA, Slack, Messaging, Calendar)  │   │
│   │    └── core-server (MCP for skills, system, agents)                 │   │
│   └──────────────────────────────┬──────────────────────────────────────┘   │
│                                  ▼                                           │
│   ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐               │
│   │   PostgreSQL    │ │ Object Storage  │ │ External APIs   │               │
│   │ (Drizzle ORM)   │ │ (MinIO / R2)    │ │ (JIRA, Google)  │               │
│   └─────────────────┘ └─────────────────┘ └─────────────────┘               │
└─────────────────────────────────────────────────────────────────────────────┘

Monorepo Structure

orient/
├── packages/
│   ├── agents/                # Agent registry, prompts, skills, permissions
│   ├── apps/                  # Mini-apps system (manifests, edit sessions)
│   ├── mcp-servers/           # MCP server types and configs
│   ├── mcp-tools/             # MCP tool definitions and registry
│   ├── core/                  # Shared utilities, config, logging, types
│   ├── database/              # Drizzle ORM schemas (PostgreSQL)
│   ├── database-services/     # DB service implementations
│   ├── integrations/          # External integrations (JIRA, GitHub, Google)
│   ├── bot-whatsapp/          # WhatsApp bot (Baileys)
│   ├── bot-slack/             # Slack bot (Bolt)
│   ├── api-gateway/           # REST API, webhooks, schedulers
│   ├── dashboard/             # React admin dashboard
│   └── test-utils/            # Test factories, mocks
├── src/                       # ⚠️ DEPRECATED - Do not write new code here
├── apps/                      # Standalone mini-apps (e.g., meeting-scheduler)
├── data/                      # Seeds, migrations
├── docker/                    # Docker configs and compose files
├── tests/                     # Cross-package tests (e2e, integration)
├── skills/                    # Global skill definitions
└── pnpm-workspace.yaml

Package Descriptions

Multi-MCP-Server Architecture

Orient implements three specialized MCP servers, replacing the legacy monolithic server:

All servers share the discover_tools tool for dynamic capability discovery.

CLI Usage:

# Start specific server
npm run start:mcp:coding
npm run start:mcp:assistant
npm run start:mcp:core

Agent Registry

Agents are managed via the Dashboard UI and stored in PostgreSQL. The @orient/agents package provides the runtime.

┌─────────────────────────────────────────┐
│           Dashboard UI                  │
│   (Agents Tab - CRUD operations)        │
└────────────────────┬────────────────────┘
                     ▼
┌─────────────────────────────────────────┐
│         Agent Registry                  │
│  - Context resolution (platform, chat)  │
│  - Skills assignment                    │
│  - Tool allow/ask/deny patterns         │
└────────────────────┬────────────────────┘
                     ▼
┌─────────────────────────────────────────┐
│        PostgreSQL Tables                │
│   agents | agent_skills | agent_tools   │
│   context_rules                         │
└─────────────────────────────────────────┘

Default Agents

Agent Mentions

In Slack or WhatsApp, prefix message with @agent-id to override default agent:

@explorer find the auth config

Mini-Apps System (@orient/apps)

Allows generating small React apps via AI prompts, managed through Git worktrees.

Key Tools:

• ai_first_create_app - Generate a new app from a prompt
• ai_first_list_apps - List existing apps
• ai_first_get_app - Get app details
• ai_first_update_app - Update an existing app
• ai_first_share_app - Generate a shareable link

Edit Session Flow:

1. Create Git worktree for isolated development
2. Scaffold app or load existing
3. Create OpenCode session
4. Send prompt to AI for code generation
5. Auto-commit changes
6. Build app (npm install && npm run build)
7. Track commit history for rollback

Note: This feature is under active development. See TODO.md.

Data Flow (Incoming Message)

1. Message received (WhatsApp/Slack)
        │
        ├── Check permission (read_only, read_write, ignored)
        │   └── ignored: Drop message
        │   └── read_only: Store message, don't respond
        │   └── read_write: Store message, process
        │
        ▼
2. Resolve Agent (AgentRegistry → context rules → default)
        │
        ▼
3. Send to OpenCode server (MCP) for AI processing
        │
        ▼
4. OpenCode uses MCP tools (JIRA, Slides, etc.)
        │
        ▼
5. Return response to user
        │
        ▼
6. Store outgoing message in PostgreSQL

Docker Deployment

Uses per-package Dockerfiles with multi-stage builds.

# Local Development (v2 compose)
docker compose -f docker/docker-compose.v2.yml -f docker/docker-compose.local.yml up -d

# Production
USE_V2_COMPOSE=1 ./deploy-server.sh deploy
# Or manually:
docker compose -f docker/docker-compose.v2.yml \
  -f docker/docker-compose.prod.yml \
  -f docker/docker-compose.r2.yml up -d

Key CLI Commands

# Development
npm run dev:slack           # Run Slack bot in dev mode
npm run dev:whatsapp        # Run WhatsApp bot in dev mode
npm run dev:mcp             # Run coding MCP server in dev mode
npm run dev:infra           # Start Docker infrastructure (Postgres, etc.)

# Database
npm run db:migrate          # Run migrations
npm run db:seed:all         # Seed all data
npm run agents:seed         # Seed default agents

# Testing
npm run test                # Run all tests
npm run test:e2e            # Run E2E tests
npm run test:unit           # Run unit tests only
npm run test:docker:build   # Test Docker builds

# Build
npm run build               # TypeScript compile
npm run build:all           # Build packages + root + dashboard

Architectural Decisions

When to Create a New Package

Create a new package when:

• Functionality is distinct and reusable across the system
• Has its own lifecycle (startup/shutdown)
• Could be published as a standalone npm package

Extend existing package when:

• Functionality is tightly coupled to existing code
• Only used in one context

Adding New Features

1. New Agent: Add via Dashboard UI, seed via data/seeds/agents.ts
2. New MCP Tool: Add to packages/mcp-tools/ or src/tools/
3. New Integration: Add to @orient/integrations
4. New Bot Platform: Follow bot-whatsapp / bot-slack pattern

Database Schema Patterns

• Use platform-specific tables: messages / slack_messages
• PostgreSQL for structured data, Object Storage for media
• Drizzle ORM for type-safe queries