# kevinclk/sis_adv_mark architecture

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

- Interactive diagram: https://gitdiagram.com/kevinclk/sis_adv_mark
- Repository: https://github.com/kevinclk/sis_adv_mark

## Overview

#### Purpose and entry points
A Laravel operational-management system for multi-branch inventory, warehouse distribution, souvenir requests, fixed assets, organization data, and reporting. HTTP entry points are `routes/web.php` and `routes/api.php`; Laravel bootstraps through `public/index.php` and `bootstrap/app.php`. The Vue/Inertia client starts at `resources/js/app.js`.

#### Application boundary and access model
Laravel controllers serve role-specific workflows for administrators, branch administrators, warehouse staff, managers, and sellers. Authentication is handled by `app/Http/Controllers/Auth/AuthenticatedSessionController.php`; authorization crosses middleware and policies in `app/Http/Middleware/CheckRole.php` and `app/Policies/UserPolicy.php`. Organization entities bind users to branches, areas, and warehouses through `app/Domain/Organizacion/Models/User.php`, `app/Domain/Organizacion/Models/Sucursal.php`, and `app/Domain/Inventario/Models/Almacen.php`.

#### Inventory and warehouse ledger
The inventory core models products, categories, per-location stock, and stock history: `app/Domain/Inventario/Models/Producto.php`, `app/Domain/Inventario/Models/Inventario.php`, and `app/Domain/Inventario/Models/StockHistorico.php`. Warehouse intake, requests, transfers, disposals, and movements are separate transactional concepts in `app/Domain/Distribucion/Models/IngresoAlmacen.php`, `app/Domain/Distribucion/Models/Movimiento.php`, and `app/Domain/Distribucion/Models/TransferenciaSucursal.php`. This establishes a flow from received stock through movement records to inventory/history updates.

#### Distribution and confirmation workflows
Admin distribution supports direct and batch-oriented delivery flows via `app/Http/Controllers/Admin/DistribucionDirectaController.php` and `app/Http/Controllers/Admin/DistribucionLoteController.php`. Distribution records can require recipient confirmation, represented by `app/Domain/Distribucion/Models/DistribucionConfirmacion.php` and coordinated by `app/Services/DistribucionConfirmacionService.php`. A public confirmation boundary exists at `app/Http/Controllers/ConfirmacionPublicaController.php`, separating recipient actions from authenticated administration.

#### Souvenirs and seller fulfillment
Souvenir operations combine versioned packs, product requests, and request history: `app/Domain/Souvenirs/Models/PackSouvenir.php`, `app/Domain/Souvenirs/Models/PackSouvenirVersion.php`, and `app/Domain/Souvenirs/Models/SolicitudSouvenir.php`. Administrative preparation and approval flow through `app/Http/Controllers/Admin/PreparacionSouvenirsController.php`; seller-facing catalogue, requests, and receipt actions reside under `app/Http/Controllers/Vendedor/`. Request state changes emit `app/Events/SolicitudSouvenirUpdated.php`.

#### Fixed assets and reporting
Assets are modeled independently from consumable stock, including assignment, movements, maintenance, and disposal in `app/Domain/Activos/Models/Activo.php`, `app/Domain/Activos/Models/AsignacionActivo.php`, and `app/Domain/Activos/Models/MantenimientoActivo.php`. Reporting derives operational views and exports from ledger data, with core assembly in `app/Domain/Reportes/Services/KardexProductoDataBuilder.php`, spreadsheet exports in `app/Exports/KardexProductoExport.php`, and PDF generation queued through `app/Jobs/GeneratePdfReportJob.php`.

#### Frontend, events, and runtime infrastructure
The frontend is a Vue application using Inertia request adaptation via `app/Http/Middleware/HandleInertiaRequests.php`; role-oriented screens live in `resources/js/Pages/Admin/`, `resources/js/Pages/Vendedor/`, and `resources/js/Pages/Gerencia/`. Events cover low-stock alerts and generated reports (`app/Events/LowStockAlert.php`, `app/Events/ReportGenerated.php`) with notification logic in `app/Services/LowStockNotifier.php`. Runtime configuration includes database, queues, mail, broadcasting, and Reverb (`config/database.php`, `config/queue.php`, `config/reverb.php`); production packaging uses Docker and Nginx (`Dockerfile.prod`, `docker/nginx.conf`, `docker/entrypoint.sh`).

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Laravel Runtime"]
  node_bootstrap{{"Laravel Bootstrap<br/>runtime entry"}}
  node_routes["Web &amp; API Routes<br/>route boundary"]
  node_deployment["Production Container<br/>Docker/Nginx deployment"]
end

subgraph group_access["Access &amp; Delivery"]
  node_frontend["Vue/Inertia Client<br/>frontend app"]
  node_inertia["Inertia Adapter<br/>HTTP middleware"]
  node_auth["Session Authentication<br/>auth controller"]
  node_authorization["Roles &amp; Policies<br/>access control"]
  node_public_confirmation["Public Recipient Confirmation<br/>public controller"]
  node_seller_ui["Seller Screens<br/>Vue pages"]
end

