# lafabricadeinventos/erp-lfdi architecture

> Architecture diagram of the GitHub repository lafabricadeinventos/erp-lfdi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lafabricadeinventos/erp-lfdi
- Repository: https://github.com/lafabricadeinventos/erp-lfdi

## Overview

1. This is a Laravel 11-style monolith with a mixed server-rendered/client-rendered UI: PHP handles routing, auth, domain logic, and persistence, while the frontend is built with React + TypeScript via Vite and Inertia-style page components.

2. The main request boundary is Laravel HTTP routing under `routes/web.php`, `routes/auth.php`, and `routes/api.php`. Controllers in `app/Http/Controllers` are organized by functional area, and they hand off work to service classes rather than embedding all logic directly in controllers.

3. The UI layer lives in `resources/js`. It is structured around Inertia pages (`resources/js/Pages`), reusable components, modal dialogs, and layouts. `app/Http/Middleware/HandleInertiaRequests.php` is the bridge that shares server data into the React frontend.

4. The core business domains are CRM/operations oriented: customers, leads, contacts, projects, tasks, services, budgets, billing, payments, sales, debtors, reports, and administrative management. Each of these has its own controller and, in many cases, associated models and request validators.

5. The budgeting flow is one of the most specialized subsystems. There are `BudgetController`, budget-specific request classes, `BudgetService`, helper constructors for “ordinary” and “simplified” invoices, a dedicated PDF budget template in `resources/views/templates/budget.blade.php`, and prebuilt sample PDFs/assets under `public/assets/budgets`.

6. Customer management is split between web and API entry points. There are standard customer controllers plus API controllers and requests (`app/Http/Controllers/Api/CustomersController.php`, `ApiCustomerRequest`), with service classes such as `CustomerService`, `ApiCustomerService`, and helper classes for customer/contact handling.

7. Authentication and authorization are first-class subsystems. Laravel auth controllers handle login/registration/password reset/email verification, while role/permission management is backed by Laratrust (`config/laratrust.php`, Laratrust migrations, `RoleService`, `PermissionsController`, `RolesController`, `UsersController`). This suggests access control is central to the application’s architecture.

8. The persistence layer is relational and model-driven. Eloquent models cover customers, projects, budgets, services, senders, bank accounts, payments, tax rules, geographic data, roles, permissions, and user-linked entities. Migrations show a schema that evolved over time, including customer phone/email tables, service details, project phases, and payment methods.

9. Geographic and reference data are treated as seeded datasets. Countries, states, and cities are loaded from JSON seeders in `database/seeders/data`, and there are dedicated service classes for geo data lookup. This indicates forms and workflows depend on normalized location data rather than free-text entry.

10. Several service classes encapsulate non-trivial workflows and integration boundaries: `GeoDataService`, `B2BRouterService`, `SenderBankService`, `UserService`, `RoleService`, and `BudgetService`. These are the main abstraction layer between controllers and Eloquent models, and likely the right place to draw business-process boundaries in a diagram.

11. The frontend has a dense interaction model built around forms and modals. Many actions such as create/edit/delete, assigning phases, confirming customers, adding payments, and selecting budgets/projects happen through modal components rather than full page transitions, which means a lot of stateful user interaction is concentrated in the React layer.

12. Operationally, the repo is set up for standard Laravel deployment with CI/CD workflows in `.github/workflows` for staging and production. Static assets, fonts, and public PDF templates are checked into `public/`, and the app uses the usual Laravel storage/cache/log directories plus PHPUnit and JS tooling (ESLint, PostCSS/Tailwind, Vite) for build and test boundaries.

