multica/LOCAL_DEVELOPMENT.md

Local Development Guide

This guide documents the intended local development workflow for Multica.

It covers:

• first-time setup
• day-to-day development in the main checkout
• isolated worktree development
• the shared PostgreSQL model
• testing and verification
• troubleshooting and destructive reset options

Development Model

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

• the main checkout usually uses .env and POSTGRES_DB=multica
• 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

This keeps Docker simple while still isolating schema and data.

Prerequisites

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

Important Rules

• The main checkout should use .env.
• A worktree should use .env.worktree.
• Do not copy .env into a worktree directory.

Why:

• the current command flow prefers .env over .env.worktree
• if a worktree contains .env, it can accidentally point back to the main database

Environment Files

Main Checkout

Create .env once:

cp .env.example .env

By default, .env points to:

POSTGRES_DB=multica
POSTGRES_PORT=5432
DATABASE_URL=postgres://multica:multica@localhost:5432/multica?sslmode=disable
PORT=8080
FRONTEND_PORT=3000

Worktree

Generate .env.worktree from inside the worktree:

make worktree-env

That generates values like:

POSTGRES_DB=multica_my_feature_702
POSTGRES_PORT=5432
PORT=18782
FRONTEND_PORT=13702
DATABASE_URL=postgres://multica:multica@localhost:5432/multica_my_feature_702?sslmode=disable

Notes:

• POSTGRES_DB is unique per worktree
• POSTGRES_PORT stays fixed at 5432
• backend and frontend ports are derived from the worktree path hash
• make worktree-env refuses to overwrite an existing .env.worktree

To regenerate a worktree env file:

FORCE=1 make worktree-env

First-Time Setup

Main Checkout

From the 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

Stop the app processes:

make stop-main

This does not stop PostgreSQL.

Worktree

From the worktree directory:

make worktree-env
make setup-worktree

What make setup-worktree does:

• uses .env.worktree
• ensures the shared PostgreSQL container is running
• creates the worktree database if it does not exist
• runs migrations against the worktree database

Start the worktree app:

make start-worktree

Stop the worktree app processes:

make stop-worktree

Recommended Daily Workflow

Main Checkout

Use the main checkout when you want a stable local environment for main.

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

Feature Worktree

Use a worktree when you want isolated data and separate app ports.

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

After that, day-to-day commands are:

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

Running Main and Worktree at the Same Time

This is a first-class workflow.

Example:

• main checkout
  • database: multica
  • backend: 8080
  • frontend: 3000
• worktree checkout
  • database: multica_my_feature_702
  • backend: generated worktree port such as 18782
  • frontend: generated worktree port such as 13702

Both checkouts use:

• the same PostgreSQL container
• the same PostgreSQL port: 5432

But they do not share application data, because each uses a different database.

Command Reference

Shared Infrastructure

Start the shared PostgreSQL container:

make db-up

Stop the shared PostgreSQL container:

make db-down

Important:

• make db-down stops the container but keeps the Docker volume
• your local databases are preserved

App Lifecycle

Main checkout:

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

Worktree:

make worktree-env
make setup-worktree
make start-worktree
make stop-worktree
make check-worktree

Generic targets for the current checkout:

make setup
make start
make stop
make check
make dev
make test
make migrate-up
make migrate-down

These generic targets require a valid env file in the current directory.

How Database Creation Works

Database creation is automatic.

The following commands all ensure the target database exists before they continue:

• make setup
• make start
• make dev
• make test
• make migrate-up
• make migrate-down
• make check

That logic lives in scripts/ensure-postgres.sh.

Testing

Run all local checks:

make check-main

Or from a worktree:

make check-worktree

This runs:

1. TypeScript typecheck
2. TypeScript unit tests
3. Go tests
4. Playwright E2E tests

Notes:

• Go tests create their own fixture data
• E2E tests create their own workspace and issue fixtures
• the check flow starts backend/frontend only if they are not already running

Local Codex Daemon

Run the local daemon:

make daemon

Normal flow:

1. start the daemon
2. open the pairing link it prints
3. choose the workspace in the browser
4. let the daemon register its local runtime

Debug shortcut:

• you can set MULTICA_WORKSPACE_ID in your env file
• this skips normal pairing
• treat it as a local shortcut, not the default workflow

Troubleshooting

Missing Env File

If you see:

Missing env file: .env

or:

Missing env file: .env.worktree

then create the expected env file first.

Main checkout:

cp .env.example .env

Worktree:

make worktree-env

Check Which Database a Checkout Uses

Inspect the env file:

cat .env
cat .env.worktree

Look for:

• POSTGRES_DB
• DATABASE_URL
• PORT
• FRONTEND_PORT

List All Local Databases in Shared PostgreSQL

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

Worktree Is Accidentally Using the Main Database

Check whether the worktree contains .env.

It should not.

The safe worktree setup is:

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

App Stops but PostgreSQL Keeps Running

That is expected.

• make stop
• make stop-main
• make stop-worktree

only stop backend/frontend processes.

To stop the shared PostgreSQL container:

make db-down

Destructive Reset

If you want to stop PostgreSQL and keep your local databases:

make db-down

If you want to wipe all local PostgreSQL data for this repo:

docker compose down -v

Warning:

• this deletes the shared Docker volume
• this deletes the main database and every worktree database in that volume
• after that you must run make setup-main or make setup-worktree again

Typical Flows

Stable Main Environment

cp .env.example .env
make setup-main
make start-main

Feature Worktree

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

Return to a Previously Configured Worktree

cd ../multica-feature
make start-worktree

Validate Before Pushing

Main checkout:

make check-main

Worktree:

make check-worktree