Contributing

Development model

Local development uses one shared PostgreSQL container and one database per checkout.

• The main checkout usually uses .env and POSTGRES_DB=concierto.
• Each Git worktree uses its own .env.worktree.
• Every checkout connects to the same PostgreSQL host: localhost:5432.
• Isolation happens at the database level, not by starting 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

First-time setup

Main checkout

cp .env.example .env
make setup-main

What make setup-main does:

• Installs JavaScript dependencies with pnpm install
• Ensures the shared PostgreSQL container is running
• Creates the application database if it does not exist
• Runs all migrations against that database

Start the app:

make start-main

Worktree

From the worktree directory:

make worktree-env
make setup-worktree
make start-worktree

Daily workflow

# Main checkout
make start-main
make stop-main
make check-main

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

Running main and a worktree simultaneously

This is a first-class workflow. Both checkouts use the same PostgreSQL container but 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 server           # 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 TypeScript typecheck, TypeScript unit tests, Go tests, and Playwright E2E tests.

Troubleshooting

Missing env file

cp .env.example .env   # main checkout
make worktree-env      # worktree

Check which database a checkout uses

cat .env           # or .env.worktree

Look for POSTGRES_DB, DATABASE_URL, PORT, FRONTEND_PORT.

Reset the current checkout's database

make stop
make db-reset
make start

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

Wipe all local PostgreSQL data

docker compose down -v

Warning: this deletes the shared Docker volume and all databases. After that you must run make setup-main or make setup-worktree again.

See also

• Architecture: how the platform fits together
• Conventions: naming, i18n glossary, Chinese voice guide