docs: design-document v1.8, dev-docs restructure, VitePress user docs scaffold, backlog update
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
286
dev-docs/SETUP.md
Normal file
286
dev-docs/SETUP.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Crewli - Setup Guide
|
||||
|
||||
This guide walks you through setting up the Crewli project from scratch.
|
||||
|
||||
## Cursor AI Configuration
|
||||
|
||||
The project includes comprehensive AI instructions:
|
||||
|
||||
```
|
||||
.cursor/
|
||||
├── instructions.md # Quick start and common prompts
|
||||
├── ARCHITECTURE.md # System design and database schema
|
||||
└── rules/
|
||||
├── 001_workspace.mdc # Project structure and conventions
|
||||
├── 100_laravel.mdc # Laravel API patterns
|
||||
├── 101_vue.mdc # Vue + Vuexy patterns
|
||||
└── 200_testing.mdc # Testing strategies
|
||||
```
|
||||
|
||||
**Read these files first!** They contain everything Cursor needs to generate code correctly.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install these before starting:
|
||||
|
||||
### macOS (Homebrew)
|
||||
|
||||
```bash
|
||||
# PHP 8.3
|
||||
brew install php@8.3
|
||||
brew link php@8.3
|
||||
|
||||
# Composer
|
||||
brew install composer
|
||||
|
||||
# Node.js (via fnm)
|
||||
brew install fnm
|
||||
fnm install 20
|
||||
fnm use 20
|
||||
|
||||
# pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# Docker Desktop
|
||||
# Download from: https://www.docker.com/products/docker-desktop/
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
php -v # Should show 8.3.x
|
||||
composer -V # Should show 2.x
|
||||
node -v # Should show v20.x
|
||||
pnpm -v # Should show 8.x or 9.x
|
||||
docker -v # Should show Docker version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Start Docker Services
|
||||
|
||||
```bash
|
||||
cd crewli
|
||||
make services
|
||||
```
|
||||
|
||||
This starts:
|
||||
- **MySQL 8.0** on port 3306
|
||||
- **Redis** on port 6379
|
||||
- **Mailpit** on port 8025 (email testing UI)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Laravel API
|
||||
|
||||
Open the project in Cursor and use this prompt:
|
||||
|
||||
```
|
||||
Create a new Laravel 12 project in the api/ folder.
|
||||
|
||||
Requirements:
|
||||
- Use the command: composer create-project laravel/laravel api
|
||||
- After creation, install Sanctum: composer require laravel/sanctum
|
||||
- Configure for API-only (we don't need web routes)
|
||||
- Set up CORS for localhost:5173, localhost:5174, localhost:5175
|
||||
- Use MySQL with these credentials:
|
||||
- Host: 127.0.0.1
|
||||
- Database: crewli
|
||||
- Username: crewli
|
||||
- Password: secret
|
||||
|
||||
Follow the conventions in .cursor/rules for code style.
|
||||
```
|
||||
|
||||
### Manual Alternative
|
||||
|
||||
```bash
|
||||
cd crewli
|
||||
composer create-project laravel/laravel api
|
||||
cd api
|
||||
composer require laravel/sanctum
|
||||
php artisan install:api
|
||||
```
|
||||
|
||||
Then configure `api/.env`:
|
||||
```env
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=crewli
|
||||
DB_USERNAME=crewli
|
||||
DB_PASSWORD=secret
|
||||
|
||||
FRONTEND_ADMIN_URL=http://localhost:5173
|
||||
FRONTEND_APP_URL=http://localhost:5174
|
||||
FRONTEND_PORTAL_URL=http://localhost:5175
|
||||
SANCTUM_STATEFUL_DOMAINS=localhost:5173,localhost:5174,localhost:5175
|
||||
SESSION_DOMAIN=localhost
|
||||
```
|
||||
|
||||
**Production (domain `crewli.app`):** set `APP_URL=https://api.crewli.app`, point `FRONTEND_ADMIN_URL` / `FRONTEND_APP_URL` / `FRONTEND_PORTAL_URL` to `https://admin.crewli.app`, `https://app.crewli.app`, and `https://portal.crewli.app`, and `SANCTUM_STATEFUL_DOMAINS=admin.crewli.app,app.crewli.app,portal.crewli.app` (hostnames only). Each SPA build should use `VITE_API_URL=https://api.crewli.app/api/v1`. Full template: `api/.env.example`. The product uses **`crewli.app`** only; **`crewli.nl`** is for a future public marketing site, not this API or SPAs.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Vuexy frontends (this repo)
|
||||
|
||||
This monorepo already contains three SPAs under `apps/`:
|
||||
|
||||
| Directory | Role | Typical Vuexy source |
|
||||
|-----------|------|----------------------|
|
||||
| `apps/admin/` | Super Admin | full-version (TypeScript) |
|
||||
| `apps/app/` | Organizer (main product) | full-version or customized starter |
|
||||
| `apps/portal/` | External portal (volunteers, token links) | stripped starter / custom layout |
|
||||
|
||||
If you ever need to re-copy from a Vuexy ZIP, use the paths above — not legacy `apps/band` or `apps/customers`.
|
||||
|
||||
```bash
|
||||
# Example only — adjust to your Vuexy download path
|
||||
cp -r ~/Downloads/vuexy/typescript-version/full-version/* apps/admin/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Configure SPAs
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
cd apps/admin && pnpm install
|
||||
cd ../app && pnpm install
|
||||
cd ../portal && pnpm install
|
||||
```
|
||||
|
||||
### Create Environment Files
|
||||
|
||||
**apps/admin/.env.local**
|
||||
```env
|
||||
VITE_API_URL=http://localhost:8000/api/v1
|
||||
VITE_APP_NAME="Crewli Admin"
|
||||
```
|
||||
|
||||
**apps/app/.env.local**
|
||||
```env
|
||||
VITE_API_URL=http://localhost:8000/api/v1
|
||||
VITE_APP_NAME="Crewli Organizer"
|
||||
```
|
||||
|
||||
**apps/portal/.env.local**
|
||||
```env
|
||||
VITE_API_URL=http://localhost:8000/api/v1
|
||||
VITE_APP_NAME="Crewli Portal"
|
||||
```
|
||||
|
||||
### Dev server ports
|
||||
|
||||
From the repo root, `make admin`, `make app`, and `make portal` start Vite on **5173**, **5174**, and **5175** respectively. If you run `pnpm dev` manually, configure the same ports in each app’s `vite.config.ts` under `server.port`.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: API client in SPAs
|
||||
|
||||
`apps/admin/src/lib/api-client.ts`, `apps/app/src/lib/api-client.ts`, and `apps/portal/src/lib/api-client.ts` share the same pattern: `VITE_API_URL` base, Bearer token from the `accessToken` cookie, 401 → clear cookies and redirect to `/login`. Build new composables on `apiClient`; keep Vuexy `useApi` for template demos only.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Create database schema
|
||||
|
||||
Implement migrations from the canonical schema, not a legacy intranet model:
|
||||
|
||||
- **`docs/SCHEMA.md`** — table list, columns, indexes
|
||||
- **`.cursor/ARCHITECTURE.md`** — overview and relationships
|
||||
- **`.cursor/rules/103_database.mdc`** — ULIDs, soft deletes, index rules
|
||||
|
||||
**Checked-in foundation (this repo):** Laravel defaults (`users`, `cache`, `jobs`) then `2026_04_07_*` migrations: Sanctum tokens → Spatie permission → activity log → `organisations` → `organisation_user` → `events` → `user_invitations` → `event_user_roles`. New modules should append migrations with a later timestamp in dependency order.
|
||||
|
||||
Typical next expansion order from `103_database.mdc`: festival sections, time slots, persons, shifts, …
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
cd api && php artisan migrate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Start development
|
||||
|
||||
Open separate terminals (or use the Makefile from the repo root):
|
||||
|
||||
```bash
|
||||
# Tab 1: Services (Docker)
|
||||
make services
|
||||
|
||||
# Tab 2: Laravel API
|
||||
make api
|
||||
|
||||
# Tab 3: Admin SPA (optional)
|
||||
make admin
|
||||
|
||||
# Tab 4: Organizer SPA (optional)
|
||||
make app
|
||||
|
||||
# Tab 5: Portal SPA (optional)
|
||||
make portal
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Building features
|
||||
|
||||
Use Cursor with **`CLAUDE.md`** and **`.cursor/instructions.md`**. Example directions:
|
||||
|
||||
### Authentication
|
||||
|
||||
```
|
||||
Wire Sanctum API auth: login, logout, me; form requests; API resources; Vue apps use axios + token storage (see .cursor/rules).
|
||||
```
|
||||
|
||||
### Events module (Crewli)
|
||||
|
||||
```
|
||||
Events nested under organisations: ULID PK, OrganisationScope, policies, EventResource, feature tests (200/401/403/422).
|
||||
```
|
||||
|
||||
### Portal token flow
|
||||
|
||||
```
|
||||
Portal token middleware and routes for artist/supplier contexts; document links on https://portal.crewli.app/... (see .cursor/rules/102_multi_tenancy.mdc).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MySQL Connection Refused
|
||||
```bash
|
||||
# Check if Docker is running
|
||||
docker ps
|
||||
|
||||
# Restart services
|
||||
make services-stop
|
||||
make services
|
||||
```
|
||||
|
||||
### CORS Errors
|
||||
Check `api/config/cors.php` allows your frontend origins.
|
||||
|
||||
### Vuexy TypeScript Errors
|
||||
```bash
|
||||
cd apps/admin
|
||||
pnpm install
|
||||
pnpm type-check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
1. Services running (Docker)
|
||||
2. Laravel API configured and migrated
|
||||
3. SPAs installed (`apps/admin`, `apps/app`, `apps/portal`)
|
||||
4. Environment files for API + each SPA
|
||||
5. Authentication and organisation switching
|
||||
6. Events, sections, time slots, shifts
|
||||
7. Persons, crowd types, portal flows
|
||||
8. Accreditation, briefings, operational modules per roadmap in `.cursor/instructions.md`
|
||||
Reference in New Issue
Block a user