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:

```bash
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:

```bash
# 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) |
| 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 |

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:

```env
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`):

```env
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`

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

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

## Common tasks

### Run tests

```bash
# 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

```bash
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

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

### Build for production

```bash
cd apps/app && pnpm build
```

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

### Static analysis (optional)

```bash
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

```bash
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

```bash
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`.