crewli/dev-docs/SETUP.md

Crewli — Working in this repo

A guide for developers continuing work on the Crewli codebase. Assumes you've cloned the repo and have basic terminal familiarity.

Prerequisites

Install these once before starting:

Tool	Version	Install (macOS via Homebrew)
PHP	8.4	brew install php@8.4 && brew link php@8.4
Composer	2.x	brew install composer
Node.js	20 LTS	brew install fnm && fnm install 20 && fnm use 20
pnpm	9.x	npm install -g pnpm
Docker Desktop	latest	https://www.docker.com/products/docker-desktop/

Verify:

php -v          # 8.4.x
composer -V     # 2.x
node -v         # v20.x
pnpm -v         # 9.x or 10.x
docker -v       # any recent version

First-time setup

From the repo root:

# 1. Backend dependencies
cd api && composer install

# 2. Frontend dependencies
cd ../apps/app && pnpm install

# 3. Backend env file
cd ../../api
cp .env.example .env
php artisan key:generate

# 4. Frontend env file
cd ../apps/app
cp .env.example .env.local

# 5. Start Docker services (MySQL, Redis, Mailpit)
cd ..
make services

# 6. Database setup
cd api
php artisan migrate --seed

# 7. Frontend post-install (icon build + MSW worker)
cd ../apps/app
pnpm run build:icons
pnpm run msw:init

# 8. Verify everything works
cd ../../api
php artisan test

If php artisan test is green, you're ready.

Daily workflow

Three terminal tabs, plus an optional fourth for the queue worker:

Terminal	Command	Where it runs	Port
1. Services	make services (from repo root)	Docker	3306 (MySQL), 6379 (Redis), 8025 (Mailpit), 8200 (GlitchTip)
2. API	make api (from repo root)	Laravel dev server	8000
3. SPA	make app (from repo root)	Vite dev server	5174
4. Queue worker (optional)	cd api && php artisan queue:listen redis --queue=emails	Local PHP	n/a

Web UIs available once make services is up:

Service	URL
Mailpit	http://localhost:8025
GlitchTip	http://localhost:8200 (admin UI; first boot ~60s while migrations run)

The queue worker is only needed when you're triggering email flows (registration, password reset, email change, invitations). Routine UI work doesn't require it.

Stop services when done: make services-stop.

Environment variables

api/.env

The defaults from .env.example cover local development. Key entries:

DB_DATABASE=crewli
DB_USERNAME=crewli
DB_PASSWORD=secret
QUEUE_CONNECTION=redis
SESSION_DOMAIN=localhost
FRONTEND_APP_URL=http://localhost:5174
SANCTUM_STATEFUL_DOMAINS=localhost:5174
APP_URL=http://localhost:8000

For production deployment (registered domain crewli.app):

APP_URL=https://api.crewli.app
FRONTEND_APP_URL=https://crewli.app
SESSION_DOMAIN=.crewli.app
SANCTUM_STATEFUL_DOMAINS=crewli.app

crewli.nl is reserved for a future marketing site only — not the application.

apps/app/.env.local

VITE_API_URL=http://localhost:8000
VITE_APP_NAME="Crewli"

For production: VITE_API_URL=https://api.crewli.app.

docker/glitchtip/.env

Generated by copying docker/glitchtip/.env.example. Dev defaults are functional out of the box — no edits needed for make services. See GLITCHTIP.md for first-boot steps (creating the superuser, creating the two projects, copying DSNs to 1Password).

Common tasks

Run tests

# Backend (PHPUnit, all tests)
cd api && php artisan test

# Backend (specific filter)
cd api && php artisan test --filter=ShiftTest

# Backend (with coverage)
cd api && php artisan test --coverage

# Frontend (Vitest, all tests)
cd apps/app && pnpm test

# Frontend (typecheck)
cd apps/app && pnpm typecheck

# Frontend (lint)
cd apps/app && pnpm lint

Database reset

cd api && php artisan migrate:fresh --seed

This drops all tables, re-runs migrations, and re-seeds. Useful when schema changes or seeders are updated.

Inspect routes

cd api && php artisan route:list --path=api/v1

Build for production

cd apps/app && pnpm build

Output lands in apps/app/dist/. The deploy.sh script handles the rest for VPS deploys.

Static analysis (optional)

cd api && composer analyse        # Larastan / PHPStan level 6
cd api && composer rector --dry-run  # Rector findings

Documentation reference

The dev-docs/ directory is the developer source of truth. The most-used files:

File	Purpose
/CLAUDE.md	Project conventions, vibe-coding principles, Vuexy-first decision tree (auto-loaded by Claude Code)
dev-docs/SCHEMA.md	Database schema (current version v2.x, kept in sync with migrations)
dev-docs/API.md	API contract
dev-docs/AUTH_ARCHITECTURE.md	Auth design (httpOnly cookies, MFA, impersonation, portal tokens)
dev-docs/CLAUDE_CODE_TOOLING.md	The .claude/ deterministic guard-rail layer (hooks, subagent, slash commands)
dev-docs/VUEXY_COMPONENTS.md	Vuexy component registry — consult before writing any frontend
dev-docs/BACKLOG.md	Tracked tech debt and follow-ups
dev-docs/ARCH-*.md	Architecture decisions per workstream (consolidation, form builder, bindings, API validation)

The docs/ directory (separate from dev-docs/) is end-user VitePress documentation in Dutch.

Troubleshooting

MySQL connection refused

docker ps                # check containers are up
make services-stop && make services   # restart

Port 8000 already in use

Something else is bound to port 8000. Find it: lsof -i :8000. Kill it or change make api to use another port.

Frontend TypeScript errors after pulling main

cd apps/app
pnpm install      # picks up new dependencies
pnpm typecheck    # confirm clean

Queue worker not picking up jobs

Confirm Redis is running: docker ps | grep redis. If yes, restart the queue worker — long-running listeners can drift after long idle periods.

Test suite is slow

PHPUnit defaults to a single process. Parallel: cd api && php artisan test --parallel.