Skip to content

Architecture

Jump to bottom
Sia edited this page May 31, 2026 · 18 revisions

Architecture Overview

Process model

┌──────────────────────────────────────────────────────────────────┐
│  docker compose stack                                            │
│                                                                   │
│  ┌────────────────────────────────────┐   ┌──────────────────┐  │
│  │  vibe-coder-server                 │   │ vibe-coder-      │  │
│  │  (Ubuntu 24.04 LTS, port 17880)    │   │  postgres        │  │
│  │  • Ktor / Netty                     │◄─►│  (postgres:17-  │  │
│  │  • Routes (admin SSR + JSON API)   │   │   alpine)        │  │
│  │  • Exposed ORM → PostgreSQL         │   │  • Port 5432    │  │
│  │  • WebSocket log hub                │   │   (internal)    │  │
│  └─────────────┬──────────────────────┘   └──────────────────┘  │
│                │ spawns                                            │
│        ┌───────┼────────┬────────┐                                │
│        ▼       ▼        ▼        ▼                                │
│     claude  gradlew    git    vibe-doctor                         │
│     (per-   (per-     (read-  (Android SDK,                       │
│      project build)   only)   MCP install)                        │
│      persistent                                                    │
│      child)                                                        │
└──────────────────────────────────────────────────────────────────┘

All external commands are wrapped in a TaskQueue + LogHub so progress streams uniformly to WebSocket clients (browser / Android). The PostgreSQL sidecar holds admin / projects / builds / artifacts / uploaded_files. The server connects via JDBC over the internal docker network — no port is exposed to the host by default.

Module layout

