Contributing

Development model

Local development uses a single shared PostgreSQL container and one database per repository clone.

• The main checkout typically uses .env and POSTGRES_DB=aacworkflow
• Each Git worktree uses its own .env.worktree
• Every clone connects to the same PostgreSQL host: localhost:5432
• Isolation is at the database level, not by running a separate Docker Compose project
• Backend and frontend ports are still unique per worktree

Prerequisites

• Node.js v20+
• pnpm v10.28+
• Go v1.26+
• Docker

Initial setup

Main checkout

cp .env.example .env
make setup-main

make setup-main:

• Installs JavaScript dependencies via pnpm install
• Ensures the shared PostgreSQL container is running
• Creates the app database if it doesn't exist
• Runs all migrations for this database

Running the app:

make start-main

Worktree

From the worktree directory:

make worktree-env
make setup-worktree

Running the worktree app:

make start-worktree

Daily process

Main checkout

make start-main
make stop-main
make check-main

Feature worktree

git worktree add ../aacworkflow-feature -b feat/my-change main
cd ../aacworkflow-feature
make worktree-env
make setup-worktree
make start-worktree

Day-to-day:

make start-worktree
make stop-worktree
make check-worktree

Running main and worktree simultaneously

Both clones share the same PostgreSQL container but use different databases and ports:

Commands

# Frontend (all commands go through Turborepo)
pnpm install
pnpm dev:web          # Next.js dev server (port 3000)
pnpm dev:desktop      # Electron dev (electron-vite, HMR)
pnpm build            # Build all frontend apps
pnpm typecheck        # TypeScript check
pnpm lint             # ESLint
pnpm test             # TS tests (Vitest)

# Backend (Go)
make dev              # Run Go server (port 8080)
make daemon           # Run local daemon
make build            # Build server + CLI binaries
make test             # Go tests
make sqlc             # Regenerate sqlc code
make migrate-up       # Run database migrations
make migrate-down     # Rollback migrations

Testing

Run all local checks:

make check

This runs:

1. TypeScript type checking
2. TypeScript unit tests
3. Go tests
4. Playwright E2E tests

Troubleshooting

Missing env file

Create the expected env file:

# Main checkout
cp .env.example .env

# Worktree
make worktree-env

Check which database the clone is using

cat .env           # or .env.worktree

Look for POSTGRES_DB, DATABASE_URL, PORT, FRONTEND_PORT.

List all local databases

docker compose exec -T postgres psql -U aacworkflow -d postgres \
  -At -c "select datname from pg_database order by datname;"

Destructive reset

Stop PostgreSQL while preserving local databases:

make db-down

Reset only the current clone's database (drops POSTGRES_DB, recreates it, re-runs all migrations). Other worktree databases are not affected.

make stop
make db-reset
make start

make db-reset refuses to run if DATABASE_URL points to a remote host.

Full wipe of all local PostgreSQL data:

docker compose down -v

Warning: This deletes the shared Docker volume and all databases. You'll need to re-run make setup-main or make setup-worktree afterward.