RpgTracker Platform

A self-improvement platform built as a Turborepo monorepo. Three apps share a single Go API, auth layer, and React component library.

App	Path	Status
LifeQuest — RPG-style skill/XP tracker	apps/rpg-tracker	Fully implemented
NutriLog — Nutrition and weight tracking	apps/nutri-log	Scaffolded
MindTrack — Mental wellness tracking	apps/mental-health	Scaffolded
Go API — Shared REST backend	apps/api	Fully implemented

Stack

• Frontend: Next.js 15 App Router · React 19 · Tailwind v4 · TanStack Query · Framer Motion
• Backend: Go · chi router · pgx v5 · Supabase JWT auth
• Shared packages: @rpgtracker/ui · @rpgtracker/auth · @rpgtracker/api-client
• Monorepo: Turborepo · pnpm workspaces
• Database: Local Docker PostgreSQL (application data) · golang-migrate
• Auth: Supabase Auth (email/password + JWT validation) — auth only, not application data
• AI: Claude API — user-supplied key, stored AES-256-GCM encrypted server-side

AI Features

• AI goal planning: Natural-language objectives (for example, "I want to learn Chinese this year") can be converted into structured plans via POST /api/v1/goals/plan.
• Where it is documented: Backend contract and route behavior in apps/api/README.md; frontend flow and UX in apps/rpg-tracker/README.md.
• Access model: Planner requires saved AI key plus backend entitlement checks; degraded responses return a safe fallback plan with degraded_response: true.
• How to test: Use the manual checklist in apps/api/README.md ("Manual testing: AI planner + membership tiers").

Local Development

Requirements: Node ≥ 20, pnpm ≥ 9, Go 1.23+, Docker

# 1. Install JS dependencies
pnpm install
# Husky pre-commit hook installs via `prepare` script.

# 2. Set up Go API environment
cp apps/api/.env.example apps/api/.env
# Edit apps/api/.env — fill in SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, MASTER_KEY

# 3. Start the database
docker compose up -d db
# ⚠️  Use plain `docker compose down` to stop — never `down -v` unless you want a full reset.
# The -v flag deletes the db_data volume and all local application data permanently.

# 4. Start the Go API (migrations run automatically on startup)
cd apps/api && make run

# 5. Start all Next.js apps (from repo root, separate terminal)
cd ../.. && pnpm dev

Each app runs on its own port. The Next.js apps proxy API requests to the Go server at http://localhost:8080.

Database architecture: Supabase handles authentication only (auth.users, JWT signing). All application data (public.users, public.skills, etc.) lives in the local Docker postgres container. The Supabase SQL Editor does not contain these tables. See apps/api/README.md for how to query local data.

Tests

# Install JS dependencies first if needed
pnpm install

# JS workspace build and test checks (matches CI)
pnpm build
pnpm test
pnpm validate:skills

# Go API
cd apps/api && go test ./...

# Combined pre-commit quality gate
cd ../.. && pnpm check:precommit