subgraph group_operations["Operational Domains"]
  node_organization[("Organization &amp; Locations<br/>organization models")]
  node_inventory[("Inventory Ledger<br/>inventory models")]
  node_warehouse["Warehouse Transactions<br/>distribution models"]
  node_distribution["Admin Distribution<br/>admin controllers"]
  node_confirmation["Distribution Confirmation<br/>confirmation service"]
  node_souvenirs[("Souvenir Requests<br/>souvenir models")]
  node_souvenir_admin["Souvenir Preparation<br/>admin controller"]
  node_assets[("Fixed Assets<br/>asset models")]
end

subgraph group_reporting["Reporting &amp; Events"]
  node_reporting_builder["Kardex Data Builder<br/>report service"]
  node_report_export["Report Export &amp; PDF Job<br/>export pipeline"]
  node_events["Operational Events<br/>events &amp; notifications"]
end

node_bootstrap -->|"boots HTTP routes"| node_routes
node_routes -->|"session endpoints"| node_auth
node_routes -->|"protects workflows"| node_authorization
node_routes -->|"web responses"| node_inertia
node_inertia -->|"Inertia pages"| node_frontend
node_authorization -->|"resolves user scope"| node_organization
node_organization -->|"scopes locations"| node_inventory
node_warehouse -->|"updates stock and history"| node_inventory
node_distribution -->|"creates delivery movements"| node_warehouse
node_distribution -->|"requests confirmation"| node_confirmation
node_public_confirmation -->|"recipient action"| node_confirmation
node_seller_ui -->|"catalogue and requests"| node_souvenirs
node_souvenir_admin -->|"prepares and approves"| node_souvenirs
node_souvenirs -->|"request state update"| node_events
node_inventory -->|"low-stock alerts"| node_events
node_inventory -->|"ledger data"| node_reporting_builder
node_warehouse -->|"movement data"| node_reporting_builder
node_reporting_builder -->|"report dataset"| node_report_export
node_report_export -->|"report generated"| node_events
node_deployment -->|"serves application"| node_bootstrap

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_bootstrap,node_routes,node_deployment toneBlue
class node_frontend,node_inertia,node_auth,node_authorization,node_public_confirmation,node_seller_ui toneAmber
class node_organization,node_inventory,node_warehouse,node_distribution,node_confirmation,node_souvenirs,node_souvenir_admin,node_assets toneMint
class node_reporting_builder,node_report_export,node_events toneRose
```

## Components

### Laravel Runtime

- **Laravel Bootstrap**: runtime entry
- **Web & API Routes**: route boundary
- **Production Container**: Docker/Nginx deployment

### Access & Delivery

- **Vue/Inertia Client**: frontend app
- **Inertia Adapter**: HTTP middleware
- **Session Authentication**: auth controller
- **Roles & Policies**: access control · Role middleware and user policy protect role-specific workflows.
- **Public Recipient Confirmation**: public controller · Unauthenticated recipient confirmation boundary.
- **Seller Screens**: Vue pages · Seller catalogue, request, and receipt workflows.

### Operational Domains

- **Organization & Locations**: organization models · Users are associated with branches, areas, and warehouses.
- **Inventory Ledger**: inventory models · Products, location stock, and stock history form the stock ledger.
- **Warehouse Transactions**: distribution models · Intake, movements, transfers, and disposals change operational stock.
- **Admin Distribution**: admin controllers · Direct and batch delivery workflows.
- **Distribution Confirmation**: confirmation service · Coordinates recipient confirmation for distributions.
- **Souvenir Requests**: souvenir models · Versioned packs and seller product requests.
- **Souvenir Preparation**: admin controller · Administrative request preparation and approval.
- **Fixed Assets**: asset models · Independent asset assignments, maintenance, movements, and disposal.

### Reporting & Events

- **Kardex Data Builder**: report service · Assembles operational ledger data for reports.
- **Report Export & PDF Job**: export pipeline · Spreadsheet export and queued PDF generation.
- **Operational Events**: events & notifications · Low-stock, report-generated, and souvenir-update events drive notifications.

## Connections

- Laravel Bootstrap → Web & API Routes: boots HTTP routes
- Web & API Routes → Session Authentication: session endpoints
- Web & API Routes → Roles & Policies: protects workflows
- Web & API Routes → Inertia Adapter: web responses
- Inertia Adapter → Vue/Inertia Client: Inertia pages
- Roles & Policies → Organization & Locations: resolves user scope
- Organization & Locations → Inventory Ledger: scopes locations
- Warehouse Transactions → Inventory Ledger: updates stock and history
- Admin Distribution → Warehouse Transactions: creates delivery movements
- Admin Distribution → Distribution Confirmation: requests confirmation
- Public Recipient Confirmation → Distribution Confirmation: recipient action
- Seller Screens → Souvenir Requests: catalogue and requests
- Souvenir Preparation → Souvenir Requests: prepares and approves
- Souvenir Requests → Operational Events: request state update
- Inventory Ledger → Operational Events: low-stock alerts
- Inventory Ledger → Kardex Data Builder: ledger data
- Warehouse Transactions → Kardex Data Builder: movement data
- Kardex Data Builder → Report Export & PDF Job: report dataset
- Report Export & PDF Job → Operational Events: report generated
- Production Container → Laravel Bootstrap: serves application