# Kovanex — Architecture Self-hosted DevOps platform. All-in-one: Git hosting, CI/CD, project management, container registry, secrets vault, AI agent. ## System Overview ``` ┌─────────────────────────────────────────────┐ │ prod VM (pay-pxe02) │ │ prod-host │ │ │ PWA (browser) ────▶│ :8080 gRPC-Web + static files │ │ │ Gio UI (desktop) ─▶│ :9000 gRPC + mTLS │ │ │ git push/pull ────▶│ :2222 Git SSH │ │ │ CLI (kovanex-ctl)─▶│ :9000 gRPC + TLS │ │ │ │ ┌──────────────┐ ┌───────────────────┐ │ │ │ kovadb │ │ Object Store │ │ │ │ :8000 │ │ :9500 API │ │ │ │ embedded │ │ :9501 Console │ │ │ └──────────────┘ └───────────────────┘ │ │ │ │ ┌──────────────┐ ┌───────────────────┐ │ │ │ Prometheus │ │ Grafana │ │ │ │ :9090 │ │ :3001 │ │ │ └──────────────┘ └───────────────────┘ │ └─────────────────────────────────────────────┘ External access: your-server:9000 (gRPC/TLS, 109.245.0.0/16 only) ``` ## Communication Protocol **gRPC only. No REST API.** | Client | Protocol | Port | Transport | |----------------|-----------|------|-------------------| | PWA (browser) | gRPC-Web | 8080 | HTTP/1.1 + proto | | Gio UI desktop | gRPC | 9000 | HTTP/2 + TLS | | Gio UI WASM | gRPC-Web | 8080 | HTTP/1.1 + proto | | CLI (ctl) | gRPC | 9000 | HTTP/2 + TLS | | Git operations | SSH | 2222 | SSH protocol | | Runners | gRPC bidi | 9000 | HTTP/2 + TLS | ## gRPC Services (proto/kovanex.proto) | Service | RPCs | Description | |-----------------|------|------------------------------------------------| | AuthService | 11 | Register, Login, SSH keys, mTLS, OIDC | | GitService | 18 | Repos, branches, commits, PRs, comments, watch | | CICDService | 5 | Pipelines, jobs, log streaming | | RunnerService | 4 | Runner pool, bidi stream, dispatch | | ProjectService | 13 | Projects, members, RBAC, releases | | TaskService | 13 | Tasks, kanban board, sprints | | AdminService | 5 | User management, backup/restore | | RegistryService | 7 | OCI images, retention, push/pull streams | ## Source Structure ``` kovanex/ ├── cmd/ │ ├── server/main.go # Main server — wires all services │ ├── ctl/main.go # CLI client (gRPC) — all management + AI commands │ ├── ui/main.go # Gio UI entry point (desktop + WASM) │ ├── runner/main.go # CI/CD runner agent │ ├── ai-runner/main.go # AI runner agent (standalone) │ ├── backup/main.go # Backup utility │ └── logs/main.go # Log viewer utility │ ├── internal/ │ ├── auth/ │ │ ├── auth.go # JWT, OIDC, mTLS, interceptors │ │ └── git_auth.go # SSH key auth for git │ ├── git/ │ │ └── server.go # Git repos, branches, commits, PRs, diff │ ├── cicd/ │ │ └── engine.go # Pipeline engine, job execution, topo sort │ ├── runner/ │ │ └── pool.go # Runner pool, job dispatch, bidi comms │ ├── task/ │ │ ├── service.go # Task CRUD, kanban, sprints │ │ └── eventbus.go # Task events (status changes, assignments) │ ├── kanban/ │ │ └── service.go # Board state, columns, drag-drop logic │ ├── project/ │ │ └── service.go # Projects, members, RBAC │ ├── rbac/ │ │ └── service.go # Role-based access control │ ├── registry/ │ │ └── service.go # OCI image registry │ ├── vault/ │ │ ├── vault.go # Secrets vault (encrypted KV store) │ │ └── shamir/shamir.go # Shamir secret sharing for unseal │ ├── agent/ │ │ └── worker.go # AI agent (server-side, optional) │ ├── ai/ │ │ ├── agent.go # AI agent logic │ │ ├── context_api.go # AI context building for tasks │ │ └── cicd/participant.go # AI in CI/CD pipeline │ ├── gitflow/ │ │ ├── handler.go # Gitflow branch management │ │ └── coordinator.go # Gitflow coordination │ ├── artifacts/ │ │ └── service.go # Build artifact storage │ ├── objectstore/ │ │ └── store.go # S3-compatible object store │ ├── backup/ │ │ └── service.go # Database backup/restore │ ├── metrics/ │ │ └── collector.go # Prometheus metrics │ ├── methodology/ │ │ └── presets.go # Kanban/Scrum/PMBOK presets │ ├── oidc/ │ │ └── provider.go # OIDC authentication provider │ ├── db/ │ │ ├── store.go # legacy SurrealDB store (only-mode runs on kovadb) │ │ ├── surrealdb_store.go # legacy; superseded by internal/kovadbstore │ │ └── helpers.go # Query helpers, emptyArr, execSQL │ └── grpc/ │ ├── register.go # Wire all gRPC services │ ├── gateway.go # HTTP gateway (gRPC-Web proxy) │ ├── interceptors.go # Auth interceptor, logging │ ├── auth_handler.go # AuthService implementation │ ├── git_handler.go # GitService implementation │ ├── cicd_handler.go # CICDService implementation │ ├── runner_handler.go # RunnerService implementation │ ├── project_handler.go# ProjectService implementation │ ├── task_handler.go # TaskService implementation │ ├── admin_handler.go # AdminService implementation │ ├── registry_handler.go # RegistryService implementation │ └── linkedcommits.go # Git-task commit linking │ ├── ui/ # Gio UI (Go-native, desktop + WASM) │ ├── app.go # Root app, routing, sidebar + content │ ├── sidebar.go # Navigation sidebar │ ├── theme/theme.go # Dark theme (GitHub/VS Code style) │ ├── api/client.go # gRPC client wrapper (35+ methods) │ └── page/ │ ├── page.go # Type aliases (C, D) │ ├── login.go # Login/register screen │ ├── dashboard.go # Dashboard with stat cards │ ├── repos.go # Repository list │ ├── repo_detail.go # Repo detail (files/branches/commits/PRs tabs) │ ├── kanban.go # Kanban board with columns │ ├── projects.go # Project list │ ├── pipelines.go # CI/CD pipeline list │ └── admin.go # User management │ ├── pwa/ # PWA (HTML/JS, gRPC-Web) │ ├── index.html # Full SPA with all screens │ ├── grpc-client.js # gRPC-Web client │ └── sw.js # Service worker (offline) │ ├── proto/ │ ├── kovanex.proto # All service + message definitions │ └── gen/ # Generated Go code (pb.go + grpc.pb.go) │ ├── docker-compose.yml # Production (server) ├── docker-compose.local.yml # Local development ├── docker-compose.vps.yml # VPS deployment variant ├── Dockerfile # Server multi-stage build ├── Dockerfile.runner # Runner image ├── kovanex.yml # Self-deploy CI/CD pipeline ├── Makefile # Build targets ├── prometheus.yml # Metrics config ├── grafana-dashboard.json # Pre-built dashboard └── nginx/nginx.conf # Reverse proxy config ``` ## Database — kovadb Storage engine: **kovadb** — an embedded, pure-Go document + graph + vector store. One bbolt-backed file holds every collection; there is no separate database process. Migrated from SurrealDB in v7.4 (see `SURREALDB_MIGRATION.md`). The schema modes below are legacy SurrealDB terminology retained for reference; in kovadb every domain is a typed document collection with optional secondary indexes and graph edges. | Table | Mode | Description | |-----------------|------------|---------------------------------| | users | SCHEMAFULL | User accounts, roles | | repos | SCHEMAFULL | Git repositories | | commits | SCHEMAFULL | Commit history | | pull_requests | SCHEMAFULL | PRs with status/merge tracking | | pr_comments | SCHEMAFULL | PR review comments (human + AI) | | pipelines | SCHEMAFULL | CI/CD pipelines + jobs | | runners | SCHEMAFULL | CI/CD runner agents | | mtls_keys | SCHEMAFULL | mTLS certificates | | projects | SCHEMALESS | Projects (flexible fields) | | boards | SCHEMALESS | Kanban boards | | tasks | SCHEMALESS | Tasks with AI fields | | sprints | SCHEMALESS | Sprint tracking | | members | SCHEMALESS | Project membership + roles | ## Frontends ### PWA (pwa/) - Vanilla HTML/JS, no framework - gRPC-Web via `grpc-client.js` - Served from `:8080` alongside gRPC-Web gateway - Full SPA: login, dashboard, repos, PRs, pipelines, kanban, projects, admin, AI chat - Service worker for offline capability ### Gio UI (ui/) - Go-native UI framework (gioui.org) - Compiles to **desktop** (Linux/Mac/Windows, 25MB) and **WASM** (32MB raw, ~8MB gzip) - Desktop: native gRPC on `:9000` (no proxy needed) - WASM: gRPC-Web on `:8080` (same as PWA) - Dark theme, 8 screens: login, dashboard, repos, repo detail, kanban, projects, pipelines, admin - Entry point: `cmd/ui/main.go`, flags: `-server`, `-insecure` ### CLI (cmd/ctl/) - Full management CLI over gRPC - Commands: login, tasks, board, pipelines, repos, projects, releases, images, vault, users, status - AI commands: `ai review`, `ai fix`, `ai task` — uses local `ANTHROPIC_API_KEY` - Token cached in `/tmp/kovanex-token` ## AI Agent Two modes: ### Client-side (primary, CLI) ```bash export ANTHROPIC_API_KEY=sk-ant-... kovanex-ctl ai review # Review PR, post comments kovanex-ctl ai fix # Fix failed CI/CD pipeline kovanex-ctl ai task # Implement task, save files ``` - API key stays on developer's machine - Developer controls when/what AI runs - Shows token usage after each call - Interactive: asks before posting comments or committing ### Server-side (optional, for teams 20+) Enabled by setting `ANTHROPIC_API_KEY` in server `.env`. - Auto-polls tasks assigned to `agent:claude` every 30s - Auto-reviews every new PR - Auto-fixes failed pipelines - **Budget controls:** - `AGENT_MAX_DAILY_TOKENS` — default 500K tokens/day - `AGENT_MAX_REQUESTS_HOUR` — default 20 req/hour - Counters reset automatically - Logged on every API call ## Infrastructure | Service | Image/Version | Purpose | Ports | |------------|---------------|----------------------|----------------| | kovanex | Go 1.24 | Main server | 8080, 9000, 2222 | | kovadb | embedded | Document/graph/vector store (in-process) | — (no port) | | s3 | S3-compatible | Object storage | 9500, 9501 | | prometheus | latest | Metrics | 9090 (internal) | | grafana | latest | Dashboards | 3001 | ## Deployment Self-deploy pipeline (`kovanex.yml`): push to `main` → sync source → docker build → deploy → healthcheck. Manual: ```bash ssh -J root@jump-host root@prod-host cd /opt/kovanex-server docker compose build kovanex && docker compose up -d kovanex docker logs --tail 30 kovanex ``` ## Key Design Decisions 1. **gRPC only** — no REST API, all clients use gRPC or gRPC-Web 2. **Gio UI over HTML** — single Go codebase for desktop + browser, no HTML/CSS debugging 3. **AI as CLI first** — developer controls spending; server agent is opt-in for large teams 4. **kovadb** — one embedded store unifies documents, the graph (backlinks, problem links, provenance), and vector search; no separate database to operate 5. **Self-hosting** — everything runs on one VM, no cloud dependencies 6. **Vault built-in** — Shamir secret sharing, AES-256-GCM encryption, no external dependencies