System Architecture

OpenCodeHub is a modular monolith built for performance and self-hosting simplicity.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                        CLIENTS                               │
│  Browser  │  Git CLI (HTTP/SSH)  │  OpenCodeHub CLI (och)   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    OPENCODEHUB PLATFORM                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Web UI     │  │  REST API   │  │  GraphQL Endpoint   │  │
│  │  (Astro+React)│  │  (175+ routes)│  │  (src/pages/api/)   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Git Server │  │  SSH Server │  │  Pipeline Runner    │  │
│  │  (HTTP RPC) │  │  (ssh2)     │  │  (Docker executor)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│              PERSISTENCE & INFRASTRUCTURE                    │
│  PostgreSQL/SQLite/Turso  │  Redis  │  Pluggable Storage    │
└─────────────────────────────────────────────────────────────┘

Runtime Processes

Process	Command	Purpose
Main App	`npm run dev`	Web UI + API + Git HTTP
SSH Git	`npm run git:start`	SSH git push/pull server
Worker	`npm run worker:start`	Background jobs (BullMQ queues)
Runner	`npm run runner:start`	CI/CD pipeline execution (Docker)

Tech Stack

Layer	Technology
Framework	Astro 4.x (SSR mode, `@astrojs/node` standalone adapter)
UI	React 18 + Tailwind CSS + Radix UI primitives
Database ORM	Drizzle ORM
DB Drivers	PostgreSQL (pg), SQLite (better-sqlite3), LibSQL/Turso
Auth	JWT (jose) + bcryptjs + TOTP (otplib) + OAuth (arctic) + SSO/SAML/OIDC
Git	Native `git` CLI + `simple-git` + `isomorphic-git` + `nodegit`
SSH	`ssh2` library
CI/CD	Dockerode (Docker API)
Storage	Abstract adapter: `local` filesystem or `s3`-compatible
AI	OpenAI, Anthropic, Google, Groq, Ollama, OpenRouter, Together, Bytez
Queue	BullMQ + Redis
Observability	OpenTelemetry + Prometheus + Pino

Request Flow

Browser/Git CLI → Astro middleware (auth, rate limit, CSRF)
                        ↓
              Route handler (src/pages/api/*.ts)
                        ↓
              Business logic (src/lib/*.ts)
                        ↓
              Database (src/db/index.ts → Drizzle)

Authentication

Web: Cookie-based JWT (och_session)
API: Bearer token (JWT or Personal Access Token och_...)
Git HTTP: Basic auth with PAT as password
Git SSH: Public key auth against deployKeys table
SSO: SAML and OIDC via admin-configured providers

Git Protocol Handling

HTTP: src/pages/git/ routes → src/lib/git-server.ts → spawns git upload-pack/receive-pack
SSH: src/lib/ssh.ts using ssh2 library → spawns git processes
Smart HTTP: Full pkt-line protocol implementation with sideband

Storage Abstraction

All blob storage goes through StorageAdapter:

LocalStorageAdapter — filesystem at STORAGE_PATH
S3StorageAdapter — any S3-compatible store (AWS, MinIO, R2, Garage, Wasabi, etc.)

Path-style addressing is enabled automatically when STORAGE_ENDPOINT is set.

Database

src/db/index.ts provides a factory pattern:

Reads DATABASE_DRIVER and DATABASE_URL
Returns appropriate Drizzle instance
Production: PostgreSQL required (schemas use pgTable)
Dev: SQLite or Turso for simplicity

38 schema tables cover users, repos, PRs, issues, projects, workflows, merge queue, stacked PRs, AI reviews, security policies, and more.

Background Workers

The worker process (npm run worker:start) handles:

BullMQ job queues for webhooks, notifications, CI triggers
Cron jobs (garbage collection, mirror sync, notification digests)
Email delivery via SMTP
Real-time SSE event broadcasting