Architecture

Technical architecture of Supascale.

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

Technology Stack

Layer	Technology
Frontend	Next.js 15 + React 19
Styling	Tailwind CSS + Shadcn UI
Backend	Next.js API Routes (Node.js)
Database	SQLite with WAL mode
Authentication	NextAuth.js v5
Process Manager	PM2
Container Management	Docker + Docker Compose

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

/opt/supascale-web/              # Installation directory
├── .build/standalone/           # Compiled application
├── data/                        # SQLite database
├── .env.local                   # Environment configuration
└── ecosystem.config.js          # PM2 configuration

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

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

Security Architecture

Authentication Flow

User submits credentials
Password verified against bcrypt hash
JWT session token issued
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