bert.hausmans
5d4132785f
Replaces the bootstrap-from-scratch document (Step 2 told readers to run 'composer create-project laravel/laravel api' on an existing codebase) with a continue-existing-project guide. Scope: prerequisites, first-time setup (clone + install + .env + migrate), daily workflow (three terminals + optional queue worker), env-config explained, common tasks (test/migrate/route:list/build), documentation reference linking the dev-docs/ canonical files, troubleshooting. Drops apps/portal references throughout (single SPA at port 5174). Drops dual-port SANCTUM_STATEFUL_DOMAINS guidance. Replaces .cursor/ instructions reference with /CLAUDE.md as auto-loaded source of truth.
5.6 KiB
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) |
| 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:
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.
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.