Architecture

Supascale is built as a modern, self-contained application designed for reliability and ease of deployment.

Technology Stack

Application Architecture

┌─────────────────────────────────────────────────────────────┐
│                       Supascale                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │   Web UI        │  │   REST API      │                   │
│  │   (React)       │  │   (/api/v1)     │                   │
│  └────────┬────────┘  └────────┬────────┘                   │
│           │                    │                             │
│  ┌────────┴────────────────────┴────────┐                   │
│  │         Next.js Server               │                   │
│  │         (Node.js Runtime)            │                   │
│  └────────┬─────────────────────────────┘                   │
│           │                                                  │
│  ┌────────┴────────┐  ┌─────────────────┐                   │
│  │   SQLite DB     │  │   PM2 Manager   │                   │
│  │   (Data Store)  │  │   (Process Mgmt)│                   │
│  └─────────────────┘  └─────────────────┘                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘
                          │
                          │ Docker API
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Docker Engine                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Project A  │  │  Project B  │  │  Project C  │         │
│  │  Containers │  │  Containers │  │  Containers │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Key Components

Web Application (Next.js)

The main application runs as a standalone Next.js server:

• Server-side rendering for fast initial loads
• API routes for REST API endpoints
• React components for interactive UI
• TypeScript for type safety

SQLite Database

An embedded SQLite database stores all application data:

• WAL mode enabled for concurrent access
• Encrypted credentials for sensitive data
• Automatic migrations on startup
• No external database required

Tables include:

• users - Admin accounts
• projects - Supabase project configurations
• cloud_storage_providers - Storage credentials
• tasks - Scheduled tasks
• activity_log - Audit trail
• backups - Backup records
• api_keys - API key management

PM2 Process Manager

Supascale runs under PM2 for production reliability:

• Auto-restart on crashes
• Memory limits to prevent runaway processes
• Log management with rotation
• Startup scripts for system boot

Docker Integration

Each Supabase project runs as Docker containers:

• Docker Compose orchestrates service containers
• Named volumes for persistent data
• Custom networks for isolation
• Dynamic port allocation

Directory Structure

Supascale uses a unified data folder structure for easy backup and restore.

Installation Directory

/opt/supascale-web/              # Installation directory
├── data/                        # USER DATA - backup this folder!
│   ├── supascale.db            # SQLite database
│   ├── supascale.db-shm        # SQLite shared memory
│   ├── supascale.db-wal        # SQLite write-ahead log
│   ├── .env.local              # Environment configuration
│   └── .update-state.json      # Update tracking
├── .build/
│   └── standalone/             # Compiled application
│       ├── server.js           # Entry point
│       ├── .next/              # Compiled Next.js
│       ├── node_modules/       # Dependencies
│       └── .env.local          # Symlink → ../../data/.env.local
├── ecosystem.config.js          # PM2 configuration
├── .update-status.json          # Update progress (UI polling)
└── update.log                   # Update logs

To backup your Supascale installation, simply copy the data/ folder:

cp -r /opt/supascale-web/data /path/to/backup/

This contains your database, environment config, and all settings.

Project Directories

~/projects/                      # Default project directory
├── project-a/
│   └── supabase/
│       └── docker/
│           ├── docker-compose.yml
│           ├── volumes/        # Persistent data
│           └── .env            # Project environment
└── project-b/
    └── supabase/
        └── docker/
            ├── docker-compose.yml
            ├── volumes/
            └── .env

Backup Directory

~/.supascale_backups/            # Default backup directory
├── project-a/
│   └── 2026-01-19-full.tar.gz
└── project-b/
    └── 2026-01-19-db.sql

Security Architecture

Authentication Flow

1. User submits credentials
2. Password verified against bcrypt hash
3. JWT session token issued
4. Token validated on each request

Credential Protection

• bcrypt for password hashing (12 rounds)
• AES encryption for stored credentials
• Environment variables for secrets
• Secure cookies for sessions

API Security

• Session authentication for web UI
• API key authentication for programmatic access
• Granular permissions per resource
• Rate limiting (future)

Deployment Models

Single Server

Most common deployment:

• Supascale and all projects on one server
• Simple setup and management
• Suitable for small to medium workloads

Dedicated Project Servers

For larger deployments:

• Supascale on management server
• Projects distributed across multiple servers
• Requires SSH-based remote management (future)

System Requirements

Minimum

• Node.js 18+
• Docker 20.10+
• 2GB RAM
• 20GB disk space

Recommended

• Node.js 20+
• Docker 24+
• 4GB+ RAM
• 50GB+ disk space
• SSD storage