Spine Framework

A complete enterprise application platform built on Supabase + Netlify + React for building scalable multi-tenant SaaS applications with an extensible app ecosystem.

Quick Start

Prerequisites

• Node.js 18+
• A Supabase project
• A Netlify account

1. Install and scaffold

mkdir my-app && cd my-app
npm install spine-framework@latest
npx spine-framework init

This scaffolds the full project structure, copies all framework files, and writes a .env template.

2. Configure your environment

Edit .env with your Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_DB_PASSWORD=your-database-password

Get these from your Supabase dashboard.
SUPABASE_DB_PASSWORD is under Settings → Database.

3. Apply database migrations

npx spine-framework migrate

This creates all tables, RLS policies, functions, and seeds system data. Safe to re-run on an existing project — migrations are idempotent.

4. Start the development server

npm install && npm run assemble && netlify dev

Your app is now running at http://localhost:8888.

CLI Reference

All commands run via npx spine-framework <command>.

| Command | Description | |---------|-------------| | init | Scaffold a new project in the current directory | | migrate | Apply framework SQL migrations to your Supabase project | | migrate --dry-run | Preview pending migrations without applying | | migrate --db-password <pw> | Pass DB password directly instead of reading from .env | | status | Show installed apps and framework version |

Project Structure

After init, your project looks like this:

my-app/
├── .env                        # Your credentials (never commit this)
├── .framework/                 # Framework core (do not edit)
│   ├── cli/                    # CLI commands
│   ├── functions/              # Serverless API functions
│   ├── migrations/             # SQL migrations
│   ├── src/                    # React frontend core
│   └── scripts/                # Build scripts
├── custom/                     # Your custom apps and extensions
│   └── apps/                   # App packages go here
├── config/                     # Vite, TypeScript, Tailwind config
├── scripts/                    # Project-level build scripts
├── netlify.toml                # Netlify configuration
└── package.json

Architecture

• Multi-tenant: Account hierarchy with inherited access and RLS-enforced isolation
• Role-based access control: Fine-grained permissions via database-enforced policies
• App ecosystem: Install, manage, and build custom applications on the framework
• Serverless API: Netlify Functions handle all backend logic
• Real-time: Supabase Realtime for live updates
• AI integration: Native support for AI agents and pipeline automation

Database Schema

| Table group | Tables | |-------------|--------| | Identity | accounts, people, roles | | Runtime | items, threads, messages, links, attachments, watchers | | Apps | apps, types, pipelines, triggers | | AI | ai_agents, embeddings, prompt_configs | | System | api_keys, logs, integrations, timers |

Building Custom Apps

Create your own applications and place them in custom/apps/:

// custom/apps/my-app/index.tsx
export default function MyApp() {
  return <div>Hello from My App</div>
}

Add custom database migrations in custom/migrations/:

-- custom/migrations/001_my_app.sql
CREATE TABLE IF NOT EXISTS my_app_records (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id uuid NOT NULL REFERENCES public.accounts(id),
  title text NOT NULL,
  created_at timestamptz DEFAULT now()
);

ALTER TABLE my_app_records ENABLE ROW LEVEL SECURITY;

Custom migrations are picked up automatically by npx spine-framework migrate.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | Yes | Your Supabase project URL | | SUPABASE_ANON_KEY | Yes | Supabase anon/public key | | SUPABASE_SERVICE_ROLE_KEY | Yes | Supabase service role key (server-side only) | | SUPABASE_DB_PASSWORD | Yes (migrate) | Postgres database password |

Deployment

# Build and deploy to Netlify
npm run assemble
netlify deploy --prod

Contributing

git clone https://github.com/spine-framework/spine-framework.git
cd spine-framework
npm install
npm run dev

See docs/ARCHITECTURE.md for internals and docs/APPS.md for the app development guide.

License

Licensed under the Spine Framework Internal Use License.

• Free for internal business use
• Commercial redistribution requires a separate license
• Contact spine-framework.com for commercial licensing

Support

• Documentation: docs.spine-framework.com
• Issues: GitHub Issues
• Commercial: spine-framework.com