# Technical Overview of Supamode

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

*Canonical: https://makerkit.dev/docs/supamode/installation/technical-details*

---

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:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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

```
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

```
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

### Recommended Setup

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  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.