# inventoros/inventoros architecture

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

- Interactive diagram: https://gitdiagram.com/inventoros/inventoros
- Repository: https://github.com/inventoros/inventoros

## Overview

1. **Overall shape**
   - Inventoros is a single Laravel 13 monolith with a Vue 3 + Inertia.js frontend.
   - The backend owns all domain logic, persistence, permissions, jobs, notifications, and integrations; the frontend is a thin UI layer rendered through Inertia pages and shared components.

2. **Primary user-facing entry points**
   - `routes/web.php` serves the browser app, including dashboard, inventory, orders, purchasing, reports, settings, install, and admin screens.
   - `routes/api.php` exposes the REST API under `/api/v1`, and `routes/ai.php` appears to expose the MCP/AI automation surface.
   - `routes/auth.php` handles authentication flows, including login, registration, password reset, email verification, and two-factor setup.

3. **Backend layering**
   - HTTP controllers are organized by domain (`Admin`, `Api`, `Inventory`, `Order`, `Purchasing`, `Reports`, `Settings`, etc.).
   - Controllers mostly coordinate request validation, authorization, and response shaping, then delegate to Eloquent models and service classes.
   - `app/Http/Resources` standardize API serialization, while `app/Http/Requests` contains validated input contracts.

4. **Core domain model**
   - The data model centers on inventory and supply-chain entities: `Product`, `ProductVariant`, `ProductOption`, `ProductCategory`, `Warehouse`, `ProductLocation`, `Supplier`, `Order`, `PurchaseOrder`, `StockAdjustment`, `StockAudit`, `WorkOrder`, `StockTransfer`, and related item tables.
   - Multi-tenancy is organization-based: `Organization` is attached to users and reused across records to isolate data per tenant.
   - Additional system entities cover roles, permission sets, plugins, notifications, webhooks, settings, activity logs, and saved reports.

5. **Inventory and stock mutation flows**
   - Stock changes happen through dedicated controllers and domain endpoints for stock adjustments, transfers, audits, returns, receiving purchase orders, and work orders.
   - Product observers and order observers likely keep derived state in sync, such as stock counts, audit logs, and status transitions.
   - Specialized tracking exists for batches and serial numbers, and variants can carry their own stock and pricing.

6. **Order, purchasing, and fulfillment**
   - Orders and purchase orders each have their own lifecycle controllers, GraphQL operations, PDF invoice rendering, and email notifications.
   - Purchase orders support send/receive/cancel actions and item-level receiving.
   - Returns are modeled separately from orders, which keeps the return workflow distinct from the original sale.

7. **API architecture**
   - The REST API is resource-oriented and backed by dedicated controllers and `JsonResource` classes.
   - The GraphQL layer mirrors much of the same domain using `Queries`, `Mutations`, and `Types` under `app/GraphQL`.
   - Both API surfaces enforce permissions through middleware/policies, and GraphQL adds schema-level constraints such as depth/complexity limits via config.

8. **Frontend architecture**
   - The UI is organized as Inertia pages under `resources/js/Pages`, with shared layout and reusable components under `resources/js/Components` and `resources/js/Layouts`.
   - Vue components cover inventory-specific interactions like barcode scanning, variant management, SKU generation, warehouse switching, and serial/batch lists.
   - Global concerns such as theme, localization, and permissions are handled via composables and i18n locale bundles.

9. **Authorization and tenant/security boundaries**
   - Access control is enforced through middleware, policies, roles, permission sets, and specialized admin/manager checks.
   - Security-related middleware includes installation gating, locale selection, two-factor verification, and security headers.
   - The app uses Sanctum for API token authentication, with separate handling for browser sessions and API bearer tokens.

10. **Extensibility and plugin system**
   - Plugins are first-class: there is a plugin registry/service layer, hook manager, hook facade, plugin UI service, and plugin activation state in storage/database.
   - The sample plugin under `plugins/hello-world` shows that plugins can contribute backend logic plus frontend assets.
   - The architectural boundary is intentional: plugins integrate through hooks, filters, and UI slots rather than by modifying core domain code.

11. **Automation, integrations, and background work**
   - Webhooks are modelled as internal events with queued delivery jobs, retry handling, and delivery logs.
   - Notifications are implemented through mailables, a notification service, and user notification preferences.
   - Queueable work is also used for delivery and likely for other asynchronous tasks such as retries and outbound notifications.

