# 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.