GitHub Actions runs the same practical checks on pull requests to main and pushes to main or cursor/**: pnpm build, pnpm test, and go test ./... in apps/api.

Project Structure

apps/
  api/              Go REST API (chi, pgx, Supabase JWT)
  rpg-tracker/      LifeQuest — Next.js 15 App Router
  nutri-log/        NutriLog  — Next.js 15 App Router (scaffolded)
  mental-health/    MindTrack — Next.js 15 App Router (scaffolded)
packages/
  ui/               Shared React components + design tokens
  auth/             Supabase SSR helpers (browser + server)
  api-client/       Typed fetch client for the Go API
  tsconfig/         Shared TypeScript config
docs/
  CURSOR-AGENT-HANDBOOK.md Cursor-first workflow and CI/CD agent model
  prd-agentic-ai.md Personal experimentation roadmap
  guides/           Operational guides for onboarding and runtime lanes
  setup.md          One-time Supabase trigger setup
Documentation/
  architecture.md   DB schema, domain model, integration contracts
  decision-log.md   Confirmed product and architectural decisions
  feature-tracker.md Per-feature status and deferred list
  README.md         Canonical documentation index

Design System

LifeQuest uses a three-theme system, switchable in account settings:

• Minimal — clean, data-forward productivity styling
• Retro — RPG-inspired visual language
• Modern — polished sci-fi command-center styling

Theme tokens live in packages/ui/tokens/ and all components are expected to be theme-aware.

Agentic Development

This project uses Cursor-first agentic workflows for feature development, review, and CI/CD automation.

• Repository context directory: AGENTS.md
• Canonical documentation map: Documentation/README.md
• Operating workflow (IDE, cloud agent chat, CI/CD SDK agents): docs/CURSOR-AGENT-HANDBOOK.md

CI/CD Agent Automation

Additional automation workflows:

• .github/workflows/cursor-pr-review.yml - Cursor SDK PR review summaries/comments
• .github/workflows/cursor-security-triage.yml - Dependabot/code-scanning triage
• .github/workflows/cursor-fix-attempt.yml - cloud auto-fix attempt loop (PR review + Sonar context -> fix attempt PR)
• .github/workflows/cursor-agent-pr-labels.yml - auto-label trusted cloud-agent PRs at open/reopen
• .github/workflows/codeql.yml - code scanning signal generation
• .github/dependabot.yml - dependency update PR generation
• .github/workflows/mend-renovate.yml - Renovate dependency update pipeline (token-based)
• .github/workflows/sonarcloud.yml - SonarCloud static analysis pipeline
• .github/workflows/quality-onboarding-smoke.yml - one-click onboarding smoke checklist

Required repository secret:

• CURSOR_API_KEY - key used by CI workflows that call @cursor/sdk
• RENOVATE_TOKEN - token for workflow-driven Renovate runs
• SONAR_TOKEN - token for SonarCloud analysis

Recommended repository variables:

• SONAR_ORGANIZATION - SonarCloud organization key
• SONAR_PROJECT_KEY - SonarCloud project key
• CURSOR_RUNTIME - local (default) or cloud for SDK workflow routing
• CURSOR_CLOUD_REPO_URL - repo URL for cloud runtime execution
• CURSOR_AUTO_FIX_ENABLED - true to allow automatic cloud fix attempts from workflow triggers
• CURSOR_AUTO_FIX_LABEL - PR label required for auto-fix (cursor:auto-fix by default)
• CURSOR_FIX_PLANNER_MODEL - model ID for planning pass in auto-fix workflow (default composer-2)
• CURSOR_FIX_EXECUTION_MODEL - lower-cost model ID for implementation pass (default composer-2-fast)
• CURSOR_FIX_MODEL - legacy fallback model variable for execution pass
• CURSOR_REQUIRE_TEST_CHANGES - true to fail auto-fix attempts with code changes but no unit-test file changes
• CURSOR_REQUIRE_REVIEW_SCHEMA - true to require machine-readable PR review payload before auto-fix planning
• CURSOR_AUTO_FIX_EXCLUDED_AUTHORS - comma-separated PR authors excluded from auto-fix source selection (cursor[bot] default)
• CURSOR_AGENT_PR_LABELS - comma-separated labels applied to trusted agent-created PRs (cursor:agent-generated default)
• CURSOR_AGENT_TRUSTED_LOGINS - comma-separated logins treated as trusted agent PR authors (cursor[bot] default)
• CURSOR_AGENT_BRANCH_PREFIXES - comma-separated branch prefixes treated as trusted agent PR heads (cursor/ default)
• CURSOR_AGENT_PR_LABELING_ENABLED - set to false to disable open/reopen auto-labeling workflow
• SONAR_MIN_NEW_COVERAGE - minimum SonarCloud PR new-code coverage (default 80)