Platform Overview | Viberglass Docs

Viberglass is a three-tier system that turns user-supplied tickets into pull requests by orchestrating containerised AI coding agents.

┌─────────────┐    webhooks    ┌──────────────────┐    invokes    ┌──────────────────┐
│  External   │ ─────────────▶ │ Platform Backend │ ────────────▶ │ Viberator Worker │
│ (GitHub /   │                │  (Express + PG)  │               │  (agent harness) │
│  Slack /    │ ◀───────────── │                  │ ◀──────────── │                  │
│  Custom)    │   feedback     │                  │   callbacks   │                  │
└─────────────┘                └────────┬─────────┘               └────────┬─────────┘
                                        │                                  │
                                        │ REST/WS                          │ git push, PR API
                                        ▼                                  ▼
                                ┌──────────────────┐               ┌──────────────────┐
                                │ Platform Frontend│               │  GitHub / GitLab │
                                │   (React SPA)    │               │       SCM        │
                                └──────────────────┘               └──────────────────┘

The four moving parts

1. Platform Backend — `apps/platform-backend`

A Node.js 24 / TypeScript Express API that owns the database and orchestrates everything else.

Framework: Express 4 with Helmet, rate limiting, Multer for uploads, Joi for validation, Passport for auth.
Database: PostgreSQL accessed through Kysely (type-safe query builder). 56+ migrations live in src/migrations/.
Job orchestration: Submits jobs to workers via the platform's WorkerExecutionService, which routes to a deployment-strategy-specific invoker (Lambda, ECS, or Docker).
Webhooks: Inbound webhook routes for GitHub, Jira, Shortcut, and custom endpoints; outbound feedback to integrations.
Slack chat backend: uses @chat-adapter/slack plus a PostgreSQL state adapter so thread ↔ session mappings survive restarts.
Logging: Winston with daily rotation (and CloudWatch in production).

2. Platform Frontend — `apps/platform-frontend`

A React 19 + Vite 6 + Tailwind CSS 4 SPA. Built with Radix UI primitives and React Router 7. Hosted on AWS Amplify in production. The whole UI: dashboard, tickets, claws, clankers, secrets, integrations comes from this app.

3. Viberator Worker — `apps/viberator`

The container that runs the actual AI agent. A single TypeScript codebase with three entry points:

CLI for local Docker runs.
Lambda handler for serverless invocation.
Docker entrypoint for ECS Fargate.

The worker:

Receives a job payload with the ticket, repo, agent, secrets, and prompt.
Fetches credentials from environment variables, SSM, or the platform database.
Initialises the chosen agent harness (Claude Code, OpenAI Codex, Qwen CLI, Gemini CLI, OpenCode, Kimi Code, or Mistral Vibe).
Clones the source repository, runs the agent against the prompt, and streams output back to the platform via a callback token.
Commits, pushes, and (for the Execution phase) opens a pull request through the SCM API.

4. Infrastructure — `infra/`

Three Pulumi stacks deployed in order:

infra/base — VPC, KMS, CloudWatch log groups.
infra/platform — ECS Fargate cluster for the backend, RDS PostgreSQL, S3 buckets, and the Amplify app for the frontend.
infra/workers — ECR repositories, Lambda functions, and ECS task definitions for every clanker variant.

CI/CD is GitHub Actions with OIDC federation; deploys are gated per environment, and Pulumi state is stored in S3.

Data stores

PostgreSQL is the system of record. Every entity — projects, tickets, jobs, clankers, claws, secrets, integration credentials, agent sessions, phase documents, approvals, revisions — lives there.
S3 stores media assets (screenshots, recordings), large instruction files attached to clankers, and bootstrap payloads for workers.
SSM Parameter Store is the production secret store (with KMS encryption).
CloudWatch Logs captures backend, worker, and platform logs in JSON format.

Authentication

Email/password, with sessions stored in the user_sessions table.
AUTH_ENABLED env var disables auth for local development.
Roles per project (user_projects table) gate access to project-scoped views.

The four moving parts

1. Platform Backend — apps/platform-backend

2. Platform Frontend — apps/platform-frontend

3. Viberator Worker — apps/viberator

4. Infrastructure — infra/