12. **Reporting, import/export, and operational tooling**
   - Reporting is split between predefined reports and a custom report builder backed by `ReportDataService`.
   - Imports and exports are handled as separate classes, with CSV-style bulk workflows for products, orders, users, and logs.
   - Activity logging is a cross-cutting concern, surfaced in admin pages and exportable for audit/reporting.

13. **Installation, updates, and deployment concerns**
   - The install wizard is an explicit application phase, with controllers and UI pages for requirements, database setup, admin creation, and completion.
   - Updates are managed in-app through update services, backup services, and GitHub release/file update integrations.
   - Deployment support includes Docker, cPanel-specific assets, GitHub Actions for tests/screenshots/releases, and environment examples for local and testing setups.

14. **Auxiliary automation interface**
   - The `app/Mcp` namespace exposes a separate tool/server model for AI or command-style automation.
   - Tools map directly onto core inventory actions such as listing products/orders, creating orders or products, adjusting stock, looking up barcodes, and querying low stock.
   - This is a distinct integration boundary layered over the same underlying domain services and authorization model.

15. **Data persistence and schema evolution**
   - All persistent state is managed through Laravel migrations and Eloquent models, with factories and seeders for tests, demo data, and screenshots.
   - The schema shows iterative expansion from core inventory into variants, warehouses, purchasing, returns, webhooks, two-factor auth, saved reports, and assembly/kitting.
   - The repository’s architecture is therefore a modular domain monolith: one app, many bounded feature areas, all sharing the same tenant-aware database and service layer.

