Documentation

Developer Overview

How apps run on Sangra — the configuration-driven architecture, AI gateway, and developer opportunity.

Contents

Platform Overview Configuration-Driven Architecture AI Gateway Shared Packages Database Schema Deployment

Platform Overview

Sangra is a monorepo-based AI App Operating System. All apps share a single Next.js backend, Supabase database, and AI gateway. Each app is distinguished by its database record and app_config — not by its own infrastructure.

The platform runs on Railway and auto-deploys on every push to the main branch of the GitHub repository.

Configuration-Driven Architecture

Every app on Sangra is defined by two database records: one in the apps table and one in the app_config table.

The apps table stores the app name, slug, status, and metadata. The app_config table stores the AI prompts, model preferences, temperature, max tokens, and response format for each call type.

Changing an app's behavior — its prompts, model, or response format — requires only a database update. No code deployment needed.

-- Example: apps table
{
  name: "DailyManager.ai",
  slug: "dailymanager",
  status: "active",
  description: "AI-powered daily management"
}

-- Example: app_config table
{
  app_id: "<uuid>",
  call_type: "daily_report",
  system_prompt: "You are a project management AI...",
  user_prompt_template: "Generate a daily report for: {{context}}",
  model: "gpt-4o",
  temperature: 0.7,
  max_tokens: 1500
}

AI Gateway

The AI gateway is a shared service that handles all OpenAI API calls across every app on the platform. Developers do not call OpenAI directly — they call the gateway.

The gateway loads the app configuration from Supabase, injects the system and user prompts, selects the correct model, and returns a structured response including the content, model used, token count, and estimated cost.

All gateway calls are automatically logged to the ai_logs table for billing and analytics.

// Calling the AI gateway
POST /api/ai
{
  "appSlug": "dailymanager",
  "userId": "<user-uuid>",
  "callType": "daily_report",
  "context": {
    "projects": [...],
    "tasks": [...]
  }
}

// Response
{
  "content": "Here is your daily report...",
  "model": "gpt-4o",
  "tokens": 847,
  "cost": 0.0254
}

Shared Packages

The monorepo includes four shared packages that all apps can import.

@sangra/core-db

Prisma ORM client connected to Supabase. Exports the Prisma client and all database types.

@sangra/core-config

Zod-based environment variable validation. Validates all required env vars on startup.

@sangra/core-ai

AI gateway client. Handles model routing, prompt injection, and response normalization.

@sangra/core-auth

Authentication utilities. JWT validation, session management, user context helpers.

Database Schema

The shared Supabase database has 8 tables. Row-level security is enabled on all tables — each app only sees its own data.

apps

App registry. One record per app on the platform.

app_config

AI configuration per app. Prompts, models, temperature, response format.

users

Platform users. Linked to one or more apps via app_id.

developers

Developer accounts. Linked to apps they own.

projects

User projects within an app.

tasks

Tasks within projects. The primary data model for DailyManager.ai.

ai_logs

Every AI gateway call logged. model, tokens, cost, latency.

usage_logs

Per-user usage events for billing and analytics.

Deployment

Railway hosts the entire platform. Auto-deploys fire on every push to the main branch. No CI/CD configuration needed.

Environment variables are managed through Railway Shared Variables. The following 8 variables are required: OPENAI_API_KEY, ANTHROPIC_API_KEY, SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, DATABASE_URL, NODE_ENV, NEXT_PUBLIC_APP_URL.