🔧 Technical Documentation
Setup & Configuration
Local Development Setup

Local Development Setup

Complete guide for setting up the MyNATCA ecosystem locally for development. This guide covers Platform, Pay, Discord, and all supporting services.

Overview

The MyNATCA ecosystem consists of multiple integrated repositories:

  • Platform - Core API and shared services (Node.js/Express)
  • Pay - PayChecker application (Python/FastAPI)
  • Discord - Discord bot verification system (Node.js)
  • Member Hub - Member-facing web application (Next.js)
  • BID - Bidding system (future)

All projects share a single Supabase database with schema-based separation.

Prerequisites

Required Software

# Node.js 20+ (LTS)
# Install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
 
# Docker Desktop
# Download from https://www.docker.com/products/docker-desktop
# Ensure Docker is running before proceeding
 
# Supabase CLI 2.65+
npm install -g supabase@latest
# OR via Homebrew
brew install supabase/tap/supabase
 
# PostgreSQL Client (psql)
brew install postgresql@16
 
# Python 3.11+ (for Pay project)
brew install python@3.11
 
# Git 2.5+
git --version  # Verify installation

Verify Installations

node --version      # v20.x.x
npm --version       # v10.x.x
docker --version    # Docker version 24.x.x
supabase --version  # 2.65.x or higher
psql --version      # psql (PostgreSQL) 16.x
python3 --version   # Python 3.11.x or higher
git --version       # git version 2.x.x

Repository Setup

1. Create Workspace Directory

mkdir -p ~/dev/mynatca
cd ~/dev/mynatca

2. Clone Repositories

# Clone platform (required - central coordination point)
git clone [platform-repo-url] platform
 
# Clone pay (optional - only if working on PayChecker)
git clone [pay-repo-url] pay
 
# Clone discord (optional - only if working on Discord bot)
git clone [discord-repo-url] discord
 
# Clone hub (optional - only if working on Member Hub)
git clone [hub-repo-url] hub

Expected structure:

~/dev/mynatca/
├── platform/    # Core platform (required)
├── pay/         # PayChecker (optional)
├── discord/     # Discord bot (optional)
└── hub/         # Member Hub (optional)

Platform Setup (Required)

The Platform repository coordinates all database operations, migrations, and seeding.

1. Install Dependencies

cd ~/dev/mynatca/platform
npm install

2. Configure Environment Variables

cp .env.example .env

Edit .env with your configuration:

# ==============================================================================
# SUPABASE (Local Development)
# ==============================================================================
# These will be provided by `supabase start` command
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=<from-supabase-start-output>
SUPABASE_SERVICE_ROLE_KEY=<from-supabase-start-output>

# Database direct connection (for seeds and migrations)
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

# ==============================================================================
# AUTH0 (Get from team)
# ==============================================================================
AUTH0_DOMAIN=mynatca.us.auth0.com
AUTH0_CLIENT_ID=<ask-team>
AUTH0_CLIENT_SECRET=<ask-team>
AUTH0_BASE_URL=http://localhost:1300
AUTH0_REDIRECT_URI=http://localhost:1300/api/auth/callback
AUTH0_SECRET=<generate-with-openssl-rand-hex-32>

# ==============================================================================
# SEED DATA SOURCE (Staging or Production)
# ==============================================================================
# URL and key for seeding data from remote environment
SEED_SOURCE_URL=https://<staging-ref>.supabase.co
SEED_SOURCE_SERVICE_KEY=<ask-team>

# ==============================================================================
# APPLICATION
# ==============================================================================
NODE_ENV=development
PORT=1300
HOST=localhost
BASE_URL=http://localhost:1300

# ==============================================================================
# REDIS (Optional for development - can use memory sessions)
# ==============================================================================
# REDIS_URL=redis://localhost:6379

# ==============================================================================
# SESSION
# ==============================================================================
SESSION_SECRET=<generate-with-openssl-rand-hex-32>

3. Start Supabase

cd ~/dev/mynatca/platform
supabase start

First-time startup will download Docker images (~2-3 minutes).

Save the output - you'll need these values for .env:

API URL: http://127.0.0.1:54321
GraphQL URL: http://127.0.0.1:54321/graphql/v1
S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
Studio URL: http://127.0.0.1:54323
Anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Service Role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
S3 Access Key: <access-key>
S3 Secret Key: <secret-key>
S3 Region: local

Update your .env file with the Anon key and Service Role key.

4. Link Subproject Migrations (If Using Pay/Discord)

If you have pay or discord repositories cloned, link their migrations:

cd ~/dev/mynatca/platform
 
