Usage Guide

Complete guide for local development, testing, and production usage of the Micro-Learning Platform API.

Table of Contents

1. Overview
2. Local Development
3. Testing with api.http
4. Production Usage
5. Multi-Function Architecture
6. Authentication
7. Quick Reference

---

Overview

The Micro-Learning Platform API is deployed as multiple independent Supabase Edge Functions, each handling specific functionality. This architecture provides:

• ✅ Independent Telemetry: Each function has its own metrics and logs
• ✅ Selective Deployment: Deploy only the functions that changed
• ✅ Better Isolation: Errors in one function don't affect others
• ✅ Easier Testing: Test functions independently
• ✅ Scalability: Scale functions based on usage patterns

Function Overview

Function	Purpose	Key Endpoints
browse	Content browsing	/api/v1/domains, /api/v1/trails, /api/v1/concepts, /api/v1/sparks, /api/v1/beacons
search	Search & autocomplete	/api/v1/search, /api/v1/autocomplete
discovery	Discovery/experience APIs	/api/v1/discovery/domains, /api/v1/discovery/trails, /api/v1/discovery/concepts
graph	Knowledge graph operations	/api/v1/graph/*, /api/v1/path
user	User profile & progress	/api/v1/me/*, /api/v1/me/journeys, /api/v1/me/events
metadata	Metadata enumerations	/api/v1/metadata
snapshots	Content versioning	/api/v1/snapshots

---

Local Development

Prerequisites

• Docker: Running (Docker Desktop or Colima)
• Deno: Installed (v1.40+)
• Supabase CLI: Installed (npm install -g supabase)

Quick Start

# 1. Start Supabase (includes PostgreSQL, Auth, etc.)
supabase start

# 2. Setup testing environment
deno task setup:e2e  # Creates test user, updates api.http

# 3. Start API server
deno task dev

Access Points: - API Server: http://localhost:8000 - API Docs (Swagger): http://localhost:8000/doc - Supabase Studio: http://127.0.0.1:54323

Development Server (Recommended)

Best for: Development, debugging, hot reload

deno task dev

Advantages: - ✅ Hot reload on file changes - ✅ Structured JSON logs - ✅ Easy debugging - ✅ Single unified API at http://localhost:8000 - ✅ All endpoints available at /api/v1/*

Usage:

# All endpoints available at:
curl http://localhost:8000/api/v1/domains
curl http://localhost:8000/api/v1/search?q=test
curl http://localhost:8000/api/v1/me  # Requires auth

Edge Functions (Production-like Testing)

Best for: Testing production deployment, edge function behavior

# Start Supabase first
supabase start

# Serve individual functions
supabase functions serve browse
supabase functions serve search
supabase functions serve discovery
# ... etc

# Or serve all at once
deno task serve:functions all

Function URLs: - Browse: http://127.0.0.1:54321/functions/v1/browse - Search: http://127.0.0.1:54321/functions/v1/search - Discovery: http://127.0.0.1:54321/functions/v1/discovery - User: http://127.0.0.1:54321/functions/v1/user - Graph: http://127.0.0.1:54321/functions/v1/graph - Metadata: http://127.0.0.1:54321/functions/v1/metadata - Snapshots: http://127.0.0.1:54321/functions/v1/snapshots

Important: When using edge functions, the path includes /api/v1/: - ✅ Correct: http://127.0.0.1:54321/functions/v1/browse/api/v1/domains - ❌ Wrong: http://127.0.0.1:54321/functions/v1/browse/domains

Environment Setup

1. Get Supabase credentials:

   supabase start
   # Copy the anon key and service_role key from output
   

2. Create .env file:

   cp env.example .env
   

3. Edit .env:

   SUPABASE_URL=http://127.0.0.1:54321
   SUPABASE_ANON_KEY=<anon key from supabase start>
   SUPABASE_SERVICE_ROLE_KEY=<service_role key from supabase start>
   

4. Initialize database:

   supabase db reset  # Applies migrations and seeds data
   

---

Testing with api.http

The api.http file provides a convenient way to test all API endpoints using VS Code's REST Client extension.

Setup

1. Install REST Client Extension:
2. Open VS Code
3. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
4. Search for "REST Client" by Huachao Mao

5. Install it

6. Get Authentication Token:

For Local Development:

deno task setup:e2e

This automatically: - Creates a test user (test@example.com / test123456) - Gets a JWT token from local Supabase - Updates api.http with the token

For Production:

deno task setup:production

Or with arguments:

deno task setup:production <email> <password> <project-ref>

This automatically: - Authenticates with production Supabase - Gets a production JWT token - Updates api.http with production URLs and token

1. Refresh Token (when expired):

   # Local (token expires in 1 hour)
   deno task api:token
   
   # Production
   deno task setup:production
   

Using api.http

1. Open api.http in VS Code

2. Configure Base URL:

3. Local Development Server: Uncomment @baseUrl = http://localhost:8000
4. Local Edge Functions: Use function-specific URLs:

   @browseUrl = http://127.0.0.1:54321/functions/v1/browse
   @searchUrl = http://127.0.0.1:54321/functions/v1/search
   # etc.
   

5. Production: Use production URLs (auto-updated by setup:production)

6. Send Requests:

7. Click "Send Request" above any request

8. Or use keyboard shortcut:

   • Mac: Cmd+Option+R
   • Windows/Linux: Ctrl+Alt+R

9. Test Authenticated Endpoints:

10. Ensure @authToken is set (run deno task setup:e2e or deno task setup:production)
11. Requests with Authorization: Bearer {{authToken}} will automatically use the token

Example Requests

Public Endpoints (no auth required):

### Discover domains (public - no auth required)
GET {{discoveryUrl}}/api/v1/discovery/domains

### Discover trails (public - no auth required)
GET {{discoveryUrl}}/api/v1/discovery/trails

### Get metadata (public - no auth required)
GET {{metadataUrl}}/api/v1/metadata

Authenticated Endpoints (require JWT token):

### List domains (authenticated)
GET {{browseUrl}}/api/v1/domains
Authorization: Bearer {{authToken}}

### Search content (authenticated)
GET {{searchUrl}}/api/v1/search?q=machine learning
Authorization: Bearer {{authToken}}

### Get user profile (authenticated)
GET {{userUrl}}/api/v1/me
Authorization: Bearer {{authToken}}

### List user journeys (authenticated)
GET {{userUrl}}/api/v1/me/journeys
Authorization: Bearer {{authToken}}

For complete authentication documentation, see Authentication Guide.

Health Checks:

### Check all functions
GET {{browseUrl}}/health
GET {{searchUrl}}/health
GET {{discoveryUrl}}/health
GET {{userUrl}}/health
GET {{graphUrl}}/health
GET {{metadataUrl}}/health
GET {{snapshotsUrl}}/health

Function-Specific Testing

When testing with edge functions (local or production), use function-specific URLs:

### Browse Function (requires auth)
GET {{browseUrl}}/api/v1/domains
Authorization: Bearer {{authToken}}

GET {{browseUrl}}/api/v1/trails
Authorization: Bearer {{authToken}}

GET {{browseUrl}}/api/v1/concepts
Authorization: Bearer {{authToken}}

### Search Function (requires auth)
GET {{searchUrl}}/api/v1/search?q=test
Authorization: Bearer {{authToken}}

GET {{searchUrl}}/api/v1/search/autocomplete?q=neural
Authorization: Bearer {{authToken}}

### Discovery Function (public - no auth required)
GET {{discoveryUrl}}/api/v1/discovery/domains

GET {{discoveryUrl}}/api/v1/discovery/trails

### Graph Function (requires auth)
GET {{graphUrl}}/api/v1/graph/sparks/intro-to-neural-nets
Authorization: Bearer {{authToken}}

### Snapshots Function (requires auth)
GET {{snapshotsUrl}}/api/v1/snapshots
Authorization: Bearer {{authToken}}

### Metadata Function (public - no auth required)
GET {{metadataUrl}}/api/v1/metadata

### User Function (requires auth)
GET {{userUrl}}/api/v1/me
Authorization: Bearer {{authToken}}

---

Production Usage

Getting Production Credentials

1. Get Project Reference:
2. Go to https://supabase.com/dashboard
3. Select your project
4. Go to Settings > General

5. Copy the "Reference ID"

6. Get API Keys:

7. Go to Settings > API
8. Copy the "anon" key (for client-side)
9. Copy the "service_role" key (for server-side, keep secret!)

Setting Up Production Testing

1. Get Production Token:

   deno task setup:production
   

   Follow the prompts to enter:
2. Email (of a user in production)
3. Password

4. Project reference ID (or Supabase URL)

5. Or use environment variables:

   export SUPABASE_URL=https://xxx.supabase.co
   export SUPABASE_ANON_KEY=your-anon-key
   export SUPABASE_PROJECT_REF=xxx
   deno task setup:production <email> <password>
   

6. Or use command-line arguments:

   deno task setup:production <email> <password> <project-ref>
   

7. Verify api.http is updated:

8. Check that @authToken has a production token
9. Check that function URLs point to production
10. Test a health endpoint: GET {{browseUrl}}/health

Production Endpoints

All production endpoints follow this pattern:

https://<project-ref>.supabase.co/functions/v1/<function-name>/api/v1/<endpoint>

Examples: - Browse domains: https://xxx.supabase.co/functions/v1/browse/api/v1/domains - Search: https://xxx.supabase.co/functions/v1/search/api/v1/search?q=test - User profile: https://xxx.supabase.co/functions/v1/user/api/v1/me

Function URLs

Production Base URLs:

https://<project-ref>.supabase.co/functions/v1/browse
https://<project-ref>.supabase.co/functions/v1/search
https://<project-ref>.supabase.co/functions/v1/discovery
https://<project-ref>.supabase.co/functions/v1/user
https://<project-ref>.supabase.co/functions/v1/graph
https://<project-ref>.supabase.co/functions/v1/metadata
https://<project-ref>.supabase.co/functions/v1/snapshots

Authentication in Production

1. For Public Endpoints (no authentication required):
2. Only discovery and metadata endpoints are public
3. Examples:
   • /api/v1/discovery/domains
   • /api/v1/discovery/trails
   • /api/v1/discovery/concepts
   • /api/v1/metadata

4. Can be accessed without Authorization header

5. For Authenticated Endpoints (require JWT token):

6. All other endpoints require authentication
7. Requires Authorization: Bearer <token> header
8. Token must be a valid Supabase JWT
9. Get token via deno task setup:production or Supabase Auth API
10. Examples:
    • /api/v1/domains (browse function)
    • /api/v1/trails (browse function)
    • /api/v1/search (search function)
    • /api/v1/graph/* (graph function)
    • /api/v1/snapshots/* (snapshots function)
    • /api/v1/me/* (user function)

For detailed authentication documentation, see Authentication Guide.

1. Token Expiration:
2. Tokens expire after 1 hour
3. Refresh by running deno task setup:production again
4. Or implement token refresh in your application

Deploying Functions

# Deploy all functions
deno task deploy:all

# Deploy specific function
deno task deploy:browse
deno task deploy:search
deno task deploy:discovery
deno task deploy:user
deno task deploy:graph
deno task deploy:metadata
deno task deploy:snapshots

# Deploy only changed functions
deno task deploy:changed

# Check deployment status
supabase functions list

# View function logs
supabase functions logs browse
supabase functions logs search
# etc.

# Check function health
deno task check:functions --project-ref <ref>

For detailed deployment instructions, see DEPLOYMENT_GUIDE.md.

---

Multi-Function Architecture

Why Multiple Functions?

The API is split into multiple independent functions for:

1. Independent Telemetry: Each function has its own metrics and logs
2. Selective Deployment: Deploy only the functions that changed
3. Better Isolation: Errors in one function don't affect others
4. Easier Testing: Test functions independently
5. Scalability: Scale functions based on usage patterns

Function Responsibilities

browse - Content browsing and navigation - Domains, trails, concepts, sparks, beacons - Entity relationships and navigation - Content details and metadata

search - Search and discovery - Full-text search across all content - Autocomplete suggestions - Search facets and filters

discovery - Discovery/experience APIs - Aggregated domain views with trails - Trail views with concepts - Concept views with sparks

graph - Knowledge graph operations - Prerequisite relationships - Learning path calculations - Graph traversal and queries

user - User profile and progress - User profile management - Learning journeys - Learning events and milestones - User statistics

metadata - Metadata enumerations - Difficulty levels - Link types - Journey statuses - Learning verbs - Beacon categories

snapshots - Content versioning - Snapshot management - Historical content access - Version comparison

Function URLs Structure

Local Development:

http://127.0.0.1:54321/functions/v1/<function-name>/api/v1/<endpoint>

Production:

https://<project-ref>.supabase.co/functions/v1/<function-name>/api/v1/<endpoint>

Development Server (unified):

http://localhost:8000/api/v1/<endpoint>

Health Checks

Each function has its own health endpoint:

# Local
curl http://127.0.0.1:54321/functions/v1/browse/health
curl http://127.0.0.1:54321/functions/v1/search/health
# etc.

# Production
curl https://<project-ref>.supabase.co/functions/v1/browse/health
curl https://<project-ref>.supabase.co/functions/v1/search/health
# etc.

# Check all functions
deno task check:functions --local  # Local
deno task check:functions --project-ref <ref>  # Production

Swagger UI

Each function has its own Swagger UI:

Local: - Browse: http://127.0.0.1:54321/functions/v1/browse/doc - Search: http://127.0.0.1:54321/functions/v1/search/doc - etc.

Production: - Browse: https://<project-ref>.supabase.co/functions/v1/browse/doc - Search: https://<project-ref>.supabase.co/functions/v1/search/doc - etc.

Development Server: - Unified: http://localhost:8000/doc

---

Authentication

Getting a JWT Token

Local Development:

deno task setup:e2e

- Creates test user: test@example.com / test123456 - Gets JWT token from local Supabase - Updates api.http automatically

Production:

deno task setup:production

- Authenticates with production Supabase - Gets production JWT token - Updates api.http with production URLs and token

Manual (via Supabase Auth API):

curl -X POST 'https://<project-ref>.supabase.co/auth/v1/token?grant_type=password' \
  -H "apikey: YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

Using Authentication

In api.http:

GET {{userUrl}}/api/v1/me
Authorization: Bearer {{authToken}}

In curl:

curl -H "Authorization: Bearer <token>" \
  https://<project-ref>.supabase.co/functions/v1/user/api/v1/me

In JavaScript/TypeScript:

const response = await fetch('https://xxx.supabase.co/functions/v1/user/api/v1/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Token Refresh

Tokens expire after 1 hour. Refresh by:

# Local
deno task api:token

# Production
deno task setup:production

Or implement automatic token refresh in your application using Supabase's refresh token mechanism.

---

Quick Reference

Local Development Workflow

# 1. Start services
supabase start

# 2. Setup testing
deno task setup:e2e

# 3. Start API
deno task dev  # Development server
# OR
supabase functions serve browse  # Edge function

# 4. Test
# Open api.http in VS Code and click "Send Request"
# Or use Swagger UI: http://localhost:8000/doc

Production Workflow

# 1. Get production token
deno task setup:production

# 2. Test production endpoints
# Open api.http in VS Code and use function-specific URLs

# 3. Deploy functions
deno task deploy:all

# 4. Monitor
supabase functions logs browse
deno task check:functions --project-ref <ref>

Common Commands

# Setup
deno task setup:e2e              # Local testing setup
deno task setup:production       # Production token setup

# Development
deno task dev                    # Start dev server
deno task serve:functions all    # Serve all edge functions

# Deployment
deno task deploy:all             # Deploy all functions
deno task deploy:browse          # Deploy specific function
deno task deploy:changed         # Deploy only changed functions

# Testing
deno task check:functions --local              # Check local functions
deno task check:functions --project-ref <ref> # Check production functions
deno task test:e2e                            # Run E2E tests

# Token Management
deno task api:token              # Refresh local token
deno task setup:production       # Refresh production token

Environment Variables

Local Development (.env):

SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=<from supabase start>
SUPABASE_SERVICE_ROLE_KEY=<from supabase start>

Production:

SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_ANON_KEY=<from Supabase Dashboard>
SUPABASE_SERVICE_ROLE_KEY=<from Supabase Dashboard>
SUPABASE_PROJECT_REF=<project-ref>

---

Next Steps

• API Testing: Use the Swagger UI or api.http file
• Database Exploration: Use Supabase Studio at http://127.0.0.1:54323
• API Usage: See Developer Guide for integration examples
• Deployment: See Deployment Guide for production deployment
• Logging: See Logging Guide for log format and filtering
• Troubleshooting: See Troubleshooting Guide for common issues