CSG Learning Platform

The all-in-one learning hub for Code School of Guam — prework, live class, workshops, recordings, grading, progress tracking, and cohort management.

Architecture

Layer	Tech	Details
Frontend	React 19 + TypeScript + Tailwind v4 + Vite	SPA with role-based routing
Mobile	Expo SDK 57 + React Native 0.86	Communications-first iOS and Android client
Backend	Rails 8.1 API-only	RESTful JSON API under /api/v1/
Auth	Clerk	Invite-only, JWT-based, role-based (student / instructor / admin)
Database	PostgreSQL	Neon (production), local Postgres (development)
Frontend Hosting	Netlify	learn.codeschoolofguam.com
API Hosting	Render (Singapore)	learn-api.codeschoolofguam.com
Analytics	PostHog	Privacy-safe typed web/native product and learning events; autocapture and session replay disabled

Monorepo Structure

csg-learning-platform/
├── api/            Rails 8.1 API backend
├── web/            React + Vite frontend
├── mobile/         Expo + React Native communications client
├── docs/           Product vision, learning strategy, roadmap, deployment guides
├── scripts/        Data import and utility scripts
└── AGENTS.md       AI/developer conventions

Quick Start

Prerequisites

• Ruby 3.3.7+ and Bundler 4+
• Node.js 20.19+ or 22.12+ and npm
• PostgreSQL 16+

Select the Repo Toolchain First

This repo now includes .ruby-version, .nvmrc, and .node-version.

cd csg-learning-platform
nvm use                    # uses 20.19.5 from .nvmrc
rbenv local 3.3.7         # or ensure your Ruby manager picks up .ruby-version
ruby -v
node -v

Expected local versions:

• Ruby 3.3.7
• Bundler 4.0.5+
• Node 20.19.5 or 22.12+

Do not rely on a global eslint binary for the frontend. Use the project-local command via npm run lint.

Backend Setup

cd api
cp .env.example .env        # Edit with your Clerk + DB credentials
bundle install
rails db:create db:migrate db:seed
rails server -p 3000

Frontend Setup

cd web
cp .env.example .env        # Edit with API URL + Clerk key
npm install
npm run dev                  # Starts on http://localhost:5173

Running Tests

cd api
bundle exec rails test       # Runs integration + unit tests

cd ../web
npm run check                # Lint + typecheck + unit tests + production build

cd ../mobile
npm run check                # Strict TypeScript + lint + native unit tests

Environment Variables

See api/.env.example and web/.env.example for all required and optional variables. Key ones:

Variable	Where	Required	Purpose
CLERK_ISSUER	API	Yes	JWT verification
CLERK_SECRET_KEY	API	No	Enriching user data from Clerk
DATABASE_URL	API	Prod only	Neon connection string
FRONTEND_URL	API	Yes	CORS allowlist
VITE_API_URL	Web	Yes	API base URL
VITE_CLERK_PUBLISHABLE_KEY	Web	Yes	Clerk auth for all environments, including local development

Core Domain Model

Curriculum
  └── CurriculumModule (prework, live_class, workshop, etc.)
        └── Lesson (day-based release scheduling)
              └── ContentBlock (video, text, exercise, checkpoint)

Cohort (assigned a Curriculum)
  └── Enrollment (User ↔ Cohort)
        ├── ModuleAssignment (per-student access overrides)
        └── LessonAssignment (per-student unlock overrides)

User
  ├── Progress (per ContentBlock completion tracking)
  └── Submission (graded exercise responses)

Key Features

• Curriculum Management — Reusable curricula with modules, lessons, and content blocks
• Cohort Operations — Create cohorts, assign curricula, manage enrollments
• Unlock Engine — Day-based scheduling with cohort-wide and per-student overrides
• Submission Windows — Per-cohort, per-module weekly deadlines that stop new work without hiding lessons or videos
• Progress Tracking — S3 watch progress plus legacy YouTube/Vimeo completion tracking, exercise marking, per-block granularity
• Grading & Feedback — Submission queue, A/B/C/R grading, redo workflow, GitHub issue integration
• Communication Hub — Announcements, cohort channels, direct messages, push notifications, and reviewed native voice-to-text drafts in the same app
• Contextual Student Support — Durable lesson/exercise/recording help requests with visible acknowledgment, instructor response, and a shared staff queue
• Recordings Library — Self-hosted AWS S3 uploads are the preferred path, with legacy external video support during migration
• Office Hours — One-time and timezone-aware recurring help sessions surfaced on student dashboards
• Live Classroom Platform (Deferred) — Documented future direction; Zoom remains operational while learning-feedback and intervention work takes priority
• Role-Based Access — Student, instructor, and admin roles with appropriate UI and API gates
• Mobile + Responsive UI — Native daily learning/communication companion plus responsive web administration and authoring
• Analytics — Explicit privacy-safe PostHog learning, support, code-navigation, and voice-draft events across web and native

Documentation

Document	Purpose
docs/PRODUCT_VISION.md	Why this product exists and where it's going
docs/PRODUCT_STRATEGY_AND_LEARNING_EXPERIENCE_PLAN.md	Current audit, platform research, learning strategy, KPIs, and phased plan
docs/VOICE_TO_TEXT_PLAN.md	Voice-draft product flow, privacy, architecture, rollout, and quality gates
docs/ROADMAP.md	What to build now, next, and later
docs/DEPLOYMENT.md	Step-by-step deployment for Render + Netlify
docs/API_REFERENCE.md	All API endpoints with request/response details
docs/BUILD_PLAN.md	Historical MVP planning document; current direction lives in the product vision and roadmap
docs/CLASSROOM_PLATFORM_PLAN.md	Live classroom strategy, scope boundaries, and implementation direction
docs/MOBILE_APP.md	Messaging-first native app scope, architecture, and release path
docs/FUTURE_IMPROVEMENTS.md	Planned enhancements (GitHub onboarding, etc.)
docs/SETUP_CHECKLIST.md	Post-deploy setup (Search Console, PostHog, PWA)
api/README.md	Backend-specific setup, models, and API overview
web/README.md	Frontend-specific setup, routes, and components