madbase/ROADMAP.md

MadBase Development Roadmap

This document outlines the development plan for MadBase, a high-performance, resource-efficient, Supabase-compatible API layer written in Rust. The roadmap is derived from the requirements specified in SPECIFICATIONS.md.

Phase 1: Foundation & Core APIs (MVP)

Goal: Establish the single-binary architecture and deliver functional Auth and Data APIs for a single project context.

1.1 Project Scaffolding & Architecture

• Initialize Rust workspace with modular crate structure (gateway, auth, data_api, common, control_plane).
• Implement configuration management (Environment variables + .env).
• Set up basic HTTP server (Axum/Actix) acting as the Gateway.
• Implement connection pooling for PostgreSQL (SQLx or similar).
• Create docker-compose.yml for dev database (compatible with Podman).

1.2 Authentication Service (/auth/v1)

• Implement User model & schema (compatible with GoTrue/Supabase).
• Sign Up: Email/password registration with Argon2 hashing.
• Sign In: Email/password login returning JWTs.
• Token Management:
  • Issue Access Tokens (JWT) with required claims (sub, role, iss, iat, exp) and optional (aud, email).
  • Issue Refresh Tokens and implement rotation logic.
• Session: /user endpoint to retrieve current session.

1.3 Data API (PostgREST-lite) (/rest/v1)

• Query Parser: Parse URL parameters for filtering, ordering, and pagination.
  • Filters: eq, neq, lt, gt, in, is.
  • Ordering: order=col.asc|desc.
  • Pagination: limit, offset.
• CRUD Operations:
  • GET: Select rows (basic select=*).
  • POST: Insert rows.
  • PATCH: Update rows.
  • DELETE: Delete rows.
• RPC: POST /rpc/<function> support for calling Postgres functions.
• RLS Enforcement:
  • Implement transaction wrapping.
  • Inject claims via SET LOCAL request.jwt.claims.
  • Switch roles (anon vs authenticated vs service_role).

1.9 Podman Compose Deployment

Single docker-compose.yml (compatible with podman-compose) deploys:

• PostgreSQL: Database for Auth and Data storage.
• MinIO: Object storage for file uploads.
• Control Plane DB: Stores project-specific config and secrets.

---

Phase 2: Realtime & Storage

Goal: Enable real-time data subscriptions and object storage capabilities.

2.1 Realtime Service (/realtime/v1)

• WebSocket Server: Implement using axum + tungstenite.
• Replication Consumer:
  • Connect to Postgres via LISTEN/NOTIFY (fallback path).
  • Connect to Postgres replication slot (pgoutput) via tokio-postgres or sqlx (Defer to Phase 5: Advanced Realtime).
  • Broadcast row changes (INSERT/UPDATE/DELETE) to connected clients.
• Subscription Management:
  • Handle Join messages to subscribe to specific tables/rows.
  • Filter events based on client subscriptions.

2.2 Storage Service (/storage/v1)

• S3 Proxy:
  • List Buckets (GET /bucket).
  • List Objects (GET /object/:bucket_id).
  • Upload/Download (POST/GET /object/:bucket_id/:filename).
• Permissions:
  • RLS-like policies for buckets/objects (storage.buckets, storage.objects tables).
  • Public vs Private buckets.

Phase 3: Control Plane & Management

Goal: Build the administrative layer to manage projects and configurations.

3.1 Project Management (/v1/projects)

• Projects Table: Store project metadata (name, owner, status).
• Provisioning: (Mocked for MVP) Simulate creating resources for a new project.
• API Keys: Generate and validate Service Keys (anon/service_role).

3.2 Secrets Management (/v1/secrets)

• JWT Generation: Automatically generate secure JWT secrets and keys for new projects.

• Project Resolution:

  • Resolve project context via x-project-ref header.

• Dynamic Configuration:

  • Load project-specific config (DB URL, JWT secret, API keys) from Control Plane DB.

• Isolation: Ensure strict separation of connections and caches between projects.

---

Phase 4: Admin UI & Observability

Goal: Provide a management interface and production-grade monitoring.

4.1 Admin API (/admin/v1)

• Project Management: Create, Update, Soft-delete projects.
• User Management: Admin-level user CRUD.
• Config Management: Key rotation and setting updates.

4.2 Management UI

• Dashboard: React/Web-based UI for managing projects.
• Features:
  • DB Connection tester.
  • Storage bucket browser (Basic).
  • Realtime connection stats (Basic).
  • Logs viewer (Basic).

4.3 Observability Stack

• Metrics: Expose Prometheus-compatible metrics (Request latency, DB pool stats, Active WS connections).
• Logs: Structured JSON logging with correlation IDs.
• Infrastructure:
  • Configure VictoriaMetrics for metric storage.
  • Configure Loki for log aggregation.
  • Configure Grafana with pre-built dashboards.
• Docker Compose: Finalize the all-in-one docker-compose.yml.

---

Phase 5: Polish, Security & Extensions

Goal: Harden the system for production use and expand compatibility.

5.1 Advanced Features

• Auth: OAuth provider integration (Google, GitHub, etc.).
• Data API:
  • Basic column selection (?select=col1,col2).
  • Nested selects (joins) (?select=col,relation(col)).
  • Complex boolean logic (or, and).
  • Bulk operations optimization (Bulk Insert).
• Realtime: Resume from LSN/ID support for reliability (via History Table).

5.2 Security & Performance

• Hardening:
  • Rate limiting (per IP/Project).
  • CORS configuration.
  • Input validation strictness.
• Performance:
  • Query caching where appropriate.
  • WS fanout optimization.
• Testing:
  • Integration tests using the official @supabase/supabase-js client.
  • Load testing.

---

Milestone Summary

1. MVP: Auth + Data API (Phase 1).
2. Beta: + Realtime + Storage (Phase 2).
3. RC: + Functions + Multi-tenancy (Phase 3).
4. v1.0: + Admin UI + Observability + Production Ready (Phase 4 & 5).