L-Ami-Fiduciaire/docs/architecture.md

Architecture — L'Ami Fiduciaire

Generated: 2026-03-08 | Scan Level: Quick

Executive Summary

L'Ami Fiduciaire is a full-stack web application built for fiduciary/accounting firm client management. It provides a multi-tenant workspace system where firms can manage clients, folders (dossiers), and document exchanges with external clients via email-based invitation links.

The application follows a server-driven SPA architecture using Laravel 12 as the backend with Inertia.js v2 bridging to a Vue 3 frontend. This eliminates the need for a separate API layer — controllers render Vue pages directly via Inertia, while Wayfinder generates TypeScript route functions for type-safe navigation.

Architecture Pattern

Pattern: Full-Stack Monolith with Server-Driven SPA (Inertia.js)

┌─────────────────────────────────────────────────────┐
│                    Browser (SPA)                     │
│  Vue 3 + TypeScript + Tailwind CSS 4 + shadcn-vue   │
│         Inertia.js Client → Page Components          │
└──────────────────────┬──────────────────────────────┘
                       │  XHR / Inertia Protocol
┌──────────────────────▼──────────────────────────────┐
│               Laravel 12 (PHP 8.4)                   │
│  ┌─────────────────────────────────────────────┐    │
│  │  Middleware Pipeline                         │    │
│  │  (Auth, Workspace, Admin, Inertia, etc.)     │    │
│  └──────────────────┬──────────────────────────┘    │
│  ┌──────────────────▼──────────────────────────┐    │
│  │  Controllers → Inertia::render('Page', props)│    │
│  └──────────────────┬──────────────────────────┘    │
│  ┌──────────────────▼──────────────────────────┐    │
│  │  Eloquent ORM → Models + Relationships       │    │
│  └──────────────────┬──────────────────────────┘    │
└──────────────────────┼──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              MySQL 8.4 (via Docker/Sail)             │
└─────────────────────────────────────────────────────┘

Technology Stack

Category	Technology	Version
Backend Framework	Laravel	12.x
Backend Language	PHP	8.2+ (8.4 runtime)
Frontend Framework	Vue.js	3.5+
Frontend Language	TypeScript	5.2+
SPA Bridge	Inertia.js	v2
CSS Framework	Tailwind CSS	4.x
UI Components	shadcn-vue (reka-ui)	2.4+
Build Tool	Vite	7.x
Database	MySQL	8.4
Authentication	Laravel Fortify	v1
Route Generation	Laravel Wayfinder	0.1.x
File Management	Spatie Media Library	11.x
Activity Logging	Spatie Activity Log	4.x
Enums	bensampo/laravel-enum	6.x
Testing	Pest	4.x
Code Style (PHP)	Laravel Pint	1.x
Code Style (JS)	ESLint 9 + Prettier 3	-
Containerization	Docker / Laravel Sail	-
WebSockets	Soketi	latest
Mail Testing	Mailpit	latest

Data Architecture

Eloquent Models

Model	Table	Key Relationships
User	users	belongsToMany(Workspace), hasMany(Client)
Workspace	workspaces	belongsToMany(User) via WorkspaceUser
WorkspaceUser	workspace_user	Pivot: user_id, workspace_id, role
Client	clients	belongsTo(Workspace), hasMany(Folder)
Folder	folders	belongsTo(Client), hasMany(Message), hasMany(FolderInvitation), media
FolderInvitation	folder_invitations	belongsTo(Folder) — token-based access
Message	messages	belongsTo(Folder)

Business Enums

Enum	Purpose
ActorType	Distinguishes user types in activity logs
ClientStatus	Client lifecycle status
FolderPriority	Folder urgency level
FolderStatus	Folder workflow status
FolderType	Category of folder/dossier
LegalForm	Legal entity type for clients
MessageType	Type of message in folder
UserGroup	User permission group
WorkspaceUserRole	Role within a workspace

Database Migrations (16 files)

• Core: users, cache, jobs tables
• Auth: two-factor columns on users
• Multi-tenant: workspaces, workspace_user
• Business: clients, folders, folder_invitations, messages
• Packages: activity_log, media tables
• Extensions: confirmation fields on folders, responsable/suivi fields on clients

Authentication & Authorization

