BUILD.md

Platform - Build & Test Guide

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Platform Platform                     │
│                                                         │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────┐ │
│  │   React UI  │◄──►│  FastAPI     │◄──►│  SQLite    │ │
│  │  (Vite)     │    │  Backend     │    │  Database  │ │
│  └─────────────┘    └──────┬───────┘    └────────────┘ │
│                            │                            │
│                            ▼                            │
│              ┌─────────────────────────┐                │
│              │    Composio API         │                │
│              │  backend.composio.dev   │                │
│              │  /api/v3.1/toolkits     │                │
│              │  /api/v3.1/tools        │                │
│              └─────────────────────────┘                │
│                            │                            │
│                            ▼                            │
│              ┌─────────────────────────┐                │
│              │    Local Cache          │                │
│              │  SQLite + JSON backup   │                │
│              │  (/data/)               │                │
│              └─────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

Local DB System

The platform uses a dual-layer caching system:

1. SQLite Database (/data/platform.db) - Primary store for integrations and tools
2. JSON Backup (/data/composio_cache.json) - Raw Composio API response backup

How it works:

1. Startup: Tries to fetch from Composio API
2. If API succeeds: Saves to SQLite + JSON backup
3. If API fails: Loads from JSON backup → seeds SQLite
4. If no cache: Uses minimal fallback definitions (5 integrations)

Cache TTL: 24 hours (configurable via CACHE_TTL)

Tool Calls Quota

Good news: Fetching tools via GET /api/v3.1/toolkits and GET /api/v3.1/tools does NOT consume your 20,000 free tool calls. Only POST /api/v3.1/tools/execute/{slug} counts as a tool call.

Build & Run

Option 1: Docker (Recommended for HF Spaces)

cd /home/runner/workspace/platform

# Set your Composio API key
export COMPOSIO_API_KEY=sk_your_key_here

# Build
docker build -t platform .

# Run
docker run -p 7860:7860 \
  -v $(pwd)/data:/data \
  -e COMPOSIO_API_KEY=$COMPOSIO_API_KEY \
  platform

Option 2: Direct (Development)

cd /home/runner/workspace/platform

# Build frontend
cd frontend && npm install && npm run build && cd ..

# Install backend deps
cd backend && pip install -r requirements.txt && cd ..

# Set env vars
export COMPOSIO_API_KEY=sk_your_key_here
export DATA_DIR=$(pwd)/data

# Initialize and run
python -c "from backend.database import init_db; init_db()"
python backend/integrations/registry.py  # Syncs tools
cd backend && uvicorn main:app --reload --port 7860

Test

# After starting the server:
cd /home/runner/workspace/platform
chmod +x test.sh
./test.sh

Hugging Face Spaces Deployment

1. Create a new Docker Space on HF
2. Push these files to the repo:

   Dockerfile
   entrypoint.sh
   backend/
   frontend/
   .env.example
   

3. Add COMPOSIO_API_KEY as a Space secret
4. The Space will auto-build and start on port 7860

API Endpoints

Method	Path	Description
GET	/health	Health check
GET	/api/docs	Swagger UI
POST	/api/auth/register	Register user
POST	/api/auth/login	Login
GET	/api/apps	List integrations
POST	/api/apps/sync	Sync from Composio API
GET	/api/tools	List tools
POST	/api/tools/{id}/execute	Execute tool
POST	/api/tools/sync	Sync tools from Composio
GET	/api/connections	List connections
GET	/api/apikeys	List API keys
GET	/api/analytics/overview	Usage stats
GET	/mcp/v1/discovery	MCP discovery
GET	/mcp/v1/tools	MCP tools list

Environment Variables

Variable	Required	Default	Description
COMPOSIO_API_KEY	No	-	Composio API key for dynamic sync
COMPOSIO_API_BASE	No	https://backend.composio.dev/api/v3.1	Composio API base URL
SECRET_KEY	No	(default)	JWT signing key
DATA_DIR	No	/data	Data directory
CACHE_TTL	No	86400	Cache TTL in seconds (24h)