328 lines
9.6 KiB
Markdown
328 lines
9.6 KiB
Markdown
# 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.
|