Vroum Solutions Documentation

Welcome to the Vroum Solutions developer documentation. Vroum is a multi-tenant SaaS platform for automotive repair shops (garages) and their clients. It enables:

• Vehicle & car management, VIN decoding, recall lookups
• Work orders, estimates, appointments & bay scheduling
• Inventory, purchase orders, suppliers & stock mutations
• Tire storage management (storage spaces, sections, tickets)
• A client portal for car owners: vehicles, garages, household members, invoices, appointment requests
• Invoicing, accounting (chart of accounts, transactions, periods) & PDF generation
• Full-text search across the domain (Scout + Meilisearch)
• Media & document handling
• Role & permission-based access control
• Real-time updates via WebSockets
• Activity logging & audit trail
• Internationalization & localization (en, fr)
• Notifications & communication (SMS and email through comms-service over RabbitMQ)
• AI-assisted tooling (laravel/ai, app/Ai)

AGENTS.md at the repo root is the short, authoritative convention sheet — read it first. This directory provides the long-form documents:

Topic	File
High-level architecture	architecture.md
Backend (Laravel) details	backend.md
Frontend (Inertia + Vue 3) details	frontend.md
Theme & design tokens	theme.md
Dependency inventory	dependencies.md
Coding standards & conventions	standards.md
Development workflow	development.md
Testing strategy	testing.md
Multi-tenancy model	multi-tenancy.md
Client portal	client-portal.md
Document templates & PDF rendering	documents.md
Part order status & purchase links	part-ordering.md
Queues & real-time comms	queues-realtime.md
Type transformation pipeline	types.md
Troubleshooting guide	troubleshooting.md
Security considerations	security.md
CASL (anti-spam) consent	casl.md
Comms service design & runbook	microservices/

Host setup (DNSMasq, the shared Docker proxy network) lives in the root README.md.

Quick Start

Prerequisite: the host-level DNSMasq + proxy Docker network setup described in the root README.md.

1. Copy environment file:

   cp .env.example .env

2. Install dependencies:

   composer install
   npm install

3. Start the stack (Laravel Sail — app, horizon, pgsql, redis, meilisearch, mailpit, minio, chromium):

   ./vendor/bin/sail up -d

4. Run migrations & seeders:

   ./vendor/bin/sail artisan migrate --seed

5. Start the Vite dev server on the host (install Vite+ once with curl -fsSL https://vite.plus | bash):

   vp install
   vp dev

The app is served by the laravel.test container behind the nginx proxy — you do not need artisan serve. Queue workers run in the dedicated horizon container.

Philosophy

• Thin controllers; business logic in Action classes (lorisleiva/laravel-actions).
• Strong typing via Spatie Data & backed enums → automatic TypeScript generation.
• Predictable formatting enforced by Pint (PHP) & Oxlint/Oxfmt via vp check (TS/Vue).
• Prefer feature tests over unit tests; real user flows validated end-to-end.
• Configuration-as-code: minimal hidden magic; explicit bootstrap in bootstrap/app.php.
• Performance & UX through Inertia.js bridging server-rendered data with SPA experience.
• Semantic design tokens over raw colors, so light/dark mode is free (theme.md).

Audience

These docs target developers onboarding to Vroum Solutions or contributing new features, refactors, or integrations.

Proceed to architecture.md for a systemic view.