| # 🛠️ 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* |
|
|
