Skip to content

Architecture

System design and architectural decisions for the Microlearning Platform.

System Architecture

The platform is a modular single-layer architecture deployed as Supabase Edge Functions:

┌─────────────────────────────────────────────────────────────────────┐
│                      CLIENT APPLICATIONS                             │
│         (Web, Mobile - using OpenAPI-generated clients)             │
└────────────────────────┬────────────────────────────────────────────┘
                         │
                         ▼
               ┌───────────────────┐
               │   Supabase Edge   │
               │     Functions     │
               │                   │
               │   Deno + Hono     │
               │  Direct DB access │
               └─────────┬─────────┘
                         │
               ┌─────────▼─────────┐
               │    PostgreSQL     │
               │  (Supabase + RLS) │
               └───────────────────┘

Tech Stack: Deno · Hono · @hono/zod-openapi · Supabase Edge Functions · PostgreSQL + RLS

Guides

API Protection Architecture

The primary security reference. Covers:

  • User roles and permission design (Anonymous / Free / Pro / Premium / Admin)
  • Rate limiting architecture (multi-layer)
  • Paywall system and content tier access
  • Middleware architecture and request pipeline
  • Database schema design for access control
  • Stripe integration design
  • Security considerations and threat model

API Protection Guide

Implementation-level reference for:

  • Authentication middleware (requireAuth, optionalAuth, getAuthUserId)
  • Authorization patterns by endpoint category
  • Rate limiting implementation
  • Content paywall enforcement

API Lineage Validation

Validates that all navigation paths through the content hierarchy are implemented:

  • Domain → Trails → Concepts → Sparks (forward navigation)
  • Spark → Concept → Trail → Domain (reverse navigation)
  • Implementation status for all lineage endpoints

Hybrid Architecture Guide (Historical)

Note: This document describes a previous two-tier architecture (Domain APIs on Supabase Edge + Experience APIs on Vercel/Next.js). The platform has since consolidated to a single-layer architecture. Retained for historical context.

Domain Independence Proposal

Design proposal for service independence and bounded context separation.

Implementation Plan

Phased implementation roadmap for platform features.