swadhin / opencodehub-docs public
/ opencodehub-docs / src / content / docs / development / architecture.md
swadhinbiswas fix: remove highlight.js CSS import causing Docker build failure · 7/21/2026
eeb5038
111 lines · 5.6 KB
Raw Download

title: "System Architecture"
description: "High-level overview of OpenCodeHub's components and data flow."

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