# Vibn Architecture ## Overview Every project gets a persistent AI brain (the Master Orchestrator) that runs 24/7 on shared infrastructure. It manages specialist agents that handle Coding, Marketing, Support, Monitoring, and Debugging autonomously. Users interact through three channels: mobile app, browser dashboard, or the full Theia IDE. --- ## System Layers ``` ┌─────────────────────────────────────────────────────────────────┐ │ User Interfaces │ │ │ │ Mobile App Browser Dashboard Theia IDE │ │ (chat + status) (chat + dashboards) (full IDE + │ │ vibe coding) │ │ REST/WebSocket REST/WebSocket WebSocket │ └────────┬───────────────────┬───────────────────────┬────────────┘ │ │ │ └───────────────────┼───────────────────────┘ │ ┌────────────────────────────┴────────────────────────────────────┐ │ API Gateway │ │ api.vibnai.com │ │ Auth, routing, WebSocket upgrade, rate limiting │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────┴────────────────────────────────────┐ │ Master Orchestrator │ │ (Hot Tier — always running) │ │ │ │ - Full project context (code, docs, marketing, support) │ │ - Routes work to specialist agents │ │ - Receives webhooks (Gitea push, Coolify deploy, support tix) │ │ - Manages task queue across all agents │ │ - Calls Gemini API │ │ - Persists conversation history per project │ │ │ │ Specialist Agents (run as needed): │ │ ┌──────────┬───────────┬──────────┬────────────┬───────────┐ │ │ │ Coder │ Marketing │ Support │ Monitor │ Debugger │ │ │ │ │ │ │ │ │ │ │ │ Writes │ Updates │ Answers │ Watches │ Reads │ │ │ │ code, │ landing │ user │ logs, │ errors, │ │ │ │ tests, │ pages, │ tickets, │ uptime, │ traces │ │ │ │ deploys │ docs, │ FAQ, │ alerts on │ stack, │ │ │ │ via │ release │ drafts │ failures │ proposes │ │ │ │ Gitea + │ notes │ replies │ │ fixes │ │ │ │ Coolify │ │ │ │ │ │ │ └──────────┴───────────┴──────────┴────────────┴───────────┘ │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────┴────────────────────────────────────┐ │ Shared Infrastructure │ │ │ │ Gitea (git.vibnai.com) — code, docs, marketing content │ │ Coolify (coolify.vibnai.com) — deploys, hosting, logs │ │ Database (Postgres) — conversations, tasks, user data │ │ Object Storage — assets, screenshots, artifacts │ └─────────────────────────────────────────────────────────────────┘ │ ┌────────────────────────────┴────────────────────────────────────┐ │ User Workspaces (Cold Tier) │ │ │ │ Per-user Theia IDE containers │ │ - Hibernate when not in use (storage persists) │ │ - Wake in 2-5 seconds when user opens browser │ │ - Mount project workspace volume │ │ - Full code editor, terminal, AI chat │ │ - For manual vibe coding sessions │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Master Orchestrator The central AI brain for each project. Always running on shared infrastructure. ### What it knows - Full codebase (via Gitea API) - Deployment state (via Coolify API) - Task/ticket history (database) - Conversation history with the user across all channels - What each specialist agent is doing ### How it receives work 1. **User message** — from mobile app, browser, or Theia IDE chat 2. **Gitea webhook** — code pushed, PR opened, issue created 3. **Coolify webhook** — deploy completed, service crashed 4. **Scheduled checks** — cron-based monitoring, report generation 5. **Support ticket** — customer question routed in ### How it dispatches - Analyzes the event/message - Decides which specialist agent(s) should act - Dispatches to one or more agents simultaneously - Tracks completion, reports results back to user - Queues follow-up work if needed --- ## Specialist Agents ### Coder - **Trigger**: User request, Orchestrator dispatch - **Tools**: Gitea API (read/write code), Coolify API (deploy), shell execute - **Output**: Code commits, PRs, deployments - **Autonomy**: Can commit to feature branches, needs approval for main ### Marketing - **Trigger**: New feature deployed, Orchestrator dispatch - **Tools**: Gitea API (update marketing repo), content templates - **Output**: Updated landing pages, release notes, feature announcements - **Autonomy**: Drafts content, queues for user review ### Support - **Trigger**: Support ticket/question received, Orchestrator dispatch - **Tools**: Codebase search, docs search, conversation history - **Output**: Draft replies, FAQ updates, escalation to Coder if it's a bug - **Autonomy**: Can draft responses, user approves before sending ### Monitor - **Trigger**: Scheduled (every N minutes), Coolify webhook on failure - **Tools**: Coolify API (logs, status), health check endpoints - **Output**: Status reports, alerts, escalation to Debugger on failures - **Autonomy**: Fully autonomous — monitors and alerts without user input ### Debugger - **Trigger**: Monitor detects failure, user reports bug, error logs - **Tools**: Coolify logs, Gitea code search, stack trace analysis - **Output**: Root cause analysis, proposed fix, delegates to Coder if approved - **Autonomy**: Analyzes and proposes, needs approval to fix --- ## User Interfaces ### Mobile App (chat-first) - Simple chat interface to the Master Orchestrator - Push notifications for alerts, completed tasks, questions needing approval - Quick actions: approve deploy, review draft, check status - No code editing — just conversation and oversight ### Browser Dashboard (command center) - Chat with the Master Orchestrator - Dashboard panels: deploy status, agent activity, recent changes - Review queues: marketing drafts, support replies, code PRs - Project timeline and task tracking - No code editing — management and oversight ### Theia IDE (full workspace) - Full code editor, terminal, file tree - AI chat with Coder agent for hands-on vibe coding - Design panel for visual preview - For when the user wants to write code themselves - Connects to the same project workspace as the Orchestrator --- ## Communication Flow ### User chats from mobile ``` User (mobile): "How's the launch looking?" → API Gateway → Master Orchestrator → Orchestrator checks: Coder status, Marketing status, Monitor status → Response: "Code is deployed. Marketing page updated. 99.8% uptime last 24h. Two support tickets pending your review." ``` ### User assigns work from mobile ``` User (mobile): "Add a pricing page with three tiers" → Master Orchestrator dispatches: 1. Coder: build /pricing route with tier components 2. Marketing: draft copy for three pricing tiers → User closes app → Coder commits code, deploys to staging → Marketing drafts copy, queues for review → User gets push notification: "Pricing page ready for review" ``` ### Automated monitoring ``` Monitor agent (scheduled): checks Coolify every 5 min → Detects: API response time > 2s → Escalates to Debugger → Debugger: reads recent commits, checks logs → Debugger: "Memory leak in auth middleware introduced in commit abc123" → Orchestrator: notifies user via push notification → User (mobile): "Fix it" → Orchestrator → Coder: revert/fix the commit, deploy ``` --- ## Infrastructure ### Hot Tier (shared, always running) - 2-4 servers on Hetzner/Coolify - Runs Master Orchestrator + specialist agents for ALL projects - Stateless compute — reads/writes to Gitea and database - Scales horizontally with demand - Estimated cost: $60-200/mo for the first 1,000 projects ### Cold Tier (per-user, on-demand) - Theia IDE containers, one per user workspace - Hibernate after idle timeout - Wake on browser access - Storage persists (workspace volumes) - Estimated cost: $1-2/mo per user (mostly storage) ### Shared Services - **Gitea**: code, docs, marketing content (self-hosted on Coolify) - **Coolify**: container orchestration, deploys, logs - **Postgres**: conversations, tasks, user accounts, agent state - **Redis** (optional): task queue, real-time pub/sub for agent coordination --- ## Data Flow ``` All code/content → Gitea repos (source of truth) All deploys → Coolify (hosting + logs) All conversations → Postgres (history + context) All agent state → Postgres (what's running, what's queued) ``` Every specialist agent reads from and writes to these shared services. No agent has local state that would be lost on restart. The Master Orchestrator coordinates but doesn't store — it queries. --- ## Agent Tool Registry The agent runner uses a modular tool registry (`src/tools/`). Each domain file registers its tools on import — agents declare which subset they use. | Tool file | Tools | Used by | |-----------|-------|---------| | `file.ts` | file read/write/list | Orchestrator, Coder | | `shell.ts` | shell execute | Orchestrator, Coder | | `git.ts` | git operations | Orchestrator, Coder | | `gitea.ts` | Gitea API (repos, issues, PRs) | Orchestrator, Coder | | `coolify.ts` | Coolify API (deploy, logs, status) | Orchestrator, Monitor | | `agent.ts` | spawn sub-agents | Orchestrator | | `memory.ts` | knowledge base read/write | All agents | | `skills.ts` | reusable markdown skill lookup | All agents | | `prd.ts` | `finalize_prd` — save completed PRD | Atlas | | `search.ts` | `web_search` — internet search via Jina AI | Atlas | ### Web Search (`web_search` tool) Atlas has access to real-time web search via [Jina AI's search endpoint](https://s.jina.ai/) — completely free, no API key required. **How it works:** - Atlas calls `web_search` with a plain-language query - The tool fetches `https://s.jina.ai/` which returns clean markdown-formatted results - Results are truncated to ~6,000 characters to keep context window usage reasonable - Atlas uses this to ground discovery conversations in real-world context **What Atlas uses it for:** - Researching competitors and existing solutions - Understanding market pricing and business models - Looking up relevant technologies, frameworks, or integrations the user mentions - Validating assumptions ("is this a solved problem? what do incumbents miss?") **No configuration needed** — Jina AI's free tier requires no credentials. If stricter control or higher volume is needed in future, swap the endpoint for Tavily, Brave Search, or Google Custom Search by updating `src/tools/search.ts`. --- ## What to build (in order) ### Phase 1: Foundation - [ ] Move AI agents to Theia backend (server-side execution) - [ ] Master Orchestrator service with multi-agent dispatch - [ ] Postgres schema for conversations, tasks, agent state - [ ] API Gateway with auth and WebSocket support ### Phase 2: Agents - [ ] Coder agent (already exists — extract from Theia frontend) - [ ] Monitor agent (Coolify log watcher + health checks) - [ ] Marketing agent (content generation + Gitea commits) - [ ] Support agent (ticket intake + draft responses) - [ ] Debugger agent (log analysis + fix proposals) ### Phase 3: Interfaces - [ ] Browser dashboard (React app, chat + status panels) - [ ] Mobile app (React Native or Flutter, chat + push notifications) - [ ] Theia IDE integration (connect to Master Orchestrator) ### Phase 4: Scale - [ ] Workspace hibernation and wake-on-access - [ ] Multi-project support per user - [ ] Hot tier horizontal scaling - [ ] Usage-based billing