docs: add project README with cold-start guide and Docker reference

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 11:02:02 +00:00
parent c89d1879bf
commit d572f65684
1 changed files with 327 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,327 @@
+# L'Ami Fiduciaire
+
+Client management platform for fiduciary and accounting firms — built with Laravel 12, Vue 3, and Inertia.js.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Tech Stack](#tech-stack)
+- [Cold-Start Guide](#cold-start-guide)
+  - [Prerequisites](#prerequisites)
+  - [First-Time Setup](#first-time-setup)
+  - [Daily Development](#daily-development)
+  - [Stopping the Environment](#stopping-the-environment)
+- [Vite and Docker: The HMR Gotcha](#vite-and-docker-the-hmr-gotcha)
+- [Verification Checklist](#verification-checklist)
+- [Docker Command Reference](#docker-command-reference)
+- [Testing](#testing)
+- [Code Quality](#code-quality)
+- [Project Structure](#project-structure)
+- [Key Services](#key-services)
+- [License](#license)
+
+## Overview
+
+L'Ami Fiduciaire is a multi-tenant web platform that provides:
+
+- **Client management** — CRUD operations, legal forms, status tracking
+- **Dossier system** — folders with priorities, workflows, and document exchange
+- **Client portal** — token-based file uploads for external clients
+- **In-folder messaging** — communication threads within dossiers
+- **Activity logging** — full audit trail via Spatie Activity Log
+- **Two-factor authentication** — TOTP-based 2FA via Laravel Fortify
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | Laravel 12, PHP 8.4 |
+| Frontend | Vue 3, TypeScript, Inertia.js v2 |
+| Styling | Tailwind CSS 4, shadcn-vue |
+| Database | SQLite (dev) |
+| Cache/Queue/Session | Redis |
+| Email (dev) | Mailpit |
+| DevOps | Docker Compose via Laravel Sail |
+| Testing | Pest PHP 4 |
+
+## Cold-Start Guide
+
+### Prerequisites
+
+You need **only two things** installed on your machine:
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or Docker Engine + Docker Compose)
+- Git
+
+> **No local PHP, Node, Composer, or npm required.** Everything runs inside Docker.
+
+### First-Time Setup
+
+**1. Clone the repository**
+
+```bash
+git clone <repository-url> "l'ami fiduciaire"
+cd "l'ami fiduciaire"
+```
+
+**2. Create your environment file**
+
+```bash
+cp .env.example .env
+```
+
+**3. Install PHP dependencies (this also builds the Docker image)**
+
+```bash
+docker run --rm \
+    -u "$(id -u):$(id -g)" \
+    -v "$(pwd):/var/www/html" \
+    -w /var/www/html \
+    laravelsail/php84-composer:latest \
+    composer install --ignore-platform-reqs
+```
+
+**4. Start the containers**
+
+```bash
+./vendor/bin/sail up -d
+```
+
+**5. Generate the application key**
+
+```bash
+./vendor/bin/sail artisan key:generate
+```
+
+**6. Run database migrations and seeders**
+
+```bash
+./vendor/bin/sail artisan migrate --seed
+```
+
+**7. Install frontend dependencies and build assets**
+
+```bash
+./vendor/bin/sail npm install
+./vendor/bin/sail npm run build
+```
+
+**8. Open the application**
+
+Visit [http://localhost](http://localhost) in your browser.
+
+### Daily Development
+
+Start containers and the Vite dev server for hot-reload:
+
+```bash
+./vendor/bin/sail up -d
+./vendor/bin/sail npm run dev
+```
+
+Or use the all-in-one dev command that starts the server, queue worker, log viewer, and Vite simultaneously:
+
+```bash
+./vendor/bin/sail composer run dev
+```
+
+### Stopping the Environment
+
+```bash
+./vendor/bin/sail down
+```
+
+To stop and remove volumes (resets Redis data):
+
+```bash
+./vendor/bin/sail down -v
+```
+
+## Vite and Docker: The HMR Gotcha
+
+When running Vite inside a Docker container, **Hot Module Replacement (HMR) requires port 5173 to be exposed from the container to your host**. This is already configured in `compose.yaml`:
+
+```yaml
+ports:
+    - '${APP_PORT:-80}:80'
+    - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
+```
+
+### Common symptoms when HMR breaks
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Page loads but CSS/JS changes require full refresh | Vite dev server is not running | Run `./vendor/bin/sail npm run dev` |
+| Browser console shows WebSocket connection errors | Port 5173 is not forwarded or is in use | Check no other process uses port 5173, restart Sail |
+| `ERR_CONNECTION_REFUSED` on Vite assets | Vite is running but the container port mapping is missing | Verify `compose.yaml` has the 5173 port mapping |
+| Assets load from `public/build/` instead of Vite | A stale production build exists and Vite is not running | Delete `public/build/` and run `./vendor/bin/sail npm run dev` |
+
+### Key rule
+
+> **Always run `./vendor/bin/sail npm run dev` as a separate process** when developing. The Vite dev server must stay running alongside the Laravel container for HMR to work. If you use `sail composer run dev`, it handles this for you.
+
+### Custom port
+
+If port 5173 conflicts with another service, override it in your `.env`:
+
+```env
+VITE_PORT=5174
+```
+
+Then restart Sail.
+
+## Verification Checklist
+
+Run through this checklist after setup to confirm everything works:
+
+### Infrastructure
+
+- [ ] `./vendor/bin/sail ps` — shows `laravel.test`, `redis`, and `mailpit` running
+- [ ] [http://localhost](http://localhost) — loads the application without errors
+- [ ] [http://localhost:8025](http://localhost:8025) — Mailpit dashboard is accessible
+
+### Database
+
+- [ ] `./vendor/bin/sail artisan migrate:status` — all migrations show `Ran`
+- [ ] `./vendor/bin/sail artisan tinker --execute="echo App\Models\User::count();"` — returns a number (seeded users)
+
+### Frontend
+
+- [ ] `./vendor/bin/sail npm run dev` — Vite starts without errors on port 5173
+- [ ] Edit any `.vue` file — changes appear in the browser without full refresh (HMR works)
+- [ ] Browser DevTools console is free of errors
+
+### Cache and Queue
+
+- [ ] `./vendor/bin/sail artisan cache:clear` — completes without error (Redis is reachable)
+- [ ] `./vendor/bin/sail artisan queue:work --once` — processes a job or reports "No jobs" (queue connection works)
+
+### Tests
+
+- [ ] `./vendor/bin/sail test` — all tests pass
+
+## Docker Command Reference
+
+All commands use `./vendor/bin/sail` as the Docker entry point. You can create a shell alias for convenience:
+
+```bash
+alias sail='./vendor/bin/sail'
+```
+
+### Container management
+
+| Command | Description |
+|---------|-------------|
+| `sail up -d` | Start all containers in detached mode |
+| `sail down` | Stop and remove containers |
+| `sail down -v` | Stop containers and remove volumes |
+| `sail ps` | List running containers |
+| `sail logs -f` | Follow container logs |
+| `sail restart` | Restart all containers |
+
+### Laravel (Artisan)
+
+| Command | Description |
+|---------|-------------|
+| `sail artisan migrate` | Run pending migrations |
+| `sail artisan migrate:fresh --seed` | Reset database and seed |
+| `sail artisan db:seed` | Run database seeders |
+| `sail artisan tinker` | Open Laravel REPL |
+| `sail artisan cache:clear` | Clear application cache |
+| `sail artisan queue:work` | Start the queue worker |
+| `sail artisan pail` | Stream application logs |
+
+### Frontend (npm)
+
+| Command | Description |
+|---------|-------------|
+| `sail npm install` | Install Node dependencies |
+| `sail npm run dev` | Start Vite dev server with HMR |
+| `sail npm run build` | Build production assets |
+| `sail npm run build:ssr` | Build with server-side rendering |
+
+### Composer
+
+| Command | Description |
+|---------|-------------|
+| `sail composer install` | Install PHP dependencies |
+| `sail composer run dev` | Start all dev services concurrently |
+| `sail composer run test` | Run linter + test suite |
+
+### Shell access
+
+```bash
+sail shell        # Enter container as sail user
+sail root-shell   # Enter container as root
+```
+
+## Testing
+
+Run the full test suite (lint + Pest):
+
+```bash
+./vendor/bin/sail composer run test
+```
+
+Run only tests (skip linting):
+
+```bash
+./vendor/bin/sail test
+```
+
+Run a specific test file:
+
+```bash
+./vendor/bin/sail test tests/Feature/Auth/LoginTest.php
+```
+
+## Code Quality
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| Pint | `sail composer run lint` | PHP code formatting (PSR-12) |
+| ESLint | `sail npm run lint` | TypeScript/Vue linting + autofix |
+| Prettier | `sail npm run format` | Frontend code formatting |
+| Prettier check | `sail npm run format:check` | Verify formatting without changes |
+
+## Project Structure
+
+```text
+├── app/
+│   ├── Actions/          # Single-purpose action classes
+│   ├── Enums/            # PHP enums (status, types)
+│   ├── Http/             # Controllers, requests, middleware
+│   ├── Models/           # Eloquent models
+│   └── Observers/        # Model lifecycle hooks
+├── database/
+│   ├── factories/        # Test data factories
+│   ├── migrations/       # Database schema
+│   └── seeders/          # Seed data
+├── resources/js/
+│   ├── pages/            # Inertia page components (Vue)
+│   ├── layouts/          # Layout wrappers
+│   ├── components/ui/    # shadcn-vue components
+│   ├── composables/      # Vue composables
+│   └── types/            # TypeScript definitions
+├── routes/               # Laravel route definitions
+├── tests/
+│   ├── Feature/          # Integration tests
+│   └── Unit/             # Unit tests
+├── compose.yaml          # Docker Compose services
+├── vite.config.ts        # Vite + plugins configuration
+└── docs/                 # Detailed project documentation
+```
+
+## Key Services
+
+| Service | Internal Port | Host URL | Purpose |
+|---------|--------------|----------|---------|
+| Laravel | 80 | [http://localhost](http://localhost) | Application server |
+| Vite | 5173 | [http://localhost:5173](http://localhost:5173) | HMR dev server |
+| Redis | 6379 | — | Cache, sessions, queues |
+| Mailpit SMTP | 1025 | — | Catches outbound email |
+| Mailpit UI | 8025 | [http://localhost:8025](http://localhost:8025) | Email viewer dashboard |
+
+## License
+
+Proprietary — All rights reserved.