How inventoros/inventoros works
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: Controllers Domain controllers · Services Services · Models Domain models · Pages Inertia pages
Components 20
Frontend UI
Vue 3 and Inertia presentation layer.
- Inertia pages · Feature screens for dashboard, inventory, orders, purchasing, reports, settings, and install.
resources/js/Pages - Shared components · Reusable UI for layouts, barcode scanning, variants, warehouses, and plugin slots.
resources/js/Components - Composables · 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 · Browser application entry points for inventory, orders, reports, settings, install, and admin.
routes/web.php - API routes · REST API surface under /api/v1.
routes/api.php - Auth routes · Login, registration, password reset, email verification, and two-factor flows.
routes/auth.php - Domain controllers · Inventory, order, purchasing, reports, settings, admin, install, and import/export controllers.
app/Http/Controllers - API controllers · Resource-oriented controllers for products, orders, suppliers, stock, warehouses, and reports.
app/Http/Controllers/Api - Resources & requests · Validated input and standardized serialization for HTTP responses.
app/Http/Requests - GraphQL layer · Queries, mutations, and types mirroring key inventory and purchasing operations.
app/GraphQL
Domain Core
Tenant-aware models, services, policies, and persistence.
- Domain models · Tenant-aware inventory, orders, purchasing, users, roles, plugins, webhooks, and settings data.
app/Models - Services · Barcode, SKU, settings, reporting, plugin, notification, update, and webhook orchestration.
app/Services - 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 · Automation and MCP-facing HTTP surface.
routes/ai.php - Plugin system · Plugin registry, hook manager, UI slots, and sample plugin boundary.
app/Services/PluginService.php - MCP server · AI/command-style tools for inventory operations and lookups.
app/Mcp - Webhooks jobs · Webhook event subscription, queued delivery, and retry/log handling.
app/Jobs/WebhookDeliveryJob.php - Notifications · Email notifications and user notification preferences.
app/Mail
Platform
Security, schema evolution, and operational support.
- Middleware · Installation gating, locale, permissions, two-factor checks, and security headers.
app/Http/Middleware - Schema & seeders · Migrations, factories, and seed data for the tenant-aware schema.
database/migrations
Connections 22
- 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.