hkcc 0.1.0

package/README.md

@@ -0,0 +1,768 @@
+# Claude OAuth Proxy
+
+A proxy server providing Claude API access through two simultaneous modes:
+
+- **SDK Mode (`/sdk/*`)** - Uses locally installed Claude Code CLI via Agent SDK
+- **OAuth Mode (`/api/*`)** - Direct API calls with OAuth tokens
+
+Each mode supports both Anthropic and OpenAI-compatible formats:
+
+- `/sdk/anthropic/*` or `/api/anthropic/*` - Anthropic Messages API format
+- `/sdk/openai/*` or `/api/openai/*` - OpenAI Chat Completions API format
+
+Both modes run simultaneously. Choose based on your setup.
+
+## Architecture
+
+```mermaid
+graph LR
+    Client[Client<br/>SDKs, Apps, CLI] --> Proxy[HKCC Proxy Server]
+
+    Proxy --> SDK[SDK Mode<br/>/sdk/*]
+    Proxy --> OAuth[OAuth Mode<br/>/api/*]
+
+    SDK --> CLI[Claude Code CLI] --> API[Claude API]
+    OAuth --> Transform[Transform Request<br/>+ OAuth Token<br/>+ Magic Headers] --> API
+
+    Proxy --> DB[(Database<br/>Users & Credentials)]
+
+    style SDK fill:#e3f2fd
+    style OAuth fill:#fff3e0
+    style DB fill:#e8f5e9
+```
+
+**Two Modes:**
+
+- **SDK Mode** - Routes through locally installed Claude Code CLI (full features)
+- **OAuth Mode** - Direct API calls with OAuth tokens (lightweight, no CLI needed)
+
+**Multi-User Support:** Session cookies and per-user API keys with database-backed credential storage
+
+See [TECHNICAL.md](TECHNICAL.md) for detailed architecture diagrams and implementation details.
+
+## Quick Start
+
+```bash
+bun install
+bun dev
+```
+
+Server starts at `http://127.0.0.1:3000`
+
+## Build
+
+Build both server and frontend dashboard:
+
+```bash
+bun run build.ts
+```
+
+This creates:
+
+```
+dist/
+├── index.js      # Bundled server
+└── public/       # Frontend dashboard
+    ├── index.css
+    ├── index.html
+    └── index.js
+```
+
+Run the built server:
+
+```bash
+bun run dist/index.js
+```
+
+## CLI
+
+HKCC can be run as a CLI tool via `npx` or `bunx`, perfect for quick local usage without Docker.
+
+### Installation
+
+```bash
+# Via npx (requires Node.js)
+npx hkcc --help
+
+# Via bunx (requires Bun)
+bunx hkcc --help
+
+# Or run directly from the repo
+bun run bin/hkcc.ts --help
+```
+
+### Usage Examples
+
+**Local SQLite (simplest setup):**
+
+```bash
+# Run with local SQLite database in current directory
+bunx hkcc --sqlite-path ./data/hkcc.db --db-driver bun-sqlite
+
+# Or run from anywhere
+bunx hkcc --sqlite-path ~/hkcc-data/db.sqlite --port 8080
+```
+
+**Turso Cloud Database:**
+
+```bash
+bunx hkcc \
+  --db-driver turso \
+  --turso-url libsql://your-db.turso.io \
+  --turso-token your-auth-token \
+  --port 3000
+```
+
+**CLI Arguments:**
+
+| Argument        | Alias | Description                                  | Default                        |
+| --------------- | ----- | -------------------------------------------- | ------------------------------ |
+| `--port`        | `-p`  | Server port                                  | `3000` or `PORT` env var       |
+| `--host`        | `-h`  | Server host                                  | `127.0.0.1` or `HOST` env var  |
+| `--db-driver`   |       | Database driver (`turso` or `bun-sqlite`)    | Auto-detect                    |
+| `--turso-url`   |       | Turso connection URL                         | `TURSO_CONNECTION_URL` env var |
+| `--turso-token` |       | Turso auth token                             | `TURSO_AUTH_TOKEN` env var     |
+| `--sqlite-path` |       | SQLite database path (relative to CWD)       | `./data/hkcc.db`               |
+| `--claude-path` |       | Path to Claude Code CLI executable           | Auto-detect                    |
+| `--production`  |       | Enable production mode (static file serving) | Enabled                        |
+
+**Key Features:**
+
+- Runs from any directory - database path is relative to CWD
+- Static files (dashboard CSS/JS) served correctly regardless of where you run it
+- Migrations run automatically from the package location
+- All auth modules share the same database instance
+
+**CLI vs Server Mode:**
+
+| Feature      | CLI (`bunx hkcc`)          | Server (`bun run src/index.ts`)   |
+| ------------ | -------------------------- | --------------------------------- |
+| Entry Point  | `bin/hkcc.ts`              | `src/index.ts`                    |
+| Args         | CLI arguments              | Environment variables             |
+| CWD          | Database relative to CWD   | Database relative to project root |
+| Use Case     | Quick start, any directory | Development in project            |
+| Static Files | Production mode            | Dev mode (hot reload)             |
+
+## Dashboard
+
+The server hosts a web dashboard at the root URL (`/`) for managing OAuth credentials and viewing server status. The dashboard is built with React and Tailwind CSS.
+
+## Docker
+
+All images require database configuration via environment variables.
+
+```bash
+# Default (with Claude Code CLI, bundled JS)
+docker build -f Dockerfile -t hkcc:latest .
+docker run -p 3000:3000 \
+  -e TURSO_CONNECTION_URL=libsql://your-db.turso.io \
+  -e TURSO_AUTH_TOKEN=your-token \
+  -v hkcc-claude:/home/claude/.claude \
+  hkcc:latest
+
+# OAuth-only (smaller image, bundled JS)
+docker build -f Dockerfile.oauth -t hkcc:oauth .
+docker run -p 3000:3000 \
+  -e TURSO_CONNECTION_URL=libsql://your-db.turso.io \
+  -e TURSO_AUTH_TOKEN=your-token \
+  hkcc:oauth
+
+# Compiled binary (no Bun runtime needed, with Claude Code CLI)
+docker build -f Dockerfile.compiled -t hkcc:compiled .
+docker run -p 3000:3000 \
+  -e TURSO_CONNECTION_URL=libsql://your-db.turso.io \
+  -e TURSO_AUTH_TOKEN=your-token \
+  -v hkcc-claude:/home/claude/.claude \
+  hkcc:compiled
+
+# Compiled binary (no Bun runtime, OAuth-only, smallest)
+docker build -f Dockerfile.compiled-oauth -t hkcc:compiled-oauth .
+docker run -p 3000:3000 \
+  -e TURSO_CONNECTION_URL=libsql://your-db.turso.io \
+  -e TURSO_AUTH_TOKEN=your-token \
+  hkcc:compiled-oauth
+```
+
+**Volume mounts:**
+
+- **SDK mode images** (`Dockerfile`, `Dockerfile.compiled`): Volume at `/home/claude/.claude`
+  - Stores Claude Code CLI authentication for SDK mode
+- **OAuth-only images** (`Dockerfile.oauth`, `Dockerfile.compiled-oauth`): No volume needed
+  - All credentials stored in database
+
+### Multi-Platform Builds (buildx)
+
+Build images for both ARM64 (Apple Silicon) and AMD64 (Intel/AMD) architectures:
+
+```bash
+# Create and use buildx builder (one-time setup)
+docker buildx create --use
+
+# Build for multiple platforms and push to registry
+docker buildx build --platform linux/amd64,linux/arm64 \
+  -t your-registry/hkcc:latest \
+  -f Dockerfile \
+  --push .
+
+# Build for multiple platforms (load local - only works for single arch)
+docker buildx build --platform linux/amd64,linux/arm64 \
+  -t hkcc:latest \
+  -f Dockerfile \
+  --output type=local,dest=./output .
+```
+
+**Note**: All Dockerfiles now support Docker buildx for multi-platform builds. The compiled variants automatically detect the target platform and compile the appropriate binary.
+
+### Docker Image Variants
+
+| Dockerfile                  | Claude Code CLI | Runtime       | Base OS | Size  | Best For                                  |
+| --------------------------- | --------------- | ------------- | ------- | ----- | ----------------------------------------- |
+| `Dockerfile`                | Yes             | Bun JS        | Alpine  | 327MB | Development, hot reload, full features    |
+| `Dockerfile.oauth`          | No              | Bun JS        | Alpine  | 107MB | OAuth-only deployments, smaller footprint |
+| `Dockerfile.compiled`       | Yes             | Native binary | Debian  | 425MB | Production with SDK mode, faster startup  |
+| `Dockerfile.compiled-oauth` | No              | Native binary | Debian  | 204MB | Production OAuth-only, smallest image     |
+
+**Key Differences:**
+
+- **Bundled JS (`.js`)**: Requires Bun runtime at runtime. Larger base image but faster builds.
+- **Native Binary**: Pre-compiled executable. No Bun runtime needed, faster cold start, slower builds.
+- **Claude Code CLI**: Required for SDK mode (`/sdk/*`). Adds ~220MB to image size.
+- **Alpine vs Debian**: Alpine is smaller but uses musl libc. Debian uses glibc, needed for Claude Code CLI.
+
+### Docker Compose
+
+For easier deployment and configuration management, use Docker Compose. Create a `docker-compose.yml` file:
+
+**Basic setup with Turso cloud database (recommended for production):**
+
+```yaml
+version: "3.8"
+
+services:
+  hkcc:
+    image: huakunshen/hkcc:latest # or build locally: build: .
+    container_name: hkcc-proxy
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      # Server configuration
+      - HOST=0.0.0.0
+      - PORT=3000
+
+      # Database - Turso (cloud)
+      - TURSO_CONNECTION_URL=libsql://your-db.turso.io
+      - TURSO_AUTH_TOKEN=your-auth-token
+
+      # Optional: Disable registration after creating accounts
+      # - HKCC_REGISTRATION_ENABLED=false
+    volumes:
+      # Persist Claude Code CLI authentication (SDK mode only)
+      - hkcc-claude:/home/claude/.claude
+
+volumes:
+  hkcc-claude:
+```
+
+**OAuth-only deployment (smaller image, no SDK mode):**
+
+```yaml
+version: "3.8"
+
+services:
+  hkcc:
+    image: huakunshen/hkcc:oauth # Uses OAuth-only image (smaller)
+    container_name: hkcc-oauth-proxy
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - HOST=0.0.0.0
+      - PORT=3000
+      - TURSO_CONNECTION_URL=libsql://your-db.turso.io
+      - TURSO_AUTH_TOKEN=your-auth-token
+```
+
+**Using local SQLite database (no external database needed):**
+
+```yaml
+version: "3.8"
+
+services:
+  hkcc:
+    image: huakunshen/hkcc:latest
+    container_name: hkcc-proxy
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - HOST=0.0.0.0
+      - PORT=3000
+      # No TURSO variables = uses local SQLite at ./data/hkcc.db
+      # Optional: Custom database path
+      # - SQLITE_DATABASE_PATH=/app/data/hkcc.db
+    volumes:
+      # Persist local SQLite database
+      - hkcc-data:/app/data
+      # Persist Claude Code CLI authentication (SDK mode)
+      - hkcc-claude:/home/claude/.claude
+
+volumes:
+  hkcc-data:
+  hkcc-claude:
+```
+
+**Compiled binary with faster startup (production-optimized):**
+
+```yaml
+version: "3.8"
+
+services:
+  hkcc:
+    image: huakunshen/hkcc:compiled # Native binary, no Bun runtime
+    container_name: hkcc-compiled
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - HOST=0.0.0.0
+      - PORT=3000
+      - TURSO_CONNECTION_URL=libsql://your-db.turso.io
+      - TURSO_AUTH_TOKEN=your-auth-token
+    volumes:
+      - hkcc-claude:/home/claude/.claude
+
+volumes:
+  hkcc-claude:
+```
+
+**Using environment file for secrets:**
+
+Create a `.env` file (git-ignored):
+
+```bash
+# .env
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-auth-token
+HKCC_REGISTRATION_ENABLED=false
+```
+
+Update `docker-compose.yml` to use it:
+
+```yaml
+services:
+  hkcc:
+    image: huakunshen/hkcc:latest
+    container_name: hkcc-proxy
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    volumes:
+      - hkcc-claude:/home/claude/.claude
+
+volumes:
+  hkcc-claude:
+```
+
+**Deploy with Docker Compose:**
+
+```bash
+# Start the service
+docker compose up -d
+
+# View logs
+docker compose logs -f
+
+# Stop the service
+docker compose down
+
+# Stop and remove volumes (WARNING: deletes data)
+docker compose down -v
+
+# Rebuild with local changes
+docker compose up -d --build
+```
+
+**Key considerations:**
+
+| Image Variant         | SDK Mode | OAuth Mode | Volume Needed          | Best Use Case              |
+| --------------------- | -------- | ---------- | ---------------------- | -------------------------- |
+| `hkcc:latest`         | ✅       | ✅         | `/home/claude/.claude` | Full features, development |
+| `hkcc:oauth`          | ❌       | ✅         | ❌                     | OAuth-only, smaller image  |
+| `hkcc:compiled`       | ✅       | ✅         | `/home/claude/.claude` | Production, faster startup |
+| `hkcc:compiled-oauth` | ❌       | ✅         | ❌                     | OAuth-only, production     |
+
+**Database options:**
+
+- **Turso (cloud)**: Set `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN` - Best for production, multi-instance setups
+- **Local SQLite**: Don't set Turso variables - Automatically uses `/app/data/hkcc.db` - Best for single-instance, development
+
+## API Endpoints
+
+### Health & Status
+
+```bash
+curl http://127.0.0.1:3000/health
+curl http://127.0.0.1:3000/oauth/status
+```
+
+### SDK Mode (`/sdk/*`) - Requires Claude Code CLI
+
+```bash
+# Anthropic Messages API
+curl -X POST http://127.0.0.1:3000/sdk/anthropic/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'
+
+# OpenAI Chat Completions API
+curl -X POST http://127.0.0.1:3000/sdk/openai/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello!"}]}'
+```
+
+### OAuth Mode (`/api/*`) - Requires OAuth Authentication
+
+```bash
+# Anthropic Messages API
+curl -X POST http://127.0.0.1:3000/api/anthropic/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'
+
+# OpenAI Chat Completions API
+curl -X POST http://127.0.0.1:3000/api/openai/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello!"}]}'
+```
+
+### Model Mapping
+
+| OpenAI Model                     | Claude Model                 |
+| -------------------------------- | ---------------------------- |
+| `gpt-4`, `gpt-4-turbo`, `gpt-4o` | `claude-sonnet-4-5-20250929` |
+| `gpt-3.5-turbo`                  | `claude-haiku-3-5-20241022`  |
+
+## Database Setup (Required)
+
+The server stores user accounts, OAuth credentials, and API keys in a database. Both cloud (Turso) and local SQLite databases are supported.
+
+### Auto-Detection (Recommended)
+
+The server automatically detects which database to use:
+
+- If `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN` are set → uses Turso (cloud)
+- Otherwise → uses local SQLite at `./data/hkcc.db`
+
+For new users, no configuration is needed - the server will automatically use local SQLite.
+
+### Local SQLite (Default)
+
+```bash
+# No configuration needed - uses ./data/hkcc.db by default
+bun dev
+```
+
+To customize the database file location:
+
+```bash
+SQLITE_DATABASE_PATH=./custom/path/db.sqlite
+```
+
+### Turso (Cloud Database)
+
+Set the database environment variables in `.env`:
+
+```bash
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-auth-token
+```
+
+### Manual Override
+
+Override auto-detection with:
+
+```bash
+DB_DRIVER=turso          # Force Turso
+# or
+DB_DRIVER=bun-sqlite     # Force local SQLite
+```
+
+### Migrations
+
+Migrations run automatically on server startup. For manual migration management:
+
+```bash
+bun drizzle-kit push     # Apply schema to database
+bun drizzle-kit studio   # Open database GUI
+```
+
+## User Authentication
+
+```bash
+# Register
+curl -X POST http://127.0.0.1:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "password123", "username": "myuser"}'
+
+# Login
+curl -X POST http://127.0.0.1:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "password123"}'
+
+# Get current user
+curl http://127.0.0.1:3000/auth/me -b "hkcc_session=SESSION_TOKEN"
+
+# Logout
+curl -X POST http://127.0.0.1:3000/auth/logout -b "hkcc_session=SESSION_TOKEN"
+```
+
+Registration can be disabled by setting `HKCC_REGISTRATION_ENABLED=false` after creating your account.
+
+## OAuth Authentication
+
+After logging in, authenticate with OAuth providers via the dashboard or API:
+
+```bash
+# Get Anthropic authorization URL
+curl http://127.0.0.1:3000/oauth/anthropic/login?mode=max
+
+# Get OpenAI/Codex authorization URL
+curl http://127.0.0.1:3000/oauth/openai/login
+
+# Check OAuth status
+curl http://127.0.0.1:3000/oauth/anthropic/status
+curl http://127.0.0.1:3000/oauth/openai/status
+```
+
+### PKCE Authentication Flow
+
+The server uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Browser
+    participant Proxy as HKCC Proxy
+    participant Claude as claude.ai
+
+    User->>Browser: Click "Login with Claude"
+    Browser->>Proxy: GET /oauth/anthropic/login
+    Proxy->>Proxy: Generate PKCE<br/>code_verifier<br/>code_challenge
+    Proxy-->>Browser: Authorization URL + state
+
+    Browser->>Claude: Redirect to authorization URL
+    Claude->>User: Show consent screen
+    User->>Claude: Approve access
+    Claude-->>Browser: Redirect with auth code
+
+    Browser->>Proxy: GET /oauth/anthropic/callback?code=xxx
+    Proxy->>Claude: POST /oauth/token<br/>(code + verifier)
+    Claude-->>Proxy: access_token + refresh_token
+    Proxy->>Proxy: Store credentials in database
+    Proxy-->>Browser: Redirect to dashboard
+    Browser->>User: Authentication complete
+```
+
+**Security features:**
+
+- PKCE prevents authorization code interception attacks
+- State parameter prevents CSRF attacks
+- Tokens stored securely in database with user isolation
+- Automatic token refresh before expiration
+
+### API Access Modes
+
+| Mode                | Authentication                  | Credentials Used            |
+| ------------------- | ------------------------------- | --------------------------- |
+| Dashboard (browser) | Session cookie (`hkcc_session`) | User's database credentials |
+| Per-user API key    | `hkcc_sk_xxx` in header         | User's database credentials |
+
+### Per-User API Keys
+
+Each registered user can create up to 5 personal API keys for external applications like Cherry Studio, Cursor, or custom scripts.
+
+**Create an API key** (via dashboard or API):
+
+```bash
+# Create key via API (requires session cookie)
+curl -X POST http://127.0.0.1:3000/auth/api-keys \
+  -H "Content-Type: application/json" \
+  -b "hkcc_session=SESSION_TOKEN" \
+  -d '{"name": "Cherry Studio"}'
+
+# Response includes the full key (shown only once):
+# {"success":true,"key":"hkcc_sk_a1b2c3d4e5f6...","apiKey":{"id":1,"keyPrefix":"hkcc_sk_a1b2...","name":"Cherry Studio"}}
+```
+
+**Use the API key** in external clients:
+
+```bash
+curl -X POST http://127.0.0.1:3000/api/anthropic/v1/messages \
+  -H "x-api-key: hkcc_sk_a1b2c3d4e5f6..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'
+
+# Or use Authorization header:
+curl -X POST http://127.0.0.1:3000/api/anthropic/v1/messages \
+  -H "Authorization: Bearer hkcc_sk_a1b2c3d4e5f6..." \
+  ...
+```
+
+**Manage API keys**:
+
+```bash
+# List keys
+curl http://127.0.0.1:3000/auth/api-keys -b "hkcc_session=SESSION_TOKEN"
+
+# Delete a key
+curl -X DELETE http://127.0.0.1:3000/auth/api-keys/1 -b "hkcc_session=SESSION_TOKEN"
+```
+
+### Token Refresh
+
+A cron job runs every hour to automatically refresh tokens expiring within 60 minutes. Claude access tokens have an 8-hour TTL (480 minutes).
+
+## SDK Integration
+
+### Vercel AI SDK
+
+```typescript
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { generateText } from "ai";
+
+const anthropic = createAnthropic({
+  baseURL: "http://127.0.0.1:3000/api/anthropic", // OAuth mode
+  apiKey: "hkcc_sk_your_personal_api_key", // Per-user API key
+});
+
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-5-20250929"),
+  prompt: "Hello!",
+});
+```
+
+### Anthropic SDK
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic({
+  baseURL: "http://127.0.0.1:3000/api/anthropic", // OAuth mode
+  apiKey: "hkcc_sk_your_personal_api_key", // Per-user API key
+});
+
+const message = await client.messages.create({
+  model: "claude-sonnet-4-5-20250929",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+### OpenAI SDK
+
+```typescript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "http://127.0.0.1:3000/api/anthropic/openai/v1", // OAuth mode with OpenAI format
+  apiKey: "hkcc_sk_your_personal_api_key", // Per-user API key
+});
+
+const completion = await client.chat.completions.create({
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+## Environment Variables
+
+```bash
+# Server Configuration
+PORT=3000                        # Server port (default: 3000)
+HOST=127.0.0.1                   # Server host (default: 127.0.0.1)
+
+# Database (Required)
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-auth-token
+
+# Registration Control
+HKCC_REGISTRATION_ENABLED=true   # Set to "false" to disable new user registration
+```
+
+## Development
+
+```bash
+bun run dev          # Run with hot reload
+bun run build.ts     # Build server and frontend
+bun test             # Run tests
+bun run format       # Format code
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts           # Server entry point (development)
+├── app.ts             # Elysia app factory
+├── auth/              # OAuth & user authentication, API key management
+├── db/                # Drizzle ORM schema and database connection
+├── cron/              # Scheduled jobs (token refresh)
+├── proxy/             # SDK and OAuth proxy implementations
+├── routes/            # OAuth and auth endpoints
+├── adapters/          # Request/response format adapters
+├── transform/         # Request/response transformations
+├── middleware/        # API key validation, error handling
+├── mcp-bridge/        # MCP tool bridging for client tools
+└── utils/             # Utilities (Claude Code detection)
+
+bin/
+└── hkcc.ts            # CLI entry point (npx/bunx)
+
+public/                # Frontend source (React + Tailwind)
+├── index.tsx          # React entry point
+└── pages/             # Dashboard pages
+
+build.ts               # Build script for server, CLI, and frontend
+```
+
+See [TECHNICAL.md](./TECHNICAL.md) for architecture details.
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Framework**: Elysia
+- **Frontend**: React, TanStack Router, Tailwind CSS
+- **Type-Safe Client**: Eden
+- **Database**: Turso (libSQL) with Drizzle ORM
+- **Validation**: Zod + Elysia's t.Object
+
+## Docker Build
+
+```bash
+# Build and push with timestamp tags for all variants
+DATE_TAG=$(date +%Y-%m-%d-%H-%M-%S)
+
+# Default (latest + oauth + compiled + compiled-oauth)
+docker buildx build --push --platform linux/amd64,linux/arm64 \
+  -t huakunshen/hkcc:latest \
+  -t huakunshen/hkcc:latest-${DATE_TAG} \
+  -f Dockerfile .
+
+docker buildx build --push --platform linux/amd64,linux/arm64 \
+  -t huakunshen/hkcc:oauth \
+  -t huakunshen/hkcc:oauth-${DATE_TAG} \
+  -f Dockerfile.oauth .
+
+docker buildx build --push --platform linux/amd64,linux/arm64 \
+  -t huakunshen/hkcc:compiled \
+  -t huakunshen/hkcc:compiled-${DATE_TAG} \
+  -f Dockerfile.compiled .
+
+docker buildx build --push --platform linux/amd64,linux/arm64 \
+  -t huakunshen/hkcc:compiled-oauth \
+  -t huakunshen/hkcc:compiled-oauth-${DATE_TAG} \
+  -f Dockerfile.compiled-oauth .
+```
+
+**Note:** Each image is tagged with both the standard tag (e.g., `latest`, `oauth`) and a timestamped tag (e.g., `oauth-2026-01-29-21-03-17`) for version tracking. All images support both `linux/amd64` and `linux/arm64` platforms.