• Laravel Fortify provides headless auth: login, registration, password reset, email verification, two-factor authentication (TOTP)
• Custom Middleware:
  • EnsureUserIsAdmin — Admin-only route protection (users, workspaces management)
  • EnsureUserHasWorkspace — Workspace context enforcement
  • ValidateFolderInvitation — Token-based access for external client portal
  • HandleInertiaRequests — Shares auth/workspace data with frontend
  • HandleAppearance — Theme/appearance persistence

Route Architecture

Authenticated Routes (auth + verified)

• GET /dashboard — DashboardController (invokable)
• POST /workspace/switch — WorkspaceSwitchController (invokable)

Workspace-Scoped Routes (auth + verified + workspace)

• CRUD /clients — ClientController (resource)
• CRUD /folders — FolderController (resource)
• POST /folders/{folder}/messages — FolderMessageController
• POST /folders/{folder}/media — FolderMediaController (upload)
• GET /folders/{folder}/media/{mediaId} — FolderMediaController (download)

Admin Routes (auth + verified + admin)

• CRUD /users — UserController (resource)
• CRUD /workspaces — WorkspaceController (resource)

Public Client Portal (/c/ prefix, folder.invitation middleware)

• GET|POST /c/upload/{token} — Client file upload
• GET|POST /c/confirm/{token} — Client folder confirmation
• GET|POST /c/refuse/{token} — Client folder refusal

Settings Routes (auth / auth+verified)

• GET|PATCH /settings/profile — Profile management
• DELETE /settings/profile — Account deletion
• GET|PUT /settings/password — Password change (throttled)
• GET /settings/appearance — Appearance/theme settings
• GET /settings/two-factor — Two-factor authentication management

Email System

5 folder-related mailables handle client communication:

• FolderInviteMail — Invitation to access a folder
• FolderFileRequestMail — Request for file upload
• FolderConfirmationMail — Folder confirmation notification
• FolderSituationMail — Folder status update
• FolderTextMessageMail — Text message notification

Frontend Architecture

Component Organization

• Pages (31 Vue components): Mapped to routes via Inertia, organized by domain (auth, clients, folders, users, workspaces, settings, client portal)
• Layouts (8 components): AppLayout (sidebar/header variants), AuthLayout (card/simple/split variants), SettingsLayout
• UI Components: shadcn-vue design system with 20+ component groups (Button, Card, Dialog, Dropdown, Input, Select, Table, Tabs, Tooltip, etc.)
• Business Components: ClientForm, FolderForm, UserForm, WorkspaceForm, WorkspaceSwitcher, Pagination
• Composables (4): useAppearance, useCurrentUrl, useInitials, useTwoFactorAuth

State Management

• No client-side store (Redux/Pinia) — state is server-driven via Inertia props
• useForm() from Inertia handles form state and submission
• Composables for shared client-side logic

Type System

• TypeScript strict mode across all frontend code
• Type definitions in resources/js/types/ (auth, navigation, UI types)
• Wayfinder generates typed route functions

Testing Strategy

• Framework: Pest 4 (PHPUnit 12 compatible)
• Test Suites: Feature (13 test files) + Unit
• Coverage Areas: Authentication, settings, dashboard, user groups
• Factories: Model factories for test data generation
• CI Matrix: PHP 8.4 and 8.5

CI/CD Pipeline

Lint Workflow (lint.yml)

• Triggers: push/PR to develop, main, master, workos
• Steps: PHP setup → Composer install → npm install → Pint → Prettier → ESLint

Test Workflow (tests.yml)

• Triggers: push/PR to develop, main, master, workos
• Matrix: PHP 8.4, 8.5
• Steps: PHP setup → Node 22 → Composer install → npm install → env setup → key generation → Vite build → Pest

Deployment Configuration

Docker Compose (Laravel Sail)

• laravel.test — PHP 8.5 application container (port 80, Vite 5173)
• mysql — MySQL 8.4 database (port 3306)
• mailpit — Email testing UI (ports 1025, 8025)
• soketi — WebSocket server / Pusher-compatible (port 6001)

SSR Support

• Inertia SSR is enabled (inertia.php → ssr.enabled = true)
• SSR entry point: resources/js/ssr.ts
• SSR server URL: http://127.0.0.1:13714