PETAL is a multi-agent AI workspace for tasks, calendar, notes, and chat.
Built with FastAPI, React, Vite, Supabase, and Gemini.

---

Screenshots

---

Tech Stack

Layer	Technology	Badge
Frontend	React 18
	Vite
	TypeScript
Backend	FastAPI
	Python
	SQLAlchemy
Database	PostgreSQL
	Supabase
AI	Gemini 2.0 Flash
Cloud	Docker
	Google Cloud Run

---

What PETAL Does

PETAL routes natural language requests through a small team of specialized agents:

• Orchestrator — routes requests and manages context
• Task Agent — manages todo workflows
• Calendar Agent — handles event scheduling
• Info Agent — stores notes and knowledge

The frontend is a brutalist, high-contrast interface designed to feel like one coherent workspace instead of separate apps.

---

Architecture

flowchart TB
    subgraph Client["Frontend (React + Vite)"]
        UI["Brutalist UI"]
        SC["Supabase Client"]
        API["API Client"]
    end

    subgraph CloudRun["Cloud Run"]
        subgraph Backend["FastAPI Backend"]
            Auth["JWT Auth"]
            Router["Request Router"]
            
            subgraph Agents["Multi-Agent System"]
                Orch["Orchestrator Agent"]
                Task["Task Agent"]
                Calendar["Calendar Agent"]
                Info["Info Agent"]
            end
            
            DB["SQLAlchemy + asyncpg"]
        end
    end

    subgraph Supabase["Supabase"]
        PG["PostgreSQL"]
        AuthSupabase["Auth"]
    end

    subgraph Gemini["Google Gemini 2.0 Flash"]
        AI["AI Inference"]
    end

    UI --> API
    API --> CloudRun
    API --> SC
    SC --> Supabase
    
    CloudRun --> Auth
    Auth --> Router
    Router --> Orch
    Orch --> Task
    Orch --> Calendar
    Orch --> Info
    
    Task --> AI
    Calendar --> AI
    Info --> AI
    
    Orch --> DB
    DB --> PG
    PG --> AuthSupabase

Loading

---

App Flow

sequenceDiagram
    participant User
    participant UI as Frontend
    participant API as Backend
    participant Orch as Orchestrator
    participant Agent as Specialized Agents
    participant DB as Database
    participant AI as Gemini

    User->>UI: Natural language input
    UI->>API: POST /api/chat (bearer token)
    API->>Orch: Route to orchestrator
    Orch->>AI: Analyze intent + context
    AI-->>Orch: Intent + required agents

    alt Task intent
        Orch->>Agent: Invoke Task Agent
        Agent->>AI: Generate todos / update status
        AI-->>Agent: Structured response
        Agent->>DB: CRUD operations
    end

    alt Calendar intent
        Orch->>Agent: Invoke Calendar Agent
        Agent->>AI: Parse event details
        AI-->>Agent: Structured response
        Agent->>DB: Create / update event
    end

    alt Info intent
        Orch->>Agent: Invoke Info Agent
        Agent->>AI: Store / retrieve knowledge
        AI-->>Agent: Structured response
        Agent->>DB: Note operations
    end

    DB-->>Agent: Confirm operation
    Agent-->>UI: Structured response
    UI-->>User: Render updated UI

Loading

---

Local Setup

cp .env.example .env
pip install -r requirements.txt
cd frontend && npm install

Backend:

cd backend
python -m uvicorn main:app --reload --port 8080

Frontend:

cd frontend
npm run dev

---

Environment

Use .env.example as the source of truth. Do not commit real keys or secrets.

Required variables:

DATABASE_URL=
SUPABASE_URL=
SUPABASE_JWT_SECRET=
SUPABASE_ANON_KEY=
GEMINI_API_KEY=
JWT_SECRET=
ALLOWED_ORIGINS=
VITE_API_URL=
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=

---

Deployment

Backend deployment on Cloud Run:

./scripts/deploy-cloud-run.sh

Frontend build and deploy:

./scripts/deploy-frontend.sh

Production URLs:

• Frontend: https://petal-frontend-ycmhorzhoa-uc.a.run.app
• Backend: https://petal-api-ycmhorzhoa-uc.a.run.app

---

Security

Secrets are intentionally excluded from source control.

Ignored by default:

• .env, .env.local, .env.production
• frontend/.env, frontend/.env.local, frontend/.env.production
• config/keys/*.json
• infrastructure/terraform/*.tfvars
• Terraform state files
• Common private key formats

---

Repository Layout

backend/              FastAPI app, agents, routes, database
frontend/             React app, components, pages, styles
assets/               Logo and showcase images
infrastructure/       Terraform and migrations
scripts/              Deployment helpers

---

Notes

• The app is designed to run with bearer-token auth and Cloud Run-friendly CORS.
• Build-time frontend env vars are required for the deployed Supabase client.
• If you change deployment URLs, update the frontend build args and the backend CORS origin list together.