Main entry points: [`app/Http/Controllers`](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Controllers) (Feature Controllers), [`app/Models`](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Models) (Eloquent Models), [`resources/js/Pages`](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Pages) (Inertia Pages), [`app/Services/BudgetService.php`](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/BudgetService.php) (Budget Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_http["HTTP Layer"]
  node_web_routes["Web Routes<br/>route map<br/>[web.php]"]
  node_auth_routes["Auth Routes<br/>route map<br/>[auth.php]"]
  node_api_routes["API Routes<br/>route map<br/>[api.php]"]
  node_http_controllers["Feature Controllers<br/>controller suite"]
  node_auth_controllers["Auth Controllers<br/>auth flow"]
  node_inertia_bridge["Inertia Bridge<br/>middleware"]
  node_form_requests["Request Validators<br/>validation"]
end

subgraph group_grp_domain["Domain Services"]
  node_budget_service{{"Budget Service<br/>workflow service<br/>[BudgetService.php]"}}
  node_customer_service{{"Customer Service<br/>workflow service"}}
  node_api_customer_service{{"API Customer Service<br/>api service"}}
  node_geo_service{{"Geo Data Service<br/>lookup service<br/>[GeoDataService.php]"}}
  node_access_service{{"Access Services<br/>authz services<br/>[RoleService.php]"}}
  node_sender_bank_service{{"Sender Bank Service<br/>finance service"}}
  node_helpers["Invoice Helpers<br/>constructors"]
end

subgraph group_grp_ui["React UI"]
  node_inertia_pages["Inertia Pages<br/>react pages"]
  node_ui_components["UI Components<br/>react components"]
  node_ui_modals["Modal Workflows<br/>react modals"]
  node_layouts["Layouts<br/>react layout"]
  node_views["Blade Templates<br/>server views"]
end

subgraph group_grp_data["Data Model"]
  node_models[("Eloquent Models<br/>domain models")]
  node_migrations["Migrations<br/>schema history"]
  node_seeders["Seed Data<br/>reference data"]
end

subgraph group_grp_ops["Ops & Delivery"]
  node_deploy["CI/CD Workflows<br/>delivery<br/>[workflows]"]
end

node_web_routes -->|"dispatches to"| node_http_controllers
node_auth_routes -->|"dispatches to"| node_auth_controllers
node_api_routes -->|"dispatches to"| node_http_controllers
node_http_controllers -->|"validates with"| node_form_requests
node_http_controllers -->|"delegates budget"| node_budget_service
node_http_controllers -->|"delegates customer"| node_customer_service
node_http_controllers -->|"delegates api customer"| node_api_customer_service
node_http_controllers -->|"looks up geo"| node_geo_service
node_http_controllers -->|"delegates access"| node_access_service
node_http_controllers -->|"delegates sender bank"| node_sender_bank_service
node_http_controllers -->|"reads/writes"| node_models
node_budget_service -->|"builds invoices"| node_helpers
node_budget_service -->|"uses"| node_models
node_customer_service -->|"uses"| node_models
node_api_customer_service -->|"uses"| node_models
node_geo_service -->|"depends on"| node_seeders
node_access_service -->|"uses"| node_models
node_sender_bank_service -->|"uses"| node_models
node_inertia_bridge -->|"feeds props"| node_inertia_pages
node_inertia_pages -->|"composes"| node_ui_components
node_inertia_pages -->|"opens"| node_ui_modals
node_layouts -->|"wraps"| node_inertia_pages
node_views -->|"templates output"| node_budget_service
node_views -->|"app shell"| node_inertia_pages
node_migrations -->|"defines schema for"| node_models
node_seeders -->|"loads reference data for"| node_models
node_deploy -.->|"ships"| node_web_routes
node_deploy -.->|"builds"| node_inertia_pages

click node_web_routes "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/web.php"
click node_auth_routes "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/auth.php"
click node_api_routes "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/api.php"
click node_http_controllers "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Controllers"
click node_auth_controllers "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Controllers/Auth"
click node_inertia_bridge "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
click node_form_requests "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Requests"
click node_budget_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/BudgetService.php"
click node_customer_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/CustomerService.php"
click node_api_customer_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/ApiCustomerService.php"
click node_geo_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/GeoDataService.php"
click node_access_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/RoleService.php"
click node_sender_bank_service "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/SenderBankService.php"
click node_helpers "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Helpers"
click node_inertia_pages "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Pages"
click node_ui_components "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Components"
click node_ui_modals "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Components/modals"
click node_layouts "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Layouts"
click node_models "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Models"
click node_migrations "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/database/migrations"
click node_seeders "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/database/seeders"
click node_views "https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/views/templates"
click node_deploy "https://github.com/lafabricadeinventos/erp-lfdi/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_routes,node_auth_routes,node_api_routes,node_http_controllers,node_auth_controllers,node_inertia_bridge,node_form_requests toneBlue
class node_budget_service,node_customer_service,node_api_customer_service,node_geo_service,node_access_service,node_sender_bank_service,node_helpers toneAmber
class node_inertia_pages,node_ui_components,node_ui_modals,node_layouts,node_views toneMint
class node_models,node_migrations,node_seeders toneRose
class node_deploy toneIndigo
```

## Components

### HTTP Layer

Laravel request boundaries, controllers, middleware, and form validation.

- [Web Routes](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/web.php): route map · Main browser-facing request boundary. · `routes/web.php`
- [Auth Routes](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/auth.php): route map · Login, registration, and password flows. · `routes/auth.php`
- [API Routes](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/routes/api.php): route map · API entry points for mobile or external clients. · `routes/api.php`
- [Feature Controllers](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Controllers): controller suite · Functional controllers for CRM, billing, projects, and admin tasks. · `app/Http/Controllers`
- [Auth Controllers](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Controllers/Auth): auth flow · Session, registration, password reset, and verification endpoints. · `app/Http/Controllers/Auth`
- [Inertia Bridge](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Http/Middleware/HandleInertiaRequests.php): middleware · Shares server-side state into the React frontend. · `app/Http/Middleware/HandleInertiaRequests.php`
- [Request Validators](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Http/Requests): validation · Typed input validation for customers, budgets, roles, users, and auth. · `app/Http/Requests`

### Domain Services

Business workflows that sit between controllers and Eloquent models.

- [Budget Service](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/BudgetService.php): workflow service · Budget creation, update, and invoice construction logic. · `app/Services/BudgetService.php`
- [Customer Service](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/CustomerService.php): workflow service · Customer CRUD and customer/contact orchestration. · `app/Services/CustomerService.php`
- [API Customer Service](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/ApiCustomerService.php): api service · Customer operations specialized for API entry points. · `app/Services/ApiCustomerService.php`
- [Geo Data Service](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/GeoDataService.php): lookup service · Country, state, and city lookup over seeded reference data. · `app/Services/GeoDataService.php`
- [Access Services](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/RoleService.php): authz services · Role, user, and permission orchestration. · `app/Services/RoleService.php`
- [Sender Bank Service](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/app/Services/SenderBankService.php): finance service · Sender and bank-account management workflows. · `app/Services/SenderBankService.php`
- [Invoice Helpers](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Helpers): constructors · Customer/contact helpers and ordinary/simplified invoice builders. · `app/Helpers`

### React UI

Inertia pages, shared components, modals, and layouts.

- [Inertia Pages](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Pages): react pages · Top-level screens for customers, budgets, billing, reports, and admin. · `resources/js/Pages`
- [UI Components](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Components): react components · Shared controls, nav, forms, and modal primitives. · `resources/js/Components`
- [Modal Workflows](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Components/modals): react modals · Stateful create/edit/delete and selection flows. · `resources/js/Components/modals`
- [Layouts](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/js/Layouts): react layout · Authenticated and guest shells for the app. · `resources/js/Layouts`
- [Blade Templates](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/resources/views/templates): server views · App shell and PDF templates, including budget and receipt output. · `resources/views/templates`

### Data Model

Eloquent models, migrations, and seed data.

- [Eloquent Models](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/app/Models): domain models · Customers, budgets, projects, payments, roles, services, and related entities. · `app/Models`
- [Migrations](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/database/migrations): schema history · Relational schema evolution for core, CRM, billing, and access control. · `database/migrations`
- [Seed Data](https://github.com/lafabricadeinventos/erp-lfdi/tree/main/database/seeders): reference data · Countries, states, cities, users, roles, services, and tax rules. · `database/seeders`

### Ops & Delivery

Deployment and build/test boundaries.

- [CI/CD Workflows](https://github.com/lafabricadeinventos/erp-lfdi/blob/main/.github/workflows): delivery · Staging and production deployment automation. · `.github/workflows`

## Connections

- Web Routes → Feature Controllers: dispatches to · Browser routes are handled by feature controllers.
- Auth Routes → Auth Controllers: dispatches to · Auth-specific routes use dedicated auth controllers.
- API Routes → Feature Controllers: dispatches to · API endpoints are exposed through controller actions.
- Feature Controllers → Request Validators: validates with · Controllers rely on typed request objects for input validation.
- Feature Controllers → Budget Service: delegates budget · Budget-related controller actions are pushed into the service layer.
- Feature Controllers → Customer Service: delegates customer · Customer management is coordinated through services.
- Feature Controllers → API Customer Service: delegates api customer · API customer endpoints use a specialized service.
- Feature Controllers → Geo Data Service: looks up geo · Location-aware flows use normalized geographic lookup.
- Feature Controllers → Access Services: delegates access · Role and user administration is service-backed.
- Feature Controllers → Sender Bank Service: delegates sender bank · Sender and bank workflows are encapsulated in a service.
- Feature Controllers → Eloquent Models: reads/writes · Controllers persist and query through Eloquent models.
- Budget Service → Invoice Helpers: builds invoices · Budget workflows use invoice constructors and customer helpers.
- Budget Service → Eloquent Models: uses · Budget workflows operate on budgets, items, services, and tax rules.
- Customer Service → Eloquent Models: uses · Customer workflows manage customers and contact sub-records.
- API Customer Service → Eloquent Models: uses · API customer operations persist through the same domain models.
- Geo Data Service → Seed Data: depends on · Geo lookups are backed by seeded country/state/city datasets.
- Access Services → Eloquent Models: uses · Authorization management centers on users, roles, and permissions.
- Sender Bank Service → Eloquent Models: uses · Sender/bank workflows persist via sender and bank models.
- Inertia Bridge → Inertia Pages: feeds props · Server data is shared into Inertia pages.
- Inertia Pages → UI Components: composes · Pages are assembled from reusable controls and form elements.
- Inertia Pages → Modal Workflows: opens · Most create/edit/confirm flows are handled in modals.
- Layouts → Inertia Pages: wraps · Application shells host the page screens.
- Blade Templates → Budget Service: templates output · Budget PDF rendering relies on dedicated Blade templates.
- Blade Templates → Inertia Pages: app shell · Blade app entry point mounts the React frontend.
- Migrations → Eloquent Models: defines schema for · Schema changes shape the Eloquent model layer.
- Seed Data → Eloquent Models: loads reference data for · Seeders populate app data used by models and forms.
- CI/CD Workflows → Web Routes: ships · CI/CD deploys the Laravel application and its routes.
- CI/CD Workflows → Inertia Pages: builds · Frontend assets are built and deployed with the app.