# Link pay project
./scripts/link-project.sh
# When prompted:
# - Project name: pay
# - Path: /Users/[your-username]/dev/mynatca/pay
# - Schema: pay
# - Seed script: ./scripts/seed.sh
 
# Link discord project (if applicable)
./scripts/link-project.sh
# When prompted:
# - Project name: discord
# - Path: /Users/[your-username]/dev/mynatca/discord
# - Schema: discord
# - Seed script: (leave empty if no seed script)

This creates:

  • Symlinks to subproject migrations in platform/supabase/migrations/
  • Registry entry in .linked-projects.json
  • Orchestration for seeding workflows

5. Database Reset and Seed

cd ~/dev/mynatca/platform
./scripts/db-refresh.sh

This single command:

  1. Resets database (applies ALL migrations from platform + linked projects)
  2. Seeds platform data (~34,982 members from production)
  3. Runs seed scripts for all linked projects

Expected output:

=== MyNATCA Database Refresh ===

Step 1: Resetting database (applying all migrations)...
Applying migration 00000000000001_baseline_platform_schema.sql...
Applying migration 00000000000001_baseline_pay_schema.sql...
Applying migration 00000000000001_baseline_discord_schema.sql...
✓ Database reset complete

Step 2: Seeding platform data (public schema)...
Seeding members... ✓ 34,982 members
Seeding facilities... ✓ 623 facilities
Seeding regions... ✓ 12 regions
Seeding positions... ✓ 1,247 positions
✓ Platform data seeded

Step 3: Seeding linked projects...
  Seeding pay (pay schema)...
  ✓ pay seed script completed

✓ Database refresh complete!

6. Install Git Hooks

cd ~/dev/mynatca/platform
./scripts/setup-git-hooks.sh

This installs:

  • post-checkout - Updates symlinks when switching branches
  • post-merge - Updates symlinks after pulling changes
  • pre-commit - Enforces branch protection (blocks commits to main/staging)

7. Start Development Server

cd ~/dev/mynatca/platform
npm run dev

Platform API will start on http://localhost:1300

Verify it's working:

curl http://localhost:1300/api/health
# Expected: {"status":"healthy","service":"MyNATCA Platform Backend"}

Pay Project Setup (Optional)

Only complete this section if you're working on PayChecker.

1. Install Dependencies

cd ~/dev/mynatca/pay
 
# Create Python virtual environment
python3 -m venv .venv
 
# Activate virtual environment
source .venv/bin/activate
 
# Install Python dependencies
pip install -r requirements.txt
 
# Install Node dependencies (if applicable)
npm install

2. Configure Environment Variables

cd ~/dev/mynatca/pay
cp .env.example .env

Edit .env:

# Supabase (same as platform - uses shared database)
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_KEY=<same-as-platform-service-role-key>
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

# Application
NODE_ENV=development
PORT=1311

# Seed source (for pulling remote data)
SEED_SOURCE_URL=https://<staging-ref>.supabase.co
SEED_SOURCE_SERVICE_KEY=<ask-team>

3. Install Git Hooks

cd ~/dev/mynatca/pay
./scripts/setup-git-hooks.sh

4. Start Development Server

cd ~/dev/mynatca/pay
source .venv/bin/activate
npm run dev
# OR
uvicorn pay_checker.main:app --reload --port 1311

PayChecker API will start on http://localhost:1311

Verify it's working:

curl -H "X-Member-Number: 40671" http://localhost:1311/api/pay-periods
# Expected: List of pay periods

Discord Project Setup (Optional)

Only complete this section if you're working on the Discord bot.

1. Install Dependencies

cd ~/dev/mynatca/discord
npm install

2. Configure Environment Variables

cp .env.example .env

Edit .env:

# Discord Bot
DISCORD_TOKEN=<ask-team>
DISCORD_CLIENT_ID=<ask-team>
DISCORD_GUILD_ID=<ask-team>

# Supabase (same as platform)
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_KEY=<same-as-platform-service-role-key>

# Auth0 (for verification web interface)
AUTH0_DOMAIN=mynatca.us.auth0.com
AUTH0_CLIENT_ID=<ask-team>
AUTH0_CLIENT_SECRET=<ask-team>
AUTH0_SECRET=<generate-with-openssl-rand-hex-32>
AUTH0_BASE_URL=http://localhost:3002

# Application
NODE_ENV=development
PORT=3002

3. Install Git Hooks

cd ~/dev/mynatca/discord
./scripts/setup-git-hooks.sh

4. Start Development

cd ~/dev/mynatca/discord
npm run dev

