feat: L'Ami Fiduciaire V1.0.0 — full codebase with Story 0.1 complete

Initial commit of the L'Ami Fiduciaire SaaS platform built on Laravel 12, Vue 3, Inertia.js 2, and Tailwind CSS 4. Story 0.1 (rename folders to declarations in database) is implemented and code-reviewed: migration, rollback, and 6 Pest tests all passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 23:33:10 +00:00
commit 35545c2a8f
1517 changed files with 246774 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,200 @@
+# 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`
--- a/docs/development-guide.md
+++ b/docs/development-guide.md
@@ -0,0 +1,186 @@
+# Development Guide — L'Ami Fiduciaire
+
+> Generated: 2026-03-08 | Scan Level: Quick
+
+## Prerequisites
+
+- **PHP** 8.2+ (recommended: 8.4)
+- **Composer** v2
+- **Node.js** 22+
+- **npm**
+- **Docker** (for Laravel Sail)
+
+## Quick Start
+
+### 1. Clone & Install
+
+```bash
+composer install
+npm install
+```
+
+### 2. Environment Setup
+
+```bash
+cp .env.example .env
+php artisan key:generate
+```
+
+### 3. Start Development Environment (Docker/Sail)
+
+```bash
+vendor/bin/sail up -d
+vendor/bin/sail artisan migrate
+```
+
+### 4. Run Development Servers
+
+```bash
+# All-in-one: PHP server + Queue + Logs + Vite (hot reload)
+vendor/bin/sail composer run dev
+
+# Or with SSR:
+vendor/bin/sail composer run dev:ssr
+```
+
+This runs concurrently:
+- `php artisan serve` — Laravel application server
+- `php artisan queue:listen` — Queue worker
+- `php artisan pail` — Log viewer
+- `npm run dev` — Vite dev server (HMR)
+
+## Docker Services
+
+| Service | Image | Ports |
+|---------|-------|-------|
+| laravel.test | sail-8.5/app | 80 (app), 5173 (Vite) |
+| mysql | mysql:8.4 | 3306 |
+| mailpit | axllent/mailpit | 1025 (SMTP), 8025 (UI) |
+| soketi | soketi:latest | 6001 (WS), 9601 (metrics) |
+
+All commands should be prefixed with `vendor/bin/sail` when running inside Docker.
+
+## Build Commands
+
+```bash
+# Development build with HMR
+npm run dev
+
+# Production build
+npm run build
+
+# Production build with SSR
+npm run build:ssr
+```
+
+## Code Quality
+
+### PHP Formatting (Laravel Pint)
+
+```bash
+# Fix formatting (dirty files only)
+vendor/bin/sail bin pint --dirty --format agent
+
+# Run all formatting
+composer lint
+
+# Check without fixing
+composer test:lint
+```
+
+### JavaScript/TypeScript Linting
+
+```bash
+# ESLint (fix mode)
+npm run lint
+
+# Prettier (fix mode)
+npm run format
+
+# Prettier (check only)
+npm run format:check
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+vendor/bin/sail artisan test --compact
+
+# Run with filter
+vendor/bin/sail artisan test --compact --filter=testName
+
+# Run specific test file
+vendor/bin/sail artisan test --compact tests/Feature/Auth/AuthenticationTest.php
+
+# Full test suite (includes lint + tests)
+composer test
+```
+
+### Test Structure
+
+- `tests/Feature/` — Feature/integration tests (13 files)
+  - `Auth/` — Authentication tests (login, registration, 2FA, email verification, password)
+  - `Settings/` — Settings tests (profile, password, 2FA)
+  - `DashboardTest.php`, `UserGroupTest.php`
+- `tests/Unit/` — Unit tests
+
+### Creating Tests
+
+```bash
+# Feature test (default)
+vendor/bin/sail artisan make:test --pest MyFeatureTest
+
+# Unit test
+vendor/bin/sail artisan make:test --pest --unit MyUnitTest
+```
+
+## Key Development Patterns
+
+### Controllers
+- Render Inertia pages: `Inertia::render('PageName', ['prop' => $data])`
+- Use Form Request classes for validation (never inline validation)
+- Invokable controllers for single-action endpoints
+
+### Route Functions (Wayfinder)
+- Import from `@/actions/` (controllers) or `@/routes/` (named routes)
+- Type-safe route generation for frontend
+
+### Frontend Components
+- All pages in `resources/js/pages/` (mapped to routes by Inertia)
+- shadcn-vue components in `resources/js/components/ui/`
+- Composables in `resources/js/composables/`
+- Layouts in `resources/js/layouts/`
+
+### Database
+- Use Eloquent models and relationships (avoid `DB::` facade)
+- Create Form Requests for all CRUD operations
+- Use factories for test data
+
+## Artisan Commands
+
+```bash
+# Create model with migration, factory, seeder
+vendor/bin/sail artisan make:model ModelName -mfs --no-interaction
+
+# Create controller
+vendor/bin/sail artisan make:controller ControllerName --no-interaction
+
+# Create form request
+vendor/bin/sail artisan make:request StoreEntityRequest --no-interaction
+
+# Run migrations
+vendor/bin/sail artisan migrate
+
+# Fresh migration with seeding
+vendor/bin/sail artisan migrate:fresh --seed
+```
+
+## CI/CD
+
+GitHub Actions run on push/PR to `develop`, `main`, `master`, `workos`:
+
+1. **Lint** (`lint.yml`): Pint → Prettier → ESLint
+2. **Tests** (`tests.yml`): Full test suite on PHP 8.4 and 8.5 matrix
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,56 @@
+# L'Ami Fiduciaire — Project Documentation Index
+
+> Generated: 2026-03-08 | Scan Level: Quick | Workflow: initial_scan
+
+## Project Overview
+
+- **Type:** Monolith (full-stack web application)
+- **Primary Language:** PHP 8.4 (backend) + TypeScript (frontend)
+- **Architecture:** Server-Driven SPA (Laravel 12 + Inertia.js v2 + Vue 3)
+- **Database:** MySQL 8.4
+- **Domain:** Fiduciary/accounting firm client & document management
+
+## Quick Reference
+
+- **Backend:** Laravel 12, Fortify (auth), Eloquent ORM, Spatie packages
+- **Frontend:** Vue 3 + TypeScript, Tailwind CSS 4, shadcn-vue, Vite 7
+- **Entry Points:** `artisan` (CLI), `resources/js/app.ts` (frontend), `resources/js/ssr.ts` (SSR)
+- **Architecture Pattern:** Inertia.js server-driven SPA (no REST API layer)
+- **Dev Command:** `vendor/bin/sail composer run dev`
+
+## Generated Documentation
+
+- [Project Overview](./project-overview.md) — Purpose, features, domain model, tech stack summary
+- [Architecture](./architecture.md) — Architecture pattern, data models, routes, auth, frontend design, CI/CD
+- [Source Tree Analysis](./source-tree-analysis.md) — Annotated directory tree, critical folders
+- [Development Guide](./development-guide.md) — Setup, commands, testing, code quality, patterns
+- [API Contracts](./api-contracts.md) _(To be generated)_
+- [Data Models](./data-models.md) _(To be generated)_
+- [Component Inventory](./component-inventory.md) _(To be generated)_
+
+## Existing Documentation
+
+- [AGENTS.md](../AGENTS.md) — Laravel Boost AI guidelines, coding conventions, testing rules
+- [.github/workflows/lint.yml](../.github/workflows/lint.yml) — GitHub Actions linting pipeline
+- [.github/workflows/tests.yml](../.github/workflows/tests.yml) — GitHub Actions test pipeline
+
+## Getting Started
+
+1. Clone the repository
+2. Run `composer install && npm install`
+3. Copy `.env.example` to `.env` and generate key: `php artisan key:generate`
+4. Start Docker: `vendor/bin/sail up -d`
+5. Run migrations: `vendor/bin/sail artisan migrate`
+6. Start dev servers: `vendor/bin/sail composer run dev`
+7. Access the app at `http://localhost`
+
+## Key Entities
+
+| Entity | Description |
+|--------|-------------|
+| Workspace | Multi-tenant workspace for a firm |
+| User | Firm employee with workspace role |
+| Client | Business client of the firm |
+| Folder | Document dossier for a client |
+| FolderInvitation | Token-based external access link |
+| Message | In-folder communication |
--- a/docs/project-overview.md
+++ b/docs/project-overview.md
@@ -0,0 +1,53 @@
+# Project Overview — L'Ami Fiduciaire
+
+> Generated: 2026-03-08 | Scan Level: Quick
+
+## Purpose
+
+L'Ami Fiduciaire is a web-based client management platform designed for fiduciary and accounting firms. It enables firms to manage their client base, organize document folders (dossiers), exchange files and messages with external clients, and handle multi-workspace operations with role-based access control.
+
+## Key Features
+
+- **Multi-Tenant Workspaces** — Firms can operate multiple workspaces, each with its own set of clients, folders, and users. Users switch between workspaces seamlessly.
+- **Client Management** — Full CRUD for clients with status tracking, legal form classification, and assignment of responsable/suivi contacts.
+- **Folder/Dossier System** — Create and manage folders with priority levels, status tracking, type categorization, and confirmation workflows.
+- **Client Portal** — External clients receive email invitations with secure token-based links to upload files, confirm folders, or refuse actions — no account required.
+- **Document Exchange** — File upload/download via Spatie Media Library with folder-scoped media management.
+- **Messaging** — In-folder messaging system for communication between firm users and clients.
+- **Email Notifications** — Automated email system for folder invitations, file requests, confirmations, status updates, and messages.
+- **Two-Factor Authentication** — TOTP-based 2FA via Laravel Fortify for enhanced account security.
+- **Activity Logging** — Audit trail via Spatie Activity Log for tracking user actions.
+- **Admin Panel** — Admin-only user and workspace management.
+
+## Tech Stack Summary
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | Laravel 12 (PHP 8.4) |
+| Frontend | Vue 3 + TypeScript + Inertia.js v2 |
+| Styling | Tailwind CSS 4 + shadcn-vue |
+| Database | MySQL 8.4 |
+| Auth | Laravel Fortify (2FA support) |
+| Build | Vite 7 |
+| DevOps | Docker/Sail + GitHub Actions |
+
+## Architecture
+
+- **Type:** Full-Stack Monolith
+- **Pattern:** Server-Driven SPA (Inertia.js)
+- **Repository:** Single repository (monolith)
+
+Controllers render Vue pages via Inertia.js, eliminating the need for a traditional REST API. Laravel Wayfinder generates TypeScript route functions for type-safe frontend navigation.
+
+## Domain Model
+
+```
+Workspace ←→ User (many-to-many via WorkspaceUser with roles)
+    │
+    └── Client (belongs to workspace)
+          │
+          └── Folder (belongs to client)
+                ├── Message (folder messages)
+                ├── Media (file attachments via Spatie)
+                └── FolderInvitation (token-based external access)
+```
--- a/docs/project-scan-report.json
+++ b/docs/project-scan-report.json
@@ -0,0 +1,53 @@
+{
+  "workflow_version": "1.2.0",
+  "timestamps": {
+    "started": "2026-03-08T12:00:00Z",
+    "last_updated": "2026-03-08T12:35:00Z",
+    "completed": "2026-03-08T12:35:00Z"
+  },
+  "mode": "initial_scan",
+  "scan_level": "quick",
+  "project_root": "c:/Projects/l'ami fiduciaire",
+  "project_knowledge": "c:/Projects/l'ami fiduciaire/docs",
+  "project_types": [
+    {
+      "part_id": "main",
+      "project_type_id": "web",
+      "display_name": "Full-stack Web Application (Laravel + Inertia.js + Vue 3)"
+    }
+  ],
+  "repository_type": "monolith",
+  "completed_steps": [
+    {"step": "step_0.5", "status": "completed", "timestamp": "2026-03-08T12:00:00Z", "summary": "Documentation requirements loaded for 12 project types"},
+    {"step": "step_1", "status": "completed", "timestamp": "2026-03-08T12:01:00Z", "summary": "Classified as monolith with 1 part: web (Laravel 12 + Inertia.js + Vue 3)"},
+    {"step": "step_2", "status": "completed", "timestamp": "2026-03-08T12:02:00Z", "summary": "Found 3 existing docs (AGENTS.md, lint.yml, tests.yml)"},
+    {"step": "step_3", "status": "completed", "timestamp": "2026-03-08T12:05:00Z", "summary": "Tech stack: Laravel 12 + Vue 3 + Inertia.js v2 + Tailwind CSS 4 + MySQL 8.4"},
+    {"step": "step_4", "status": "completed", "timestamp": "2026-03-08T12:10:00Z", "summary": "15 controllers, 7 models, 9 enums, 31 pages, 20+ UI component groups, 5 mailables"},
+    {"step": "step_5", "status": "completed", "timestamp": "2026-03-08T12:15:00Z", "summary": "Source tree documented with annotated directory structure"},
+    {"step": "step_6", "status": "completed", "timestamp": "2026-03-08T12:18:00Z", "summary": "Dev setup, Docker services, build commands, testing, CI/CD documented"},
+    {"step": "step_8", "status": "completed", "timestamp": "2026-03-08T12:22:00Z", "summary": "Architecture document generated for monolith"},
+    {"step": "step_9", "status": "completed", "timestamp": "2026-03-08T12:25:00Z", "summary": "Supporting docs: project-overview.md, development-guide.md"},
+    {"step": "step_10", "status": "completed", "timestamp": "2026-03-08T12:28:00Z", "summary": "Master index generated"},
+    {"step": "step_11", "status": "completed", "timestamp": "2026-03-08T12:32:00Z", "summary": "Validation complete, user chose to finalize"},
+    {"step": "step_12", "status": "completed", "timestamp": "2026-03-08T12:35:00Z", "summary": "Workflow complete"}
+  ],
+  "current_step": "completed",
+  "findings": {
+    "project_classification": "Monolith, 1 part, Laravel 12 + Vue 3 + Inertia.js",
+    "technology_stack": "Laravel 12, Vue 3, Inertia.js v2, Tailwind CSS 4, MySQL 8.4, shadcn-vue",
+    "models_count": 7,
+    "controllers_count": 15,
+    "pages_count": 31,
+    "enums_count": 9,
+    "tests_count": 16
+  },
+  "outputs_generated": [
+    "project-scan-report.json",
+    "source-tree-analysis.md",
+    "architecture.md",
+    "project-overview.md",
+    "development-guide.md",
+    "index.md"
+  ],
+  "resume_instructions": "Workflow completed successfully"
+}
--- a/docs/source-tree-analysis.md
+++ b/docs/source-tree-analysis.md
@@ -0,0 +1,178 @@
+# Source Tree Analysis — L'Ami Fiduciaire
+
+> Generated: 2026-03-08 | Scan Level: Quick | Repository Type: Monolith
+
+## Annotated Directory Tree
+
+```
+l'ami fiduciaire/
+├── app/                            # Laravel application code (backend)
+│   ├── Actions/
+│   │   └── Fortify/                # Custom Fortify auth actions (CreateNewUser, ResetUserPassword)
+│   ├── Concerns/                   # Shared traits (PasswordValidationRules, ProfileValidationRules)
+│   ├── Enums/                      # Business domain enums (9 enums)
+│   │   ├── ActorType.php
+│   │   ├── ClientStatus.php
+│   │   ├── FolderPriority.php
+│   │   ├── FolderStatus.php
+│   │   ├── FolderType.php
+│   │   ├── LegalForm.php
+│   │   ├── MessageType.php
+│   │   ├── UserGroup.php
+│   │   └── WorkspaceUserRole.php
+│   ├── Http/
+│   │   ├── Controllers/            # Inertia page controllers
+│   │   │   ├── Client/             # Public client portal (Upload, Confirm, Refuse)
+│   │   │   ├── Settings/           # User settings (Profile, Password, 2FA)
+│   │   │   ├── ClientController.php
+│   │   │   ├── DashboardController.php        ← Entry point (invokable)
+│   │   │   ├── FolderController.php
+│   │   │   ├── FolderMediaController.php
+│   │   │   ├── FolderMessageController.php
+│   │   │   ├── UserController.php             ← Admin only
+│   │   │   ├── WorkspaceController.php        ← Admin only
+│   │   │   └── WorkspaceSwitchController.php  ← Entry point (invokable)
+│   │   ├── Middleware/             # Custom middleware
+│   │   │   ├── EnsureUserHasWorkspace.php
+│   │   │   ├── EnsureUserIsAdmin.php
+│   │   │   ├── HandleAppearance.php
+│   │   │   ├── HandleInertiaRequests.php
+│   │   │   └── ValidateFolderInvitation.php
+│   │   └── Requests/              # Form request validation (13 classes)
+│   │       ├── Settings/          # Settings form requests
+│   │       ├── StoreClientRequest.php
+│   │       ├── StoreFolderMessageRequest.php
+│   │       ├── StoreFolderRequest.php
+│   │       ├── StoreUserRequest.php
+│   │       ├── StoreWorkspaceRequest.php
+│   │       ├── UpdateClientRequest.php
+│   │       ├── UpdateFolderRequest.php
+│   │       ├── UpdateUserRequest.php
+│   │       └── UpdateWorkspaceRequest.php
+│   ├── Mail/                       # Mailable classes (5 folder-related emails)
+│   │   ├── FolderConfirmationMail.php
+│   │   ├── FolderFileRequestMail.php
+│   │   ├── FolderInviteMail.php
+│   │   ├── FolderSituationMail.php
+│   │   └── FolderTextMessageMail.php
+│   ├── Models/                     # Eloquent models (7 models)
+│   │   ├── Client.php
+│   │   ├── Folder.php
+│   │   ├── FolderInvitation.php
+│   │   ├── Message.php
+│   │   ├── User.php
+│   │   ├── Workspace.php
+│   │   └── WorkspaceUser.php       # Pivot model
+│   └── Providers/                  # Service providers
+├── bootstrap/                      # Laravel bootstrap & app configuration
+│   ├── app.php                     ← Application bootstrap (middleware, routing, exceptions)
+│   ├── providers.php               ← Service provider registration
+│   └── cache/                      # Framework cache files
+├── config/                         # Laravel configuration files
+│   ├── app.php
+│   ├── auth.php
+│   ├── database.php
+│   ├── fortify.php                 # Fortify auth configuration
+│   ├── inertia.php                 # Inertia SSR configuration
+│   ├── mail.php
+│   ├── queue.php
+│   ├── session.php
+│   └── ...                         # Other standard Laravel config
+├── database/
+│   ├── factories/                  # Model factories for testing
+│   ├── migrations/                 # 16 database migrations
+│   └── seeders/                    # Database seeders
+├── public/                         # Web-accessible public directory
+├── resources/
+│   ├── css/                        # Global CSS (Tailwind imports)
+│   ├── js/                         # Frontend TypeScript/Vue source
+│   │   ├── app.ts                  ← Frontend entry point
+│   │   ├── ssr.ts                  ← SSR entry point
+│   │   ├── components/             # Vue components
+│   │   │   ├── ui/                 # shadcn-vue design system (20+ component groups)
+│   │   │   ├── clients/            # Client-specific components
+│   │   │   ├── folders/            # Folder-specific components
+│   │   │   ├── ClientForm.vue
+│   │   │   ├── FolderForm.vue
+│   │   │   ├── UserForm.vue
+│   │   │   ├── WorkspaceForm.vue
+│   │   │   ├── WorkspaceSwitcher.vue
+│   │   │   ├── Pagination.vue
+│   │   │   └── ...                 # App shell, navigation, layout components
+│   │   ├── composables/            # Vue composables (4 hooks)
+│   │   │   ├── useAppearance.ts
+│   │   │   ├── useCurrentUrl.ts
+│   │   │   ├── useInitials.ts
+│   │   │   └── useTwoFactorAuth.ts
+│   │   ├── layouts/                # Page layouts (8 layouts)
+│   │   │   ├── app/                # App layouts (Header, Sidebar)
+│   │   │   ├── auth/               # Auth layouts (Card, Simple, Split)
+│   │   │   ├── settings/           # Settings layout
+│   │   │   ├── AppLayout.vue       ← Main app layout
+│   │   │   └── AuthLayout.vue      ← Auth pages layout
+│   │   ├── lib/                    # Utility functions
+│   │   ├── pages/                  # Inertia page components (31 pages)
+│   │   │   ├── auth/               # Auth pages (Login, Register, 2FA, etc.)
+│   │   │   ├── client/             # Public client portal pages
+│   │   │   ├── clients/            # Client management (CRUD)
+│   │   │   ├── folders/            # Folder management (CRUD)
+│   │   │   ├── settings/           # User settings pages
+│   │   │   ├── users/              # User admin (CRUD)
+│   │   │   ├── workspaces/         # Workspace admin (CRUD)
+│   │   │   ├── Dashboard.vue
+│   │   │   └── Welcome.vue
+│   │   └── types/                  # TypeScript type definitions
+│   │       ├── auth.ts
+│   │       ├── index.ts
+│   │       ├── navigation.ts
+│   │       ├── ui.ts
+│   │       └── global.d.ts
+│   └── views/                      # Blade templates
+│       ├── app.blade.php           ← Root Blade template for Inertia
+│       └── emails/                 # Email Blade templates
+├── routes/
+│   ├── web.php                     ← Main web routes
+│   ├── settings.php                ← Settings routes
+│   └── console.php                 # Console/Artisan routes
+├── storage/                        # Laravel storage (logs, cache, uploads)
+├── tests/
+│   ├── Pest.php                    # Pest configuration
+│   ├── TestCase.php                # Base test case
+│   ├── Feature/                    # Feature tests (13 test files)
+│   │   ├── Auth/                   # Authentication tests
+│   │   ├── Settings/               # Settings tests
+│   │   ├── DashboardTest.php
+│   │   └── UserGroupTest.php
+│   └── Unit/                       # Unit tests
+├── .github/workflows/              # CI/CD pipelines
+│   ├── lint.yml                    # Linting (Pint + ESLint + Prettier)
+│   └── tests.yml                   # Testing (Pest, PHP 8.4/8.5 matrix)
+├── compose.yaml                    # Docker Compose (Sail + MySQL + Mailpit + Soketi)
+├── composer.json                   # PHP dependencies
+├── package.json                    # Node.js dependencies
+├── vite.config.ts                  # Vite build configuration
+├── tsconfig.json                   # TypeScript configuration
+├── eslint.config.js                # ESLint configuration
+├── phpunit.xml                     # PHPUnit/Pest configuration
+├── pint.json                       # Laravel Pint code style config
+├── artisan                         ← Laravel CLI entry point
+└── AGENTS.md                       # Laravel Boost AI guidelines
+```
+
+## Critical Folders Summary
+
+| Folder | Purpose | Key Files |
+|--------|---------|-----------|
+| `app/Http/Controllers/` | All Inertia page controllers (15 controllers) | ClientController, FolderController, etc. |
+| `app/Models/` | Eloquent ORM models (7 models) | User, Client, Folder, Workspace, etc. |
+| `app/Enums/` | Business domain enumerations (9 enums) | ClientStatus, FolderStatus, FolderType, etc. |
+| `app/Mail/` | Email notifications (5 mailables) | Folder-related email notifications |
+| `app/Http/Middleware/` | Request middleware (5 custom) | Workspace, Admin, Invitation guards |
+| `app/Http/Requests/` | Form validation (13 requests) | Store/Update requests for all entities |
+| `resources/js/pages/` | Vue page components (31 pages) | CRUD pages for all entities |
+| `resources/js/components/ui/` | shadcn-vue design system | 20+ UI component groups |
+| `resources/js/composables/` | Vue composables | Appearance, URL, Initials, 2FA |
+| `resources/js/layouts/` | Page layout templates (8 layouts) | App, Auth, Settings layouts |
+| `database/migrations/` | Schema migrations (16 files) | Full database schema |
+| `routes/` | Route definitions | web.php, settings.php |
+| `.github/workflows/` | CI/CD pipelines | lint.yml, tests.yml |