BuildOS Platform
AI-powered productivity platform. Users write stream-of-consciousness "brain dumps" and AI extracts projects, tasks, and context. Includes daily brief generation, calendar integration, ontology-driven project management, and an agentic chat system.
This is the unified monorepo for the web app, background worker, and shared packages.
Structure
buildos-platform/
├── apps/
│ ├── web/ # SvelteKit 2 + Svelte 5 web app (Vercel)
│ └── worker/ # Node.js background worker (Railway)
├── packages/
│ ├── shared-types/ # Generated DB types, queue types, API types
│ ├── shared-agent-ops/ # Agent op layer shared by web gateway + worker Agent Run runner
│ ├── shared-utils/ # Logging, metrics, shared utilities
│ ├── smart-llm/ # LLM abstraction (OpenRouter + fallbacks)
│ ├── supabase-client/ # Shared Supabase client configuration
│ ├── twilio-service/ # SMS / Twilio integration
│ ├── agentic-chat-runtime/ # Transport-neutral agentic chat contracts, loop + supervisor
│ └── buildos-mcp-server/ # Local stdio MCP bridge to the remote BuildOS connector
├── docs/ # Cross-cutting docs (architecture, marketing, ops)
├── scripts/ # Type generation, schema extraction, tooling
└── supabase/ # Migrations and local Supabase config
Tech Stack
- Monorepo: Turborepo 2.10 + pnpm 11 workspaces
- Web: SvelteKit 2 + Svelte 5 (runes) on Vercel (
nodejs22.x)
- Worker: Node.js + Express on Railway (
nodejs_22)
- TypeScript: TypeScript 5.9 for SvelteKit and package build tooling; native TypeScript 7 for
worker compilation and selected package typechecks
- Queue: Redis-free — Supabase-backed queue with PostgreSQL RPCs
- Database: Supabase (PostgreSQL + Row Level Security)
- LLMs: OpenRouter (primary) → OpenAI / Anthropic fallback; optional direct Moonshot for Kimi
- Auth: Supabase Auth + Google OAuth
- Billing: Stripe (optional, behind
PRIVATE_ENABLE_STRIPE)
- SMS: Twilio
Getting Started
Prerequisites
- Node.js 22.23.4+ within 22.x or 24.22.1+ within 24.x (
.nvmrc and CI use 22.23.4)
- pnpm >= 11 (the root package pins
[email protected])
- A Supabase project
- OpenRouter API key (or OpenAI/Anthropic as fallback)
The web package accepts both Node lines. Vercel selects the newest supported build
major in that range (24.x); the SvelteKit adapter keeps server functions on nodejs22.x.
Install & run
pnpm install
# Dev (all configured dev tasks via Turborepo)
pnpm dev
# Single app
pnpm dev --filter=@buildos/web # http://localhost:5173
pnpm dev --filter=@buildos/worker # http://localhost:3001
Environment
Copy .env.example to .env and fill in the required values. The full list lives in .env.example; the essentials are:
# Supabase
PUBLIC_SUPABASE_URL=
PUBLIC_SUPABASE_ANON_KEY=
PUBLIC_SUPABASE_PROJECT_ID=
PRIVATE_SUPABASE_SERVICE_KEY=
# LLMs (OpenRouter is primary; OpenAI is fallback)
PRIVATE_OPENROUTER_API_KEY=
PRIVATE_OPENAI_API_KEY=
# Google OAuth (Calendar)
PUBLIC_GOOGLE_CLIENT_ID=
PRIVATE_GOOGLE_CLIENT_SECRET=
# Web ↔ Worker
PUBLIC_RAILWAY_WORKER_URL=http://localhost:3001
PRIVATE_RAILWAY_WORKER_TOKEN=
# Stripe (optional)
PRIVATE_ENABLE_STRIPE=false
# PostHog analytics (optional — no-ops without a key)
PUBLIC_POSTHOG_KEY=
PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
Naming convention: PUBLIC_* for client-accessible, PRIVATE_* for server-only.
Common Commands
# Quality
pnpm typecheck # All configured packages
pnpm lint # All configured packages
pnpm lint:fix
pnpm format # Prettier
pnpm pre-push # typecheck + test + lint + build
# Tests
pnpm test:run # Full suite, no watch mode
pnpm test:run --filter=@buildos/web
pnpm test:run --filter=@buildos/worker
cd apps/web && pnpm test path/to/file.test.ts # Single file
cd apps/web && pnpm test:llm # LLM prompt tests (real API; costs money)
cd apps/worker && pnpm test:scheduler
# Build
pnpm build
pnpm build --filter=@buildos/web
pnpm build --filter=@buildos/worker
# Generation
pnpm gen:types # Regenerate Supabase types from local URL + service key
pnpm gen:schema # Extract DB schema
pnpm gen:all # Full regen: types + schema + web assets + typecheck
Always use pnpm. Never npm or yarn.
Deployment
- Web → Vercel. Config in
vercel.json, including ~10 cron jobs (billing/trial lifecycle, welcome/reactivation sequences, Gmail maintenance, webhook renewal, account deletions, retention cleanup — see vercel.json for the current list).
- Worker → Railway. Three services deploy from repository root
/ with
Railpack on patched Node 22: railway.toml (daily brief), railway.chat.toml
(Agentic Chat), railway.libri.toml (Libri). Healthcheck at /health.
See docs/architecture/diagrams/WEB-WORKER-ARCHITECTURE.md for the full topology.
Conventions (Quick Reference)
- Svelte 5 runes only —
$state, $derived, $effect. Never old reactive syntax.
- API responses — JSON endpoints must use
ApiResponse from $lib/utils/api-response. Protocol endpoints (SSE, file downloads, webhooks, tracking pixels) may return raw responses.
- Supabase access — API routes use
locals.supabase (user-scoped, RLS). Admin operations use createAdminSupabaseClient() from $lib/supabase/admin.
- Design system — Inkprint. All components support light + dark modes with
dark: prefix.
- Formatting — Tabs, single quotes, no trailing commas, 100-char print width. Configured in root Prettier.
Full guidelines in CLAUDE.md.
Documentation
Security
- Service role key is server-side only; never shipped to the browser.
- RLS enforced on all user-scoped tables.
- Stripe webhook signatures verified.
- Consumption billing guard blocks mutations for frozen accounts (402 response) in
hooks.server.ts.
Report issues to the maintainers privately — see docs/SECURITY.md.