vibe-coder-server/
├── shared/                          # JVM library (DTOs, ApiPath, WsFrame)
│   └── src/main/kotlin/.../shared/
│       ├── ApiPath.kt               # All REST/WS routes as constants
│       ├── ws/WsFrame.kt            # Sealed class hierarchy for WS frames
│       └── dto/Dtos.kt              # @Serializable request/response types
│
└── server/                          # Ktor app body
    └── src/main/kotlin/.../server/
        ├── ServerMain.kt            # Bootstrap, DI wiring
        ├── Module.kt                # Routing + plugin install
        ├── auth/                    # Bearer + session + setup + CSRF
        │   └── Totp                  # RFC 6238 self-impl + Base32 (no external deps)
        ├── audit/                   # AuditLogger + /audit page
        ├── claude/                  # ClaudeSessionManager (stream-json)
        │   ├── ConversationHistoryService — turn persistence
        │   ├── HistoryRoutes        # /projects/{id}/history + /chat/history
        │   ├── GlobalHistorySearchRoutes — /history cross-project grep
        │   ├── ConversationExportService — JSON envelope export/import
        │   ├── ConversationArchiver — 30-day inactive dump-and-prune
        │   ├── PromptSuggestionService — LIKE-prefix autocomplete
        │   └── ClaudeUsageMonitor — quota polling + threshold alert
        ├── env/                     # EnvSetupService, MCP, Claude auth
        │   ├── AgentRegistry — ~/.claude/agents/*.md CRUD
        │   └── AgentRoutes           # /agents + /api/agents JSON dispatch list
        ├── git/                     # GitReader, GitCloneService, GitWriter
        ├── projects/                # ProjectService, KeystoreGenerator, ProjectTemplates
        │   ├── ProjectArchiver — source zip
        │   ├── EnvFilesRoutes — /projects/{id}/env-files whitelist editor
        │   ├── CodeStatsService — LoC / 언어 분류
        │   ├── CodeSearchService — workspace grep
        │   └── CodeAnalysisRoutes    # /projects/{id}/wrapper + /stats + /code-search
        ├── build/                   # BuildService (Gradle assembleDebug)
        │   ├── BuildCacheService — Gradle/Android/npm cache size + cleanup
        │   ├── buildCacheRoutes      # /settings/cache
        │   ├── DependencyAudit — gradlew :{module}:dependencies parser
        │   ├── DependencyAuditRoutes # /projects/{id}/deps
        │   ├── BuildScheduler — HH:MM / *:MM cron tick (60s)
        │   ├── BuildAutomationRoutes # /projects/{id}/automation + /api/webhooks/build/{id}
        │   └── GradleWrapperService — distributionUrl atomic 교체
        ├── artifacts/               # APK storage
        │   └── ApkSignerInspector — apksigner verify wrapper
        ├── files/                   # Upload routes + ProjectFileBrowser
        ├── prompts/                 # Prompt template store + /prompts page
        ├── notify/                  # EmailNotifier + WebhookNotifier + Notifiers facade
        │   ├── EmailSettingsRoutes  # /settings/email
        │   └── WebhookSettingsRoutes # /settings/webhook
        ├── publish/                 # PlayPublishService + TestFlightPublishService
        │                            # MCP delegation, prompts to Claude session
        ├── device/                  # AdbService + /adb wireless ADB logcat
        ├── disk/                    # DiskMonitor + dashboard card
        ├── admin/                   # SSR routes + HTML templates
        │   ├── TwoFactorRoutes      # /2fa enable / disable
        │   ├── LogSearchRoutes — /logs grep across all build logs
        │   ├── BackupRoutes — /backup + tar.gz stream
        │   └── MultiConsoleRoutes — /multi-console iframe grid
        ├── tasks/                   # TaskQueue (background work)
        ├── ws/                      # LogHub (WebSocket broadcaster)
        ├── config/                  # ServerConfig + ConfigPersistence
        └── db/                      # VibeDb (PostgreSQL via Exposed)
                                     # schemas: build_schedules, build_webhook_secrets

Data flow — example: send a prompt

  1. Client sends POST /api/projects/{id}/claude/console/prompt with text.
  2. ConsoleRoutes finds or spawns the claude child for that project (ClaudeSessionManager.spawnSession). Stream-json mode (--output-format stream-json --input-format stream-json).
  3. The user prompt is written as a stream-json frame to the child's stdin.
  4. Claude responds line-by-line on stdout. ClaudeStreamParser decodes each line and turns it into a WsFrame subtype:
    • console_session_started
    • console_assistant (with isPartial)
    • console_tool_use / console_tool_result
    • console_done / console_error
  5. LogHub broadcasts the frame to all WS subscribers on /ws/projects/{id}/console/logs.
  6. Browser console UI renders incrementally. Android client does the same with the same JSON shape.

To cancel a turn: POST .../claude/console/cancel — server sends SIGTERM to the child but keeps the saved session-id, so the next prompt resumes the same conversation.

Persistence

All persistent state lives under one host directory, and the PostgreSQL data directory is part of that tree. See Data Volumes & Backup for the full mapping.

./vibe-coder-data/
├── workspace/         # project sources + APKs
├── postgres/          # PostgreSQL data dir
├── server/            # server logs + build metadata
├── dev-tools/         # Android SDK, Gradle, npm-global (MCP), npm cache, ...
└── claude/            # Claude OAuth credentials + MCP registrations

The image itself contains only the server body (~600 MB) and is replaced on upgrade. Every persistent path is a bind mount; no Docker named volumes are used by default. The PostgreSQL directory is owned by UID 70 inside the container (the postgres user in alpine images) — see Data-Volumes for backup procedures.

Database layer

  • Engine: PostgreSQL 17 (postgres:17-alpine sidecar container).
  • ORM: Exposed 0.55.0 + Hikari connection pool (default size 10).
  • Tables: admin_users, devices, projects, builds, artifacts, uploaded_files, conversation_turns. Schema is created/migrated on boot via SchemaUtils.createMissingTablesAndColumns.
  • Cascade: Foreign keys reference projects.id. PostgreSQL enforces these. ProjectService.delete does explicit cascade cleanup for uploaded_files, artifacts, builds before deleting the project row.
  • Connection retry: On boot, the server retries 30× / 2 s = 60 s total to give the postgres container time to become healthy.
  • conversation_turns: stores Claude console turns with a JSONB column for tool_use input/output and a GIN tsvector for full-text search.
  • Audit log: audit_log table records IAM-level actions (auth / project / build / MCP / settings / git / console / publish / 2FA / session timeout). See the Audit Log page for the schema and filter URL recipes.
  • admin_users.totp_secret + totp_enabled_at — 2FA TOTP secret + enablement timestamp. See Two-Factor Auth.
  • build_schedules — cron expression + variant + enabled flag + lastFiredAt. See Build Automation.
  • build_webhook_secrets — secret-id + SHA-256 hash + lastUsedAt for external trigger auth.

Auth boundary

  • First boot: empty DB → /setup form creates admin (or VIBECODER_ADMIN_USERNAME/PASSWORD env auto-bootstrap).
  • Login: /api/auth/login returns bearer token + vibe_session cookie.
  • Subsequent requests: either auth header (Authorization: Bearer ...) or the cookie. Both paths converge in the same installAuth plugin.
  • CSRF: All SSR POST forms carry an HMAC-SHA256-derived CSRF token in a hidden _csrf input. REST API (Bearer header) is exempt.
  • Passwords: BCrypt cost 12 hash. 10 failures → 15-min account lock, 30 failures from same IP / 24 h → 24-h IP block. Timing-safe dummy verify on missing users.
  • 2FA TOTP: when enabled, login requires a 6-digit code after password. Server returns 401 totp_required on first call, expects totpCode field on the retry.
  • Session idle timeout: security.sessionIdleTimeoutMinutes (default 30) auto-deletes device rows whose lastSeenAt exceeded the threshold. Enforced both in AuthPlugin (Bearer) and SSR requireSessionOrRedirect.
  • Single-admin: this is a single-operator tool. There is one admin, and every authenticated session has full access — authentication is the only access boundary. WebSession.isAdmin / canWrite and DevicePrincipal.isAdmin / canWrite are always true.

Wire stability

shared/ is the contract between server and Android client. All wire changes (ApiPath / DTO / WsFrame) must be reflected in the Android companion repo's shared/ copy. CHANGELOG marks them with Wire change: Yes/No.

Notable parts of the wire surface:

  • Project registration (RegisterProjectRequestDto) carries git-clone fields and a templateId; the env-setup APIs cover SDK / MCP / Claude auth.
  • Console turn control: ApiPath.claudeConsoleCancel(projectId).
  • Conversation history: GET /projects/{id}/history + GET /chat/history (backed by conversation_turns), plus GET /api/projects/{id}/claude/prompt-suggestions?prefix=... (server-only {"suggestions": [...]} map).
  • Git write: ApiPath.gitCommit(projectId).
  • Prompt templates: ApiPath.PROMPT_TEMPLATES + PromptTemplateDto / PromptTemplateListResponseDto.
  • Claude status: ClaudeStatusDto.usagePercent + resetAt.
  • Auth: LoginRequestDto.totpCode; 2FA-enabled accounts signal 401 totp_required until the field is supplied.
  • Build webhooks: POST /api/webhooks/build/{projectId} external trigger (no admin auth; multi-secret via X-Vibe-Secret-Id + X-Vibe-Secret + optional X-Vibe-Signature).
  • Sub-agents: GET /api/agents Bearer JSON (lists ~/.claude/agents/*.md). SubAgentSessionManager runs independent Claude child processes per (projectId, agentName), with per-agent SSR consoles + REST (POST /api/projects/{id}/agents/{agent}/console/prompt | cancel, GET /api/projects/{id}/agents/active) + WS (/ws/projects/{id}/agents/{agent}/console/logs). Turns persist alongside the main console via the conversation_turns.agent_name column (ConversationHistoryService takes an agentName: String?).
  • Web Push: WebPushNotifier (VAPID P-256 ECDSA + RFC 8292 JWT; Aes128GcmEncrypt pure-JDK RFC 8291 aes128gcm content-encoding) + PushSubscriptionRepository + /settings/push SSR + /api/push/{vapid-public-key, subscribe, subscriptions/{id}}. The Notifiers facade exposes a webPush channel; the service worker reads the decrypted event.data.json() payload (title / body / url) and routes click to the matching open tab.
  • WebAuthn: WebauthnService (wraps webauthn4j 0.29.1) + WebauthnCredentialRepository + WebauthnSection config + /webauthn SSR
    • 4 JSON endpoints (POST /api/webauthn/{register,assert}/{options,verify}). The admin_users.passwordless_only flag + /webauthn toggle enable a passkey-only login flow next to password / TOTP (AuthService.login(hasPasskey) callback).
  • Usage viewer: /usage shows the cached Claude /status raw output (ClaudeStatusService.rawSnapshots).
  • History filtering / search: ConversationTurnRepository.Filter.agentName (3-mode: null main only / "" all / "<name>" specific) + distinctAgents(projectId). Full-text search uses a content_tsv GENERATED ALWAYS AS STORED column + GIN index, with TsvectorMatchOp (private Op<Boolean>); non-ASCII queries auto-route through a pg_trgm GIN gin_trgm_ops index on content via TrigramIlikeOp.
  • Symbols: SymbolFinder (Kotlin/Java regex-based definition lookup) + symbolRoutes (GET /projects/{id}/symbols SSR + GET /api/projects/{id}/symbols?name=). The file viewer reads a ?line=N query and smooth-scrolls + outlines the target line.
  • Metrics + rate limit: MetricsRegistry + /metrics SSR (Prometheus text exposition; zero deps); RateLimiter + installRateLimit Ktor plugin (/api/, /ws/, /login; 429 + Retry-After; config security.rateLimit.*).
  • Build analysis: BuildService.compareWithPrevious(...) + comparison card on the build detail page; BuildService.statistics(...) + builds-list stats card (success rate / avg duration / inline SVG sparkline + APK size trend).
  • Backup: BackupService + BackupScheduler cron polling + SSR endpoints /backup/auto/{name}, /backup/auto/{name}/delete, /backup/auto/run-now.
  • Memo / star: conversation_turns.user_memo (text) + starred (bool); repository setMemo / setStarred / findById; filter starredOnly; SSR row gains ☆/★ + memo editor; JSON endpoints POST .../history/{turnId}/star|memo (CSRF via ?_csrf=).
  • Usage reporting: ClaudeEvent.UsageReport + ClaudeStreamParser reads message.usage (assistant frames) and top-level usage (result frames), persisted as role="usage" history rows; ConversationTurnRepository.usageSummary(projectId) aggregates. Console + sub-agent toWsFrame exposes the report as a small ConsoleSystem(code="usage") notice, and /usage shows a structured cache stats card.

General Chat

Multi-session General Chat (ChatGPT-style) lets each chat be a ghost project __chat_<id>__ (alongside the __scratch__ ghost), living under <root>/.vibecoder/<id> like scratch. It reuses ClaudeSessionManager (process / session-id / --resume), ConversationTurnRepository (per-projectId turn isolation) and the WS console topic verbatim — no DB schema change. SSR routes are POST /chat/new, POST /chat/{id}/rename, POST /chat/{id}/delete, and GET /chat?c=<id>; the prompt/cancel/new JSON APIs take the active chat's ghost projectId unchanged (no wire change). ProjectService.isGhost(id) (scratch + every __chat_*) governs project listing, dashboard projectCount, vibe_projects_total, and console redirects. The left sidebar (WebProjectTemplates.chatSidebar) lists chats, auto-titled from the first user prompt; consolePage takes chatSidebar / chatTitle params and wraps the console body in a flex shell.

Chat is conversation-only: when WorkspacePath.isGhostId(projectId) (scratch

  • every __chat_*), ClaudeSessionManager appends Bash Write Edit NotebookEdit Task to --disallowedTools, so a chat session can't create/modify files, run builds, or dispatch sub-agents — it only emits text. Read/Glob/Grep and WebSearch/WebFetch stay allowed so the model can still read context and search the web. Regular project consoles are unaffected. This applies from the next process (re)spawn; "New session" forces it.

Background services (started in ServerMain)

Service Polls Shutdown hook
ClaudeUsageMonitor claude /status every 5 min yes
DiskMonitor Files.getFileStore(root) every 10 min yes
BuildScheduler enabled build_schedules every 60 s yes
ConversationArchiver conversation_turns once every 24 h yes
Notifiers (email + webhook + webPush) n/a (event-driven) yes
ClaudeSessionManager per-project child processes yes
SubAgentSessionManager per (project, agent) child processes; persists turns yes
WebPushNotifier n/a (event-driven; lazy VAPID keypair; aes128gcm encrypted) n/a (JDK HttpClient close on JVM exit)
WebauthnService n/a (per-request; 5 min in-memory challenge TTL) n/a
MetricsRegistry n/a (sampled on each /metrics scrape) n/a
RateLimiter n/a (in-memory per-IP token buckets) n/a (state lost on restart by design)
BackupScheduler enabled backup.cron every 60 s yes

All are wired in ServerMain.kt and added to a single Runtime.getRuntime().addShutdownHook(...) so docker compose stop cleans up gracefully.

Clone this wiki locally