SPEC.md

🛠️ Aubm — Technical Specification

Target Stack: FastAPI (Python) + React/TypeScript (Vite) + Supabase (Postgres + Auth)

This document provides a comprehensive technical blueprint for recreating Aubm.

---

1. System Architecture

Aubm follows a decoupled architecture with a centralized database (Supabase) acting as the source of truth and coordination layer.

Directory Structure

aubm/
├── backend/                  # Python 3.10+
│   ├── main.py              # Application entrypoint & CRUD API
│   ├── worker.py            # Standalone task queue worker
│   ├── schema.sql           # Full DDL for Supabase
│   ├── agents/              # Provider-specific implementations
│   │   ├── base.py          # Abstract BaseAgent class
│   │   ├── agent_factory.py # Factory for creating agent instances
│   │   └── {provider}_agent.py
│   ├── routers/             # Functional endpoint grouping
│   │   ├── agent_runner.py  # Task execution logic
│   │   └── orchestrator.py  # Multi-task project flow
│   └── services/            # Core business logic
│       ├── config.py        # Configuration management
│       ├── task_queue.py    # Background processing loop
│       └── semantic_backprop.py # RAG context builder
├── frontend/                # React + Vite + TS
│   ├── src/
│   │   ├── components/      # UI Modular components
│   │   ├── services/        # API communication layer
│   │   ├── context/         # Auth & Global state
│   │   └── i18n/            # Multi-language support
│   └── vite.config.ts
└── database/                # Migrations & Seed data

---

2. Database Schema (Supabase/Postgres)

Core Tables

Table	Purpose	Key Columns
profiles	User extensions	id (uuid), role, full_name, avatar_url
projects	Project containers	id, name, description, context, owner_id, status
agents	AI Identities	id, name, role, api_provider, model, system_prompt
tasks	Units of work	id, project_id, assigned_agent_id, status, output_data
task_runs	Execution history	id, task_id, agent_id, status, error_message
agent_logs	Execution traces	id, task_id, action, content, metadata
app_config	Global settings	key, value (JSONB)

Status Enums

• Tasks: todo, in_progress, awaiting_approval, done, failed, cancelled.
• Task Runs: queued, running, completed, failed, cancelled.
• Profiles: user, manager, admin.

---

3. Backend Logic

Agent Execution Flow

1. Request: POST /tasks/{id}/run
2. Initialization: Fetch task, agent, and project data.
3. Context Building: semantic_backprop fetches outputs from previous tasks in the same project.
4. Agent Factory: Instantiates the correct BaseAgent subclass (e.g., GroqAgent).
5. Execution:
   • LLM call with dynamic prompt.
   • Real-time logging to agent_logs via SSE.
6. Guardrails:
   • output_cleaner: Strips markdown artifacts.
   • language_guard: Ensures output matches app_config["output_language"].
7. Persistence: Updates task.output_data and sets status to awaiting_approval.

Orchestration Engine

• Processes a project's task list as a Directed Acyclic Graph (DAG).
• Respects is_critical and priority fields.
• Auto-assigns available agents from the agents pool if no agent is pre-assigned.

Tool System (Phase 2)

• Tool Registry: A central registry where tools are defined and permissioned.
• Browser Tool: Uses Playwright for headless browsing and content extraction.
• Sandbox Tool: Executes code in a restricted environment.
• Integration: Tools are exposed to agents via the OpenAI function-calling/tool-calling schema.

---

4. Frontend Design System

• Styling: Vanilla CSS with modern variables (HSL colors, glassmorphism).
• Icons: Lucide React.
• State Management: React Context + Hooks.
• Features:
  • Kanban Board for task management.
  • Real-time streaming console for agent thoughts.
  • Interactive Project Wizard for quick setup.
  • Analytics dashboard for project performance.

---

5. Deployment Guide

Vercel Integration

The project is designed to run seamlessly on Vercel:

• Frontend: Standard Vite build.
• Backend: Python Serverless Functions.
• Database: External Supabase instance.

Local Setup

1. DB: Apply schema.sql to Supabase.
2. Backend: pip install -r requirements.txt & uvicorn main:app.
3. Frontend: npm install & npm run dev.

---

6. Key Dependencies

Backend

• fastapi, supabase, openai, groq, google-genai, playwright, folium.

Frontend

• react, lucide-react, framer-motion (for animations), i18next.

---

7. Security (RLS)

• Projects: Only visible to owner or if is_public=true.
• Config: Only writable by users with role='admin'.
• Agents: Writable by manager or admin.
• Tasks: Protected by project-level RLS.

---

End of Specification