350 lines
17 KiB
Markdown
350 lines
17 KiB
Markdown
# 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/<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`.
|
|
|
|
---
|
|
|
|
## Product Lifecycle (Current Design)
|
|
|
|
### Correct sequence — not yet fully implemented
|
|
|
|
```
|
|
1. Create project (name only — no scaffold yet)
|
|
↓
|
|
2. Atlas discovery conversation
|
|
- Understands the product concept
|
|
- Determines product type (SaaS / Marketplace / E-commerce / AI / Website / Mobile)
|
|
- Determines required surfaces (Web App, Marketing Site, Admin, Mobile, Email, Docs)
|
|
- Determines design package per surface
|
|
- Generates PRD with all of the above as structured data
|
|
↓
|
|
3. Architect agent
|
|
- Reads PRD (product type, surfaces, design choices)
|
|
- Designs technical solution and data model
|
|
- Generates Gitea repo scaffold tailored to the specific surfaces needed
|
|
- NOT a generic Turborepo template — apps/ reflects exactly what was decided
|
|
↓
|
|
4. Builder / Orchestrator
|
|
- Reads PRD + architecture
|
|
- Builds the product surface by surface
|
|
↓
|
|
5. Active (Theia IDE + Orchestrator for ongoing work)
|
|
```
|
|
|
|
### What is built today (and needs to change)
|
|
|
|
| Step | Current behaviour | Correct behaviour |
|
|
|------|------------------|-------------------|
|
|
| Project creation | Creates Gitea repo + generic Turborepo scaffold immediately | Create project record only — no repo yet |
|
|
| Atlas | Saves PRD markdown + sets stage to `architecture` | Also saves `productType` and `surfaces[]` as structured fields |
|
|
| Design page | Shows Turborepo `apps/` from Gitea | Reads `surfaces[]` from PRD, shows theme picker per surface |
|
|
| Architect | Not built yet | Reads PRD + surfaces, generates tailored Gitea scaffold |
|
|
|
|
### Design surfaces and recommended libraries
|
|
|
|
| Surface | When needed | Library options |
|
|
|---------|-------------|----------------|
|
|
| **Web App** | SaaS, Marketplace, AI Product | shadcn/ui, Mantine, HeroUI, Tremor |
|
|
| **Marketing Site** | Almost every product | DaisyUI, HeroUI, Aceternity UI, Tailwind only |
|
|
| **Admin / Internal** | SaaS, Marketplace, E-commerce | Mantine, shadcn/ui, Tremor |
|
|
| **Mobile App** | Mobile-first products | NativeWind, Gluestack, RN Paper |
|
|
| **Email** | SaaS, E-commerce, Marketplace | React Email + Resend |
|
|
| **Docs / Content** | Developer tools, complex products | Nextra, Starlight, Docusaurus |
|
|
|
|
---
|
|
|
|
## 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
|