Daily Development Workflow

Starting Your Day

# 1. Ensure Docker is running
docker ps
 
# 2. Pull latest changes from all repos you're working on
cd ~/dev/mynatca/platform && git pull
cd ~/dev/mynatca/pay && git pull  # if applicable
cd ~/dev/mynatca/discord && git pull  # if applicable
 
# 3. Start Supabase (from platform)
cd ~/dev/mynatca/platform
supabase start
 
# 4. Check if you need to refresh database
# (If there are new migrations or you want fresh data)
./scripts/db-refresh.sh
 
# 5. Start the services you're working on
# Platform
cd ~/dev/mynatca/platform && npm run dev
 
# Pay (in a new terminal)
cd ~/dev/mynatca/pay && source .venv/bin/activate && npm run dev
 
# Discord (in a new terminal)
cd ~/dev/mynatca/discord && npm run dev

Working on Multiple Branches

The symlink workflow handles multi-branch development gracefully:

# Platform on main branch
cd ~/dev/mynatca/platform
git checkout main
 
# Pay on feature branch
cd ~/dev/mynatca/pay
git checkout feature/new-calculator
 
# When you run db-refresh from platform, it uses:
# - Platform main branch migrations
# - Pay feature branch migrations
# - Discord current branch migrations
 
cd ~/dev/mynatca/platform
./scripts/db-refresh.sh
# Applies the MIX of migrations from different branches

Important: Be aware of which branches you're on in each repository.

Ending Your Day

# Stop services (Ctrl+C in each terminal)
 
# Optional: Stop Supabase (keeps data)
cd ~/dev/mynatca/platform
supabase stop
 
# Optional: Reset database completely (clears all data)
supabase db reset

Database Access

Supabase Studio (Recommended - GUI)

# Open in browser
open http://127.0.0.1:54323

Browse tables, run queries, view logs, and manage storage.

psql (Command Line)

# Connect to database
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres
 
# Useful commands:
\dt public.*      # List public schema tables
\dt pay.*         # List pay schema tables
\dt discord.*     # List discord schema tables
\d public.members # Describe members table
\q                # Quit

Quick SQL Queries

# Via Supabase CLI
supabase db query "SELECT COUNT(*) FROM public.members"
supabase db query "SELECT COUNT(*) FROM pay.shifts"
 
# Via psql
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \
  -c "SELECT COUNT(*) FROM public.members"

Creating New Migrations

Platform Migrations (Public Schema)

cd ~/dev/mynatca/platform
 
# Option 1: Make changes in Supabase Studio, then generate migration
supabase db diff -f add_new_feature
 
# Option 2: Write migration manually
# Create file: supabase/migrations/YYYYMMDDHHmmss_description.sql
 
# Test the migration
supabase db reset
 
# Commit the migration
git add supabase/migrations/
git commit -m "Add migration for new feature"

Pay Migrations (Pay Schema)

cd ~/dev/mynatca/pay
 
# Create migration in pay repository
supabase db diff -f add_pay_tracking_feature
 
# This creates: pay/supabase/migrations/YYYYMMDDHHmmss_add_pay_tracking_feature.sql
 
# Git hook automatically creates symlink in platform/supabase/migrations/
 
# Test from platform (all migrations run from platform)
cd ~/dev/mynatca/platform
supabase db reset

Discord Migrations (Discord Schema)

cd ~/dev/mynatca/discord
 
# Create migration in discord repository
supabase db diff -f add_verification_logging
 
# Git hook automatically creates symlink in platform/supabase/migrations/
 
# Test from platform
cd ~/dev/mynatca/platform
supabase db reset

Seeding Custom Test Data

Platform Data

Platform data is automatically seeded from production/staging via seed:from-remote:

cd ~/dev/mynatca/platform
npm run seed:from-remote  # Pull ~34,982 members from remote
npm run seed:dry-run      # Preview without applying

Pay Test Data

Option 1: SQL Files (Recommended for Simple Data)

cd ~/dev/mynatca/pay
 
# Create a custom seed file
cat > supabase/seeds/50_my_test_shifts.sql << 'EOF'
-- My custom test shifts
INSERT INTO pay.shifts (
    membernumber,
    pp_id,
    shift_date,
    start_time,
    end_time,
    type,
    notes,
    created_by
) VALUES (
    '40671',
    '202524',
    '2025-11-12',
    '2025-11-12 08:00:00',
    '2025-11-12 16:00:00',
    'regular',
    'Test shift',
    '40671'
) ON CONFLICT (membernumber, shift_date, pp_id) WHERE deleted_at IS NULL DO NOTHING;
EOF
 
