Architecture

Architecture Overview

Process model

┌─────────────────────────────────────────────────────────────┐
│  Docker container (Ubuntu 24.04 LTS noble)                  │
│                                                              │
│   ┌────────────────────────────────────┐                   │
│   │  Ktor server (vibe-coder-server)   │                   │
│   │  • Port 17880                       │                   │
│   │  • Netty engine                     │                   │
│   │  • Routes (admin SSR + JSON API)    │                   │
│   │  • SQLite via Exposed               │                   │
│   │  • WebSocket log hub                │                   │
│   └─────────────┬──────────────────────┘                   │
│                 │ 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).

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
        ├── claude/                  # ClaudeSessionManager (stream-json)
        ├── env/                     # EnvSetupService, MCP, Claude auth
        ├── git/                     # GitReader, GitCloneService, credentials
        ├── projects/                # ProjectService, KeystoreGenerator
        ├── build/                   # BuildService (Gradle assembleDebug)
        ├── artifacts/               # APK storage
        ├── files/                   # Upload routes
        ├── admin/                   # SSR routes + HTML templates
        ├── tasks/                   # TaskQueue (background work)
        ├── ws/                      # LogHub (WebSocket broadcaster)
        └── db/                      # VibeDb (SQLite via Exposed)

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.

Persistence

All persistent state lives under one host directory (v0.7.0+). See Data Volumes & Backup for the full mapping.

./vibe-coder-data/
├── workspace/         # project sources + APKs
├── server/            # SQLite DB + server logs
├── 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.

Auth boundary (v0.4.0+)

• 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.
• Passwords: BCrypt cost 12 hash. 10 failures → 15-min lock. Timing-safe dummy verify on missing users.

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.