Technical Overview of Supamode

A detailed look at the technical details of Supamode. Learn how the application is built and how it works.

Supamode is a comprehensive admin dashboard for Supabase projects, making it easy for non-developers to manage the database's data. This document explains the high-level architecture to help you understand how Supamode works and deploy it with confidence.

Overview

Supamode consists of three main components:

  1. React Frontend (Vite + TypeScript) - The admin dashboard interface
  2. Hono.js Backend API - Type-safe API server with RPC capabilities
  3. Supabase Schema - PostgreSQL with custom schema supamode for metadata and permissions

Architecture Diagram

Below is a high-level architecture diagram of Supamode:

text
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React App     │    │   Hono.js API   │    │   Supabase DB   │
│   (Frontend)    │◄──►│   (Backend)     │◄──►│   PostgreSQL    │
│                 │    │                 │    │                 │
│ • Vite Build    │    │ • Type-safe RPC │    │ • Your Data     │
│ • React Router  │    │ • Drizzle ORM   │    │ • Supamode      │
│ • TanStack Query│    │ • Auth Handling │    │   Schema        │
└─────────────────┘    └─────────────────┘    └─────────────────┘

How Supamode Indexes Your Tables

The Supamode Schema

Supamode creates a dedicated supamode schema in your PostgreSQL database that contains metadata about your existing tables and columns. This schema includes:

  • Table Metadata: Information about which tables are visible in the admin panel
  • Column Metadata: Field types, display names, and visibility settings
  • Permissions: Role-based access control for tables and operations
  • Audit Logs: Track all changes made through the admin interface
  • User Accounts: Link Supabase Auth users to admin roles

Dynamic Table Discovery

When you deploy Supamode:

  1. Schema Introspection: The system automatically discovers all tables and columns in your database using PostgreSQL's information schema
  2. Metadata Storage: Table and column information is stored in supamode.table_metadata and supamode.column_metadata tables
  3. Permission Mapping: Each table gets default permissions that can be customized per role
  4. Syncing: Schema changes can be synced to the admin interface with a simple button click.

Your Data Remains Untouched

  • Supamode never modifies your existing schemas or data
  • All metadata is stored separately in the supamode schema
  • Your application continues to work exactly as before
  • Supamode only adds read/write capabilities through the admin interface

Frontend Architecture

React Application (Vite)

The frontend is a modern React application built with:

  • Vite: Fast build tool and development server
  • React Router 7: File-based routing with data loaders
  • TypeScript: Full type safety across the application
  • Tailwind CSS v4: Utility-first styling
  • Shadcn/ui: Consistent component library for the admin interface

Data Flow

text
User Interaction → React Component → TanStack Query → Hono RPC → Database
                                  ↑
                            Type-safe API calls
  1. User Actions: Users interact with forms, tables, and buttons
  2. React Components: Handle UI state and user interactions
  3. TanStack Query: Manages server state, caching, and data fetching
  4. Type-safe RPC: Calls backend APIs with full TypeScript inference

Backend Architecture

Hono.js API Server

The backend uses Hono.js, a fast web framework that provides:

  • Type-safe RPC: Client and server share the same TypeScript types
  • Minimal Overhead: Lightweight and performant
  • Edge-ready: Can deploy to various platforms (Node.js, Cloudflare Workers, etc.)

Service Layer Pattern

text
API Route → Service Class → Drizzle ORM → PostgreSQL
  1. API Routes: Handle HTTP requests and validation
  2. Service Classes: Contain business logic and data operations
  3. Drizzle ORM: Type-safe database queries and migrations
  4. PostgreSQL: Your Supabase database with Row Level Security

Authentication & Security

  • Supabase Auth: Uses your existing Supabase authentication
  • JWT Validation: All API calls validate Supabase JWT tokens
  • Row Level Security: Database-level permissions protect your data
  • Role-based Access: Granular permissions for different user types

Database Security Architecture

Supamode uses RLS to protect your data. It's a powerful feature that allows you to control access to your data based on the user's role.

Permission System

  • Hierarchical Roles: Admin, Manager, Editor, Viewer with different capabilities
  • Table-level Permissions: Control access to specific tables
  • Column-level Permissions: Hide sensitive fields from certain roles
  • Operation Permissions: Separate read, write, delete permissions

Audit logs

Every action is logged:

  • Who performed the action
  • What data was changed
  • When the change occurred
  • IP address and user agent
  • Before/after values for updates

Deployment Architecture

text
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Vercel/Railway │    │  Vercel/Railway │    │   Supabase      │
│   Frontend      │    │   Backend API   │    │   Database      │
│                 │    │                 │    │                 │
│ • Static Assets │    │ • Hono Server   │    │ • Supabase      │
│ • React App     │    │ • Environment   │    │ • Auth          │
│ • Edge Caching  │    │   Variables     │    │ • Storage       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Vercel/Railway are fully supported, but you can deploy to any platform that supports Javascript/Docker applications, such as AWS, Fly.io, Digital Ocean, Cloudflare, etc.

Security & Compliance

Data Protection

  • No Data Export: Supamode doesn't store or export your data, it's all in your database.
  • Audit Logging: Complete trail of all administrative actions
  • Role Separation: Principle of least privilege enforced

Benefits of This Architecture

  1. Non-intrusive: Doesn't modify your existing database schema
  2. Secure: Multiple layers of security and access control
  3. Scalable: Each component can scale independently
  4. Type-safe: Full TypeScript coverage prevents runtime errors
  5. Auditable: Complete trail of all administrative actions
  6. Flexible: Customizable permissions and user interface
  7. Maintainable: Clean separation of concerns and modern tooling
  8. Tests: Large test suite to ensure reliability, both with Playwright and PgTap.