Microlearning Platform — Documentation¶

Technical reference for the Microlearning Platform API built with Deno + Hono + Supabase Edge Functions.

New to the project? Start with Local Development and Testing — it covers environment setup, running services, seeding data, and executing the full test suite from scratch.

Getting Started¶

Local setup, development workflows, and API usage patterns.

Document	Description
Local Development and Testing	Start here. Complete guide: local environment, edge functions, seeding, and running the test suite
Developer Guide	Core concepts, content model, knowledge graph, and integration patterns
Usage Guide	API usage patterns and request/response examples

Quick Start:

# 1. Start Supabase locally
deno task local:start

# 2. Serve edge functions with hot reload
supabase functions serve

# 3. Seed curriculum data
deno task content:seed

# 4. Verify with a request
curl http://127.0.0.1:54321/functions/v1/graph/domains

API Reference¶

Endpoint specifications organized by Edge Function. Each function serves a distinct area of the API.

Document	Function	Auth	Description
Graph API	`graph`	Optional	Knowledge graph, learning paths, breadcrumbs
Discovery API	`graph`	Optional	Faceted browsing across all resource types
Domains API	`graph`	Optional	Domain CRUD and listing
Content API	`content`	Optional	Lesson content delivery and versioning
Search API	`search`	Required	Full-text search and autocomplete
Journeys API	`journeys` / `journey-catalog`	Optional	Trail progress, graph navigation, catalog
User API	`user`	Required	Profile, journeys, events, milestones
Snapshots API	`snapshots`	Required	Content versioning and publishing
Metadata API	`metadata`	Public	Enumeration values (difficulties, types, etc.)

API Index: docs/api/README.md — base URLs, authentication headers, response format, pagination, and rate limits.

Edge Function Base URLs:

Environment	Pattern
Local	`http://127.0.0.1:54321/functions/v1/{function}/*`
Production	`https://<project-ref>.supabase.co/functions/v1/{function}/*`

Architecture¶

System design, security model, and architectural decisions.

Document	Description
Architecture Overview	System diagram and component overview
API Protection Architecture	Security model: auth levels, rate limiting, paywall, RLS, middleware
API Protection Guide	Implementation details for securing endpoints
API Lineage Validation	Data lineage tracking across the content hierarchy
Hybrid Architecture Guide	(Historical) Domain/Experience API split design — superseded by single-layer architecture
Domain Independence Proposal	Design proposal for service independence and bounded context separation
Implementation Plan	Phased implementation roadmap for platform features

System Architecture:

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

Authentication¶

JWT-based authentication via Supabase Auth.

Document	Description
Authentication Overview	Auth flow diagram and endpoint classification
Authentication Guide	Comprehensive guide: JWT lifecycle, token validation, authorization model, integration patterns
Auth Implementation	Middleware implementation, JWT verification, OAuth flows, RBAC

Endpoint Auth Classification:

Endpoint	Auth
`GET /graph/*`	Optional
`GET /content/*`	Optional
`GET /home`	Optional
`GET /search/*`	Required
`GET /metadata/*`	Public
`GET /snapshots/*`	Required
`GET /me/*`	Required

Configuration¶

Environment variables, secrets management, and OAuth provider setup.

Document	Description
Configuration Overview	Environment principles and GitHub Secrets reference
Multi-Environment Configuration	Complete env variable reference for local, staging, and production
Secrets Management	How secrets flow from local → CI/CD → Supabase; rotation procedures
OAuth Setup	OAuth provider configuration in Supabase Dashboard
OAuth Provider Setup	Step-by-step setup for GitHub and Google OAuth

Environment Files:

File	Committed	Purpose
`.env.local.example`	Yes	Template for local development
`.env.local`	No	Local development secrets
`supabase/config.toml`	Yes	Supabase config

Database¶

Schema, migrations, RLS, and data management.

Document	Description
Database Overview	Content model, schema overview, and common commands
Database Setup	Table structure, Postgres functions, RLS policies, indexes
Data Hydration and Seeding	Migration strategy, seed scripts, and all data tasks
Seed Curriculum Guide	Agentic AI curriculum seed data format and import
Snapshot Publishing Workflow	Content versioning: draft → published → archived lifecycle

Content Hierarchy:

Domain (e.g., "Machine Learning")
  └── Trail (10-20 hours, e.g., "Transformer Mastery")
       └── Concept (30-60 mins, e.g., "Attention Mechanisms")
            └── Spark (5-10 mins, e.g., "Self-Attention Explained")

Deployment¶

Edge Function deployment, CI/CD pipelines, and SDK publishing.

Document	Description
Deployment Overview	Deployment workflows and quick commands
Deployment Guide	Step-by-step: migrations, Edge Functions, secrets
Branching Setup	Multi-environment branching with Supabase branches (main/develop/pr-*)
CI/CD Guide	GitHub Actions workflows: lint, tests, deploy
Supabase Operations	Production operations and maintenance procedures
SDK Publishing Guide	SemVer, GitHub Packages (NPM), GitHub Releases (Python), local Verdaccio
Deployment Plan	Release planning and versioning strategy

Deployment Triggers:

Trigger	Target	Workflow
Push to `main`	Production	`deploy-production.yml`
Push to `develop`	Staging	`deploy-staging.yml`
PR + `deploy-preview` label	Preview	`pr-checks.yml`

Testing¶

Integration testing infrastructure and test execution.

Document	Description
Testing Overview	Quick start, test commands, and test user credentials
Integration Testing Guide	E2E test framework: TestClient, fixtures, writing and running tests, CI integration
Getting a Test Token	Obtaining JWT tokens for authenticated test requests
Running and Testing	Quick reference for all test commands

Local Environment (Integration Tests):

deno task local:start        # Start local Supabase
deno task local:setup        # Reset DB + seed test users
deno task function:serve     # Serve edge functions
deno task test:e2e:all       # Run all integration tests
deno task local:stop         # Stop local environment

Test Users:

Role	Email	Password
FREE	test-free@example.com	test123456
PRO	test-pro@example.com	test123456
PREMIUM	test-premium@example.com	test123456
ADMIN	test-admin@example.com	test123456

Operations¶

Logging, batch import, and ETL integrations.

Document	Description
Operations Overview	Log commands and operational runbook
Logging Guide	Log levels, structured logging, aggregation, debugging
Batch Import Guide	Bulk data import: format, batch processing, error handling
Integration Guide	ETL integrations: external data sources, import pipelines, transformation

Troubleshooting¶

Common issues and fixes.

Document	Description
Troubleshooting Overview	Quick fixes for Supabase, auth, database, and CI/CD issues
Troubleshooting Guide	Comprehensive issue catalog: local dev, auth failures, DB connections, deployment
Colima Fix	Docker on macOS with Colima: known issues and workarounds
Switch to Docker Desktop	Migration guide from Colima to Docker Desktop

Quick Reference¶

Task	Documentation
First-time setup	Local Development and Testing
Understand the platform	Developer Guide
Browse API endpoints	API Reference
Journeys / Trails API	Journeys API
Configure environments	Multi-Env Configuration
Manage secrets	Secrets Management
Set up OAuth	OAuth Setup
Understand auth	Authentication Guide
Understand security	API Protection Architecture
Seed / hydrate data	Data Hydration and Seeding
Publish content	Snapshot Publishing Workflow
Run integration tests	Integration Testing Guide
Set up local environment	Local Development and Testing
Deploy to production	Deployment Guide
Set up CI/CD	CI/CD Guide
Publish the SDK	SDK Publishing Guide
Fix common issues	Troubleshooting Guide
Fix Docker on macOS	Colima Fix