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/your-endpoint # No /api prefix — routes mount at subdomain root

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:

# Docker Stack
npm run dev:stack:logs
docker logs jubiloop_dev_server

# Host-mode (infra-only)
npm run dev -- --filter=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

Docker Stack (primary):

npm run dev:stack:up      # Start all services in background
npm run dev:stack:down    # Stop all services
npm run dev:stack:logs    # Stream logs
npm run dev:stack:restart # Restart
npm run dev:stack:rebuild # Rebuild after package changes

Running commands inside the stack:

docker exec -it jubiloop_dev_server node ace test
docker exec -it jubiloop_dev_server node ace test --suite unit
docker exec -it jubiloop_dev_server node ace migration:run
docker exec -it jubiloop_dev_postgres psql -U postgres -d jubiloop_dev_db
docker exec -it jubiloop_dev_redis redis-cli

Infra-only (alternative):

cd infra/local_dev
docker compose -f docker-compose.infra.yml up -d    # Start
docker compose -f docker-compose.infra.yml down     # Stop
docker compose -f docker-compose.infra.yml logs -f  # Logs

Service locations:

Service	URL / Port
Web App	https://app.jubiloop.localhost
API	https://api.jubiloop.localhost
Marketing	https://jubiloop.localhost
UI Prototype	https://lab.jubiloop.localhost
Docs	https://docs.jubiloop.localhost
PostgreSQL	localhost:5433
Redis	localhost:6379

Learn more: Local Development Setup

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

# Docker Stack (recommended)
npm run dev:stack:up        # Start everything in background
npm run dev:stack:down      # Stop
npm run dev:stack:logs      # View logs
npm run dev:stack:rebuild   # Rebuild after package changes
npm run dev:tui             # Interactive TUI dashboard

# Run individual apps (host-mode / infra-only)
npm run dev -- --filter=server    # Backend only
npm run dev -- --filter=webapp    # Frontend only
npm run dev -- --filter=marketing # Marketing only

# Database
npm run migration:run    # Run migrations
npm run migration:rollback # Rollback (last batch only)
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