Quick Reference Guide

Common tasks and where to find what you need.

Quick Links

• Environment URLs & Costs - All environment URLs and infrastructure costs
• Technology Stack - Complete list of technologies and versions
• CI/CD Pipeline - How deployments work

Adding Environment Variables

Where it fits: Environment variables flow from env.deploy.yml → Scripts → GitHub Actions → Everywhere

Steps:

1. Add to infra/deploy/env.deploy.yml:

   DEV:
     server:
       MY_NEW_VAR: 'value' # Plain value
       MY_SECRET: 'from_secrets' # Auto-generates DEV_SERVER_MY_SECRET

2. Test locally:

   cd infra/deploy
   # See what secrets are needed
   node scripts/generate-env-files.js DEV --list-secrets
   
   # Test env generation
   node scripts/generate-env-files.js DEV --server --dry-run

3. Add secret to GitHub if needed

Key Scripts:

• generate-env-files.js - Creates .env files from env.deploy.yml
• extract-config.js - Extracts terraform vars, secrets list, documentation

Learn more: CI/CD Pipeline

Creating a New API Endpoint

Where it fits: Routes → Controller → Service → Database

Steps:

1. Create controller in apps/server/app/controllers/YourController.ts
2. Add route in apps/server/start/routes.ts
3. Add validation in apps/server/app/validators/
4. Test with: curl http://localhost:3333/api/your-endpoint

Conventions:

• RESTful naming: GET /events, POST /events, GET /events/:id
• Controllers handle HTTP logic only
• Business logic goes in services

Learn more: Controllers & Routing

Adding a Frontend Component

Where it fits: Component → Page → Route

React App (apps/webapp/):

1. Create component in src/components/
2. Use in pages under src/routes/
3. Add to route if new page

Conventions:

• Use TypeScript interfaces for props
• Keep components pure when possible
• Co-locate styles with components

Learn more: Component Library

Database Changes

Where it fits: Migration → Model → Controller

Steps:

1. Create migration:

   cd apps/server
   node ace make:migration create_events_table

2. Run migration:

   npm run migration:run

3. Create/update model in apps/server/app/models/

Conventions:

• Plural table names: users, events
• Singular model names: User, Event
• Always include timestamps

Learn more: Database Setup

Deploying Changes

Where it fits: Your code → GitHub → Actions → Cloud

Automatic deployment on push to:

• develop → Development environment
• qa → QA environment
• main → Production (requires approval)

Manual deployment:

# Never needed for normal work - GitHub Actions handles it
# But if you must: see deployment docs

Learn more: CI/CD Pipeline

Debugging Issues

Backend Debugging

Check logs:

# Local development
npm run dev:server
# Look at console output

# Production
# Check GitHub Actions logs
# SSH to server: docker compose logs server

Common issues:

• Database connection: Check DB_HOST in .env
• Port conflicts: Change PORT in .env

Frontend Debugging

Browser DevTools:

1. Network tab: Check API calls
2. Console: JavaScript errors
3. React DevTools: Component state

Common issues:

• CORS errors: Check VITE_API_URL
• Build errors: Clear .turbo cache

Learn more: Troubleshooting

Working with Docker

Local services (PostgreSQL, Redis, Caddy):

cd infra/local_dev

# Start
docker compose up -d

# Stop
docker compose down

# Reset (warning: deletes data)
docker compose down -v

Service locations:

• PostgreSQL: localhost:5433
• Redis: localhost:6379
• Caddy: https://*.jubiloop.localhost

Learn more: Local Infrastructure

Git Workflow

Creating branches:

# Traditional approach:
git checkout -b feature/sc-123-description

# Using git worktrees (recommended for parallel work):
./scripts/worktree.sh feature/sc-123-description

Daily workflow:

# Start of day
git checkout develop
git pull origin develop
git checkout -b feature/sc-123-new-feature

# Before pushing
git add .
git commit -m "[sc-123] add new feature"
git push origin feature/sc-123-new-feature

Working on multiple features (with worktrees):

# Create worktrees for parallel development
./scripts/worktree.sh feature/sc-100-api-feature
./scripts/worktree.sh feature/sc-101-ui-feature

# Switch between them
./scripts/worktree-switch.sh feature/sc-100-api-feature

# List all worktrees
./scripts/worktree-list.sh

# Clean up when done
./scripts/worktree-remove.sh feature/sc-100-api-feature

Learn more:

• Development Workflow
• Git Worktrees

Code Organization

apps/
├── server/          # Backend API (AdonisJS)
│   ├── app/        # Controllers, models, validators
│   ├── config/     # Configuration files
│   └── start/      # Routes and bootstrapping
├── webapp/          # Web application (React)
│   ├── src/        # Components, routes, stores
│   └── public/     # Static assets
└── marketing/       # Marketing site (Next.js)
    ├── src/        # Pages and components
    └── public/     # Static assets

Learn more: Monorepo Structure

Getting Help

1. Check documentation - You're here!
2. Search codebase - Often the best examples
3. Check Shortcut - Similar tasks might have notes
4. Ask your teammate - When stuck

Most Used Commands

# Development
npm run dev              # Start everything
npm run dev:server       # Backend only
npm run dev:webapp       # Frontend only

# Database
npm run migration:run    # Run migrations
npm run migration:rollback # Rollback
npm run db:seed         # Seed data

# Code quality
npm run lint            # Check code style
npm run format          # Auto-fix formatting
npm run test           # Run tests

# Build
npm run build          # Build everything
npm run build:server   # Backend only
npm run build:webapp   # Frontend only

# Git Worktrees (for parallel development)
./scripts/worktree.sh feature/name     # Create worktree
./scripts/worktree-list.sh            # List all worktrees
./scripts/worktree-switch.sh feature  # Switch to worktree
./scripts/worktree-remove.sh feature  # Remove worktree

Key Files to Know

• env.deploy.yml - All environment configuration
• turbo.json - Monorepo task configuration
• .github/workflows/ - CI/CD pipelines
• docker-compose.yml - Local services
• apps/server/start/routes.ts - API routes
• apps/webapp/src/routes/ - Frontend routes