14 KiB
14 KiB
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
- User message — from mobile app, browser, or Theia IDE chat
- Gitea webhook — code pushed, PR opened, issue created
- Coolify webhook — deploy completed, service crashed
- Scheduled checks — cron-based monitoring, report generation
- 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 — completely free, no API key required.
How it works:
- Atlas calls
web_searchwith a plain-language query - The tool fetches
https://s.jina.ai/<query>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