Main entry points: [`app/Http/Controllers`](https://github.com/inventoros/inventoros/tree/main/app/Http/Controllers) (Domain controllers), [`app/Services`](https://github.com/inventoros/inventoros/tree/main/app/Services) (Services), [`app/Models`](https://github.com/inventoros/inventoros/tree/main/app/Models) (Domain models), [`resources/js/Pages`](https://github.com/inventoros/inventoros/tree/main/resources/js/Pages) (Inertia pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend UI"]
  node_ui_pages["Inertia pages<br/>Vue pages"]
  node_ui_components["Shared components<br/>Vue components"]
  node_ui_composables["Composables<br/>Vue state helpers"]
end

subgraph group_http["HTTP Surface"]
  node_routes_web["Web routes<br/>Laravel routes<br/>[web.php]"]
  node_routes_api["API routes<br/>Laravel routes<br/>[api.php]"]
  node_routes_auth["Auth routes<br/>Laravel routes<br/>[auth.php]"]
  node_controllers_domain["Domain controllers<br/>HTTP controllers"]
  node_controllers_api["API controllers<br/>HTTP controllers"]
  node_resources_requests["Resources & requests<br/>API contracts"]
  node_graphql{{"GraphQL layer<br/>GraphQL schema"}}
end

subgraph group_domain["Domain Core"]
  node_models[("Domain models<br/>Eloquent models")]
  node_services["Services"]
  node_policies["Policies"]
end

subgraph group_automation["Automation"]
  node_routes_ai["AI routes<br/>Laravel routes<br/>[ai.php]"]
  node_plugins["Plugin system<br/>Extensibility layer<br/>[PluginService.php]"]
  node_mcp{{"MCP server<br/>Automation tools"}}
  node_webhooks_jobs["Webhooks jobs<br/>Async delivery"]
  node_notifications_mail["Notifications<br/>Mail and alerts"]
end

subgraph group_platform["Platform"]
  node_middleware["Middleware<br/>HTTP security"]
  node_persistence[("Schema & seeders<br/>Database evolution")]
end

node_routes_web -->|"dispatches"| node_controllers_domain
node_routes_web -->|"renders"| node_ui_pages
node_routes_api -->|"dispatches"| node_controllers_api
node_routes_auth -->|"auth flow"| node_controllers_domain
node_routes_ai -->|"exposes"| node_mcp
node_controllers_domain -->|"reads/writes"| node_models
node_controllers_domain -->|"delegates"| node_services
node_controllers_domain -->|"authorizes"| node_policies
node_controllers_domain -->|"returns views"| node_ui_pages
node_controllers_api -->|"validates/serializes"| node_resources_requests
node_controllers_api -->|"reads/writes"| node_models
node_graphql -->|"resolves"| node_models
node_graphql -->|"uses"| node_services
node_middleware -->|"guards"| node_controllers_domain
node_ui_pages -->|"composes"| node_ui_components
node_ui_pages -->|"uses"| node_ui_composables
node_plugins -->|"hooks into"| node_services
node_mcp -->|"calls"| node_services
node_webhooks_jobs -->|"delivered by"| node_services
node_notifications_mail -->|"sent by"| node_services
node_services -->|"orchestrates"| node_models
node_models -->|"persisted in"| node_persistence

click node_routes_web "https://github.com/inventoros/inventoros/blob/main/routes/web.php"
click node_routes_api "https://github.com/inventoros/inventoros/blob/main/routes/api.php"
click node_routes_auth "https://github.com/inventoros/inventoros/blob/main/routes/auth.php"
click node_routes_ai "https://github.com/inventoros/inventoros/blob/main/routes/ai.php"
click node_ui_pages "https://github.com/inventoros/inventoros/tree/main/resources/js/Pages"
click node_ui_components "https://github.com/inventoros/inventoros/tree/main/resources/js/Components"
click node_ui_composables "https://github.com/inventoros/inventoros/tree/main/resources/js/composables"
click node_controllers_domain "https://github.com/inventoros/inventoros/tree/main/app/Http/Controllers"
click node_controllers_api "https://github.com/inventoros/inventoros/tree/main/app/Http/Controllers/Api"
click node_resources_requests "https://github.com/inventoros/inventoros/tree/main/app/Http/Requests"
click node_graphql "https://github.com/inventoros/inventoros/tree/main/app/GraphQL"
click node_models "https://github.com/inventoros/inventoros/tree/main/app/Models"
click node_services "https://github.com/inventoros/inventoros/tree/main/app/Services"
click node_policies "https://github.com/inventoros/inventoros/tree/main/app/Policies"
click node_middleware "https://github.com/inventoros/inventoros/tree/main/app/Http/Middleware"
click node_plugins "https://github.com/inventoros/inventoros/blob/main/app/Services/PluginService.php"
click node_mcp "https://github.com/inventoros/inventoros/tree/main/app/Mcp"
click node_webhooks_jobs "https://github.com/inventoros/inventoros/blob/main/app/Jobs/WebhookDeliveryJob.php"
click node_notifications_mail "https://github.com/inventoros/inventoros/tree/main/app/Mail"
click node_persistence "https://github.com/inventoros/inventoros/tree/main/database/migrations"

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_ui_pages,node_ui_components,node_ui_composables toneBlue
class node_routes_web,node_routes_api,node_routes_auth,node_controllers_domain,node_controllers_api,node_resources_requests,node_graphql toneAmber
class node_models,node_services,node_policies toneMint
class node_routes_ai,node_plugins,node_mcp,node_webhooks_jobs,node_notifications_mail toneRose
class node_middleware,node_persistence toneIndigo
```

## Components

### Frontend UI

Vue 3 and Inertia presentation layer.

- [Inertia pages](https://github.com/inventoros/inventoros/tree/main/resources/js/Pages): Vue pages · Feature screens for dashboard, inventory, orders, purchasing, reports, settings, and install. · `resources/js/Pages`
- [Shared components](https://github.com/inventoros/inventoros/tree/main/resources/js/Components): Vue components · Reusable UI for layouts, barcode scanning, variants, warehouses, and plugin slots. · `resources/js/Components`
- [Composables](https://github.com/inventoros/inventoros/tree/main/resources/js/composables): Vue state helpers · Cross-cutting client logic such as permissions, theme, and localization. · `resources/js/composables`

### HTTP Surface

Browser routes, API endpoints, and controller entry points.

- [Web routes](https://github.com/inventoros/inventoros/blob/main/routes/web.php): Laravel routes · Browser application entry points for inventory, orders, reports, settings, install, and admin. · `routes/web.php`
- [API routes](https://github.com/inventoros/inventoros/blob/main/routes/api.php): Laravel routes · REST API surface under /api/v1. · `routes/api.php`
- [Auth routes](https://github.com/inventoros/inventoros/blob/main/routes/auth.php): Laravel routes · Login, registration, password reset, email verification, and two-factor flows. · `routes/auth.php`
- [Domain controllers](https://github.com/inventoros/inventoros/tree/main/app/Http/Controllers): HTTP controllers · Inventory, order, purchasing, reports, settings, admin, install, and import/export controllers. · `app/Http/Controllers`
- [API controllers](https://github.com/inventoros/inventoros/tree/main/app/Http/Controllers/Api): HTTP controllers · Resource-oriented controllers for products, orders, suppliers, stock, warehouses, and reports. · `app/Http/Controllers/Api`
- [Resources & requests](https://github.com/inventoros/inventoros/tree/main/app/Http/Requests): API contracts · Validated input and standardized serialization for HTTP responses. · `app/Http/Requests`
- [GraphQL layer](https://github.com/inventoros/inventoros/tree/main/app/GraphQL): GraphQL schema · Queries, mutations, and types mirroring key inventory and purchasing operations. · `app/GraphQL`

### Domain Core

Tenant-aware models, services, policies, and persistence.

- [Domain models](https://github.com/inventoros/inventoros/tree/main/app/Models): Eloquent models · Tenant-aware inventory, orders, purchasing, users, roles, plugins, webhooks, and settings data. · `app/Models`
- [Services](https://github.com/inventoros/inventoros/tree/main/app/Services): Application services · Barcode, SKU, settings, reporting, plugin, notification, update, and webhook orchestration. · `app/Services`
- [Policies](https://github.com/inventoros/inventoros/tree/main/app/Policies): Authorization policies · Permission checks for products, orders, stock, suppliers, users, roles, and plugins. · `app/Policies`

### Automation

Plugins, MCP tools, webhooks, notifications, and background work.

- [AI routes](https://github.com/inventoros/inventoros/blob/main/routes/ai.php): Laravel routes · Automation and MCP-facing HTTP surface. · `routes/ai.php`
- [Plugin system](https://github.com/inventoros/inventoros/blob/main/app/Services/PluginService.php): Extensibility layer · Plugin registry, hook manager, UI slots, and sample plugin boundary. · `app/Services/PluginService.php`
- [MCP server](https://github.com/inventoros/inventoros/tree/main/app/Mcp): Automation tools · AI/command-style tools for inventory operations and lookups. · `app/Mcp`
- [Webhooks jobs](https://github.com/inventoros/inventoros/blob/main/app/Jobs/WebhookDeliveryJob.php): Async delivery · Webhook event subscription, queued delivery, and retry/log handling. · `app/Jobs/WebhookDeliveryJob.php`
- [Notifications](https://github.com/inventoros/inventoros/tree/main/app/Mail): Mail and alerts · Email notifications and user notification preferences. · `app/Mail`

### Platform

Security, schema evolution, and operational support.

- [Middleware](https://github.com/inventoros/inventoros/tree/main/app/Http/Middleware): HTTP security · Installation gating, locale, permissions, two-factor checks, and security headers. · `app/Http/Middleware`
- [Schema & seeders](https://github.com/inventoros/inventoros/tree/main/database/migrations): Database evolution · Migrations, factories, and seed data for the tenant-aware schema. · `database/migrations`

## Connections

- Web routes → Domain controllers: dispatches · Browser requests are handled by feature controllers.
- Web routes → Inertia pages: renders · Web routes return Inertia pages.
- API routes → API controllers: dispatches · REST endpoints are served by API controllers.
- Auth routes → Domain controllers: auth flow · Authentication and account flows are coordinated by controllers.
- AI routes → MCP server: exposes · Automation surface is routed to MCP tooling.
- Domain controllers → Domain models: reads/writes · Feature controllers coordinate domain state through Eloquent models.
- Domain controllers → Services: delegates · Controllers offload orchestration to services where needed.
- Domain controllers → Policies: authorizes · Domain actions are gated by policies and checks.
- Domain controllers → Inertia pages: returns views · Browser controllers shape data for Inertia screens.
- API controllers → Resources & requests: validates/serializes · API handlers use request contracts and JsonResources.
- API controllers → Domain models: reads/writes · API endpoints operate directly on the core domain models.
- GraphQL layer → Domain models: resolves · GraphQL queries and mutations mirror the same domain objects.
- GraphQL layer → Services: uses · GraphQL operations rely on application services for behavior.
- Middleware → Domain controllers: guards · Security and tenant boundaries are enforced before controller execution.
- Inertia pages → Shared components: composes · Pages are built from shared Vue components.
- Inertia pages → Composables: uses · Pages consume client-side state helpers.
- Plugin system → Services: hooks into · Plugin behavior is wired through registry and hook services.
- MCP server → Services: calls · MCP tools reuse the same underlying application services.
- Webhooks jobs → Services: delivered by · Webhook delivery is orchestrated through services and queued jobs.
- Notifications → Services: sent by · Mail and notification flows are coordinated through services.
- Services → Domain models: orchestrates · Services operate over the tenant-aware domain model.
- Domain models → Schema & seeders: persisted in · Models map to the evolving Laravel schema and seeded data.