# Next db-refresh will automatically execute this file
cd ~/dev/mynatca/platform
./scripts/db-refresh.sh

Option 2: Python Scripts (For Complex/Dynamic Data)

See pay/scripts/dev/README.md for creating custom Python seed scripts.

Troubleshooting

Supabase Won't Start

Port conflicts:

# Find and kill processes using ports
lsof -ti:54321,54322,54323 | xargs kill -9
 
# Or stop any running Supabase instances
cd ~/dev/mynatca/platform
supabase stop

Docker not running:

# Start Docker Desktop and wait for it to fully start
open -a Docker
# Wait for Docker icon in menu bar to show "running"

Migrations Fail

Schema doesn't exist:

# Ensure migrations are linked
cd ~/dev/mynatca/platform
./scripts/link-project.sh  # Re-link if needed
 
# Verify symlinks exist
ls -la supabase/migrations/
 
# Check config.toml has schemas listed
grep "schemas =" supabase/config.toml

Migration conflicts:

# Reset database completely
cd ~/dev/mynatca/platform
supabase db reset
# This reapplies ALL migrations from scratch

Seed Script Fails

Foreign key constraint violations:

# Ensure migrations ran first
cd ~/dev/mynatca/platform
supabase db reset  # Runs migrations first
npm run seed:from-remote  # Then seeds

Platform data not seeding:

# Check environment variables
grep SEED_SOURCE_ .env
 
# Test seed script directly
npm run seed:dry-run  # Preview without applying

Git Hooks Not Working

Symlinks not updating:

# Re-install git hooks
cd ~/dev/mynatca/platform
./scripts/setup-git-hooks.sh
 
# Manually update symlinks
./scripts/link-migrations.sh
 
# Verify hooks are installed
ls -la .git/hooks/post-checkout
ls -la .git/hooks/post-merge

Pay Seed Not Running

Pay seed script not executing during db-refresh:

# Check .linked-projects.json exists
cat ~/dev/mynatca/platform/.linked-projects.json
 
# Verify pay is registered
grep "pay" ~/dev/mynatca/platform/.linked-projects.json
 
# Re-link if needed
cd ~/dev/mynatca/platform
./scripts/link-project.sh

Pay seed script fails:

# Check script is executable
chmod +x ~/dev/mynatca/pay/scripts/seed.sh
 
# Run manually to see errors
cd ~/dev/mynatca/pay
./scripts/seed.sh

Python Virtual Environment Issues

# Recreate virtual environment
cd ~/dev/mynatca/pay
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Database Connection Issues

Can't connect to database:

# Verify Supabase is running
supabase status
 
# Restart Supabase
supabase stop
supabase start
 
# Check Docker containers
docker ps | grep supabase

Quick Reference

Essential Commands

# Supabase
supabase start              # Start local Supabase
supabase stop               # Stop Supabase (keep data)
supabase db reset           # Reset DB and apply migrations
supabase migration list     # Show migration status
supabase db diff -f <name>  # Create new migration
 
# Database Refresh (Platform)
./scripts/db-refresh.sh     # Reset DB + seed all projects
 
# Seeding
npm run seed:from-remote    # Seed from staging/production (platform)
npm run seed:dry-run        # Preview seed (platform)
 
# Development Servers
npm run dev                 # Start dev server (most projects)
uvicorn pay_checker.main:app --reload  # Pay (alternative)
 
# Database Access
open http://127.0.0.1:54323  # Supabase Studio
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres

File Locations

Platform:

  • Migrations: platform/supabase/migrations/
  • Seeds: Via seed:from-remote script
  • Env: platform/.env

Pay:

  • Migrations: pay/supabase/migrations/ (symlinked to platform)
  • Python seeds: pay/scripts/dev/*.py
  • SQL seeds: pay/supabase/seeds/*.sql
  • Env: pay/.env

Discord:

  • Migrations: discord/supabase/migrations/ (symlinked to platform)
  • Env: discord/.env

Important URLs

  • Platform API: http://localhost:1300
  • PayChecker API: http://localhost:1311
  • Discord Bot: http://localhost:3002
  • Supabase Studio: http://localhost:54323
  • Supabase API: http://localhost:54321

Next Steps

Getting Help

  • Check existing documentation in each project's docs/ folder
  • Platform issues: See platform/docs/ and platform/scripts/README.md
  • Pay issues: See pay/docs/seed-data.md and pay/scripts/README.md
  • Discord issues: See discord/CLAUDE.md
  • Ask in the dev Slack channel
Platform IntegrationEnvironment Variables