# bkdesignhub/stockiq architecture

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

- Interactive diagram: https://gitdiagram.com/bkdesignhub/stockiq
- Repository: https://github.com/bkdesignhub/stockiq

## Overview

#### Purpose and Runtime
StockIQ is a server-rendered inventory and purchasing ERP for SMB distributors and retailers. It is a Laravel/PHP application using MySQL persistence, Blade HTML views, Bootstrap/JavaScript assets, and Laravel’s standard web session/auth runtime. The HTTP entry point is `public/index.php`; CLI, migrations, and scheduled/queue commands enter through `artisan`.

#### Application Composition
The web route layer in `routes/web.php` maps browser requests to controller modules under `app/Http/Controllers`. Controllers render Blade screens or perform state-changing form actions; shared authenticated page structure is in `resources/views/layouts/app.blade.php`. The repository contains no API route tree or separate frontend service, so the primary boundary is browser → Laravel MVC → MySQL.

#### Identity and Admin Access
Authentication is handled by `app/Http/Controllers/AuthController.php`, backed by Laravel auth configuration in `config/auth.php` and the `app/Models/User.php` model. Admin profile/settings management is separated in `app/Http/Controllers/AdminProfileController.php` and `resources/views/admin/profile.blade.php`. Database seeding establishes an initial administrator through `database/seeders/AdminUserSeeder.php`.

#### Product Catalog and Supplier Pricing
Catalog master data consists of products, categories, brands, vendors, and vendor-specific product prices. Their persistence models are `app/Models/Product.php`, `app/Models/Category.php`, and `app/Models/VendorProductPrice.php`; UI/controller boundaries are represented by `app/Http/Controllers/ProductController.php`, `app/Http/Controllers/VendorController.php`, and `app/Http/Controllers/VendorProductPriceController.php`. Product forms and product detail views support catalog maintenance via `resources/views/products/_form.blade.php` and `resources/views/products/show.blade.php`.

#### Purchase-to-Inventory Flow
Purchases are the principal inventory-in transaction: `app/Http/Controllers/PurchaseController.php` manages purchase headers and item lines represented by `app/Models/Purchase.php` and `app/Models/PurchaseItem.php`. Stock changes are tracked separately through `app/Models/StockMovement.php` and exposed by `app/Http/Controllers/StockController.php`. This separates commercial purchase records from inventory ledger/history, with user-facing purchase workflows in `resources/views/purchases/create.blade.php` and `resources/views/purchases/show.blade.php`.

#### Operational Views and Reporting
`app/Http/Controllers/DashboardController.php` aggregates business state for the overview at `resources/views/dashboard/index.blade.php`. `app/Http/Controllers/ReportController.php` supplies stock-worth and monthly-profit reports, rendered by `resources/views/reports/stock-worth.blade.php` and `resources/views/reports/monthly-profit.blade.php`. These are read/aggregation boundaries over catalog, purchase, and stock data rather than a dedicated analytics service.

#### Persistence and Infrastructure
Schema ownership is concentrated in `database/migrations/2026_05_16_000000_create_stockiq_tables.php` and `database/migrations/2026_05_16_010000_create_categories_and_brands_tables.php`, alongside Laravel user/cache/job tables. Database connectivity is configured through environment values and `config/database.php`; Laravel queue, cache, filesystem, mail, logging, and session subsystems are available via their respective `config/` files. No external business API integration is evidenced in the tree.

Main entry points: [`routes/web.php`](https://github.com/bkdesignhub/stockiq/blob/main/routes/web.php) (Web routes), [`app/Http/Controllers/DashboardController.php`](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/DashboardController.php) (Dashboard & reports), [`config/database.php`](https://github.com/bkdesignhub/stockiq/blob/main/config/database.php) (MySQL), [`app/Http/Controllers/PurchaseController.php`](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/PurchaseController.php) (Purchase workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_browser(("Browser<br/>client"))
  node_layout["Authenticated layout<br/>Blade layout<br/>[app.blade.php]"]
  node_catalog_views["Catalog screens<br/>Blade views<br/>[_form.blade.php]"]
  node_purchase_views["Purchase screens<br/>Blade views<br/>[create.blade.php]"]
  node_report_views["Dashboard &amp; report screens<br/>Blade views<br/>[index.blade.php]"]
end

subgraph group_web["Laravel Web Application"]
  node_routes["Web routes<br/>routing<br/>[web.php]"]
  node_auth["Authentication<br/>controller<br/>[AuthController.php]"]
  node_admin["Admin profile<br/>controller"]
  node_catalog["Catalog &amp; supplier pricing<br/>controllers"]
  node_purchases["Purchase workflow<br/>controller"]
  node_stock["Stock ledger<br/>controller"]
  node_reporting["Dashboard &amp; reports<br/>controllers"]
end

subgraph group_data["Persistence &amp; Operations"]
  node_users["Users<br/>Eloquent model<br/>[User.php]"]
  node_catalog_data["Catalog data<br/>Eloquent models<br/>[Product.php]"]
  node_purchasing_data["Purchases &amp; items<br/>Eloquent models<br/>[Purchase.php]"]
  node_movements["Stock movements<br/>Eloquent model<br/>[StockMovement.php]"]
  node_mysql[("MySQL<br/>database<br/>[database.php]")]
  node_schema["Schema migrations"]
  node_artisan{{"Artisan<br/>CLI runtime"}}
  node_admin_seed["Initial admin seeder<br/>database seeder"]
end

node_browser -->|"HTTP requests"| node_routes
node_routes --> node_auth
node_routes --> node_admin
node_routes --> node_catalog
node_routes --> node_purchases
node_routes --> node_stock
node_routes --> node_reporting
node_auth -->|"authenticates"| node_users
node_admin -->|"manages"| node_users
node_catalog -->|"maintains"| node_catalog_data
node_purchases -->|"creates purchases"| node_purchasing_data
node_purchases -->|"records inventory in"| node_movements
node_stock -->|"shows history"| node_movements
node_reporting -.->|"reads"| node_catalog_data
node_reporting -.->|"aggregates"| node_purchasing_data
node_reporting -.->|"aggregates"| node_movements
node_catalog -->|"renders"| node_catalog_views
node_purchases -->|"renders"| node_purchase_views
node_reporting -->|"renders"| node_report_views
node_catalog_views -.->|"uses"| node_layout
node_purchase_views -.->|"uses"| node_layout
node_report_views -.->|"uses"| node_layout
node_users -->|"persists"| node_mysql
node_catalog_data -->|"persists"| node_mysql
node_purchasing_data -->|"persists"| node_mysql
node_movements -->|"persists"| node_mysql
node_artisan -->|"runs"| node_schema
node_schema -->|"creates tables"| node_mysql
node_artisan -->|"runs"| node_admin_seed
node_admin_seed -->|"creates administrator"| node_users

click node_routes "https://github.com/bkdesignhub/stockiq/blob/main/routes/web.php"
click node_auth "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/AuthController.php"
click node_admin "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/AdminProfileController.php"
click node_catalog "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/ProductController.php"
click node_purchases "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/PurchaseController.php"
click node_stock "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/StockController.php"
click node_reporting "https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/DashboardController.php"
click node_layout "https://github.com/bkdesignhub/stockiq/blob/main/resources/views/layouts/app.blade.php"
click node_catalog_views "https://github.com/bkdesignhub/stockiq/blob/main/resources/views/products/_form.blade.php"
click node_purchase_views "https://github.com/bkdesignhub/stockiq/blob/main/resources/views/purchases/create.blade.php"
click node_report_views "https://github.com/bkdesignhub/stockiq/blob/main/resources/views/dashboard/index.blade.php"
click node_users "https://github.com/bkdesignhub/stockiq/blob/main/app/Models/User.php"
click node_catalog_data "https://github.com/bkdesignhub/stockiq/blob/main/app/Models/Product.php"
click node_purchasing_data "https://github.com/bkdesignhub/stockiq/blob/main/app/Models/Purchase.php"
click node_movements "https://github.com/bkdesignhub/stockiq/blob/main/app/Models/StockMovement.php"
click node_mysql "https://github.com/bkdesignhub/stockiq/blob/main/config/database.php"
click node_schema "https://github.com/bkdesignhub/stockiq/blob/main/database/migrations/2026_05_16_000000_create_stockiq_tables.php"
click node_artisan "https://github.com/bkdesignhub/stockiq/blob/main/artisan"
click node_admin_seed "https://github.com/bkdesignhub/stockiq/blob/main/database/seeders/AdminUserSeeder.php"

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_browser,node_layout,node_catalog_views,node_purchase_views,node_report_views toneBlue
class node_routes,node_auth,node_admin,node_catalog,node_purchases,node_stock,node_reporting toneAmber
class node_users,node_catalog_data,node_purchasing_data,node_movements,node_mysql,node_schema,node_artisan,node_admin_seed toneMint
```

## Components

### Browser UI

- **Browser**: client
- [Authenticated layout](https://github.com/bkdesignhub/stockiq/blob/main/resources/views/layouts/app.blade.php): Blade layout · `resources/views/layouts/app.blade.php`
- [Catalog screens](https://github.com/bkdesignhub/stockiq/blob/main/resources/views/products/_form.blade.php): Blade views · `resources/views/products/_form.blade.php`
- [Purchase screens](https://github.com/bkdesignhub/stockiq/blob/main/resources/views/purchases/create.blade.php): Blade views · `resources/views/purchases/create.blade.php`
- [Dashboard & report screens](https://github.com/bkdesignhub/stockiq/blob/main/resources/views/dashboard/index.blade.php): Blade views · `resources/views/dashboard/index.blade.php`

### Laravel Web Application

- [Web routes](https://github.com/bkdesignhub/stockiq/blob/main/routes/web.php): routing · `routes/web.php`
- [Authentication](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/AuthController.php): controller · `app/Http/Controllers/AuthController.php`
- [Admin profile](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/AdminProfileController.php): controller · `app/Http/Controllers/AdminProfileController.php`
- [Catalog & supplier pricing](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/ProductController.php): controllers · `app/Http/Controllers/ProductController.php`
- [Purchase workflow](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/PurchaseController.php): controller · `app/Http/Controllers/PurchaseController.php`
- [Stock ledger](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/StockController.php): controller · `app/Http/Controllers/StockController.php`
- [Dashboard & reports](https://github.com/bkdesignhub/stockiq/blob/main/app/Http/Controllers/DashboardController.php): controllers · Aggregates operational data for read-only views. · `app/Http/Controllers/DashboardController.php`

### Persistence & Operations

- [Users](https://github.com/bkdesignhub/stockiq/blob/main/app/Models/User.php): Eloquent model · `app/Models/User.php`
- [Catalog data](https://github.com/bkdesignhub/stockiq/blob/main/app/Models/Product.php): Eloquent models · Products, categories, brands, vendors, and supplier prices. · `app/Models/Product.php`
- [Purchases & items](https://github.com/bkdesignhub/stockiq/blob/main/app/Models/Purchase.php): Eloquent models · `app/Models/Purchase.php`
- [Stock movements](https://github.com/bkdesignhub/stockiq/blob/main/app/Models/StockMovement.php): Eloquent model · Inventory ledger and history. · `app/Models/StockMovement.php`
- [MySQL](https://github.com/bkdesignhub/stockiq/blob/main/config/database.php): database · `config/database.php`
- [Schema migrations](https://github.com/bkdesignhub/stockiq/blob/main/database/migrations/2026_05_16_000000_create_stockiq_tables.php): migrations · `database/migrations/2026_05_16_000000_create_stockiq_tables.php`
- [Artisan](https://github.com/bkdesignhub/stockiq/blob/main/artisan): CLI runtime · Runs migrations, seeders, schedules, and queue commands. · `artisan`
- [Initial admin seeder](https://github.com/bkdesignhub/stockiq/blob/main/database/seeders/AdminUserSeeder.php): database seeder · `database/seeders/AdminUserSeeder.php`

## Connections

- Browser → Web routes: HTTP requests
- Web routes → Authentication
- Web routes → Admin profile
- Web routes → Catalog & supplier pricing
- Web routes → Purchase workflow
- Web routes → Stock ledger
- Web routes → Dashboard & reports
- Authentication → Users: authenticates
- Admin profile → Users: manages
- Catalog & supplier pricing → Catalog data: maintains
- Purchase workflow → Purchases & items: creates purchases
- Purchase workflow → Stock movements: records inventory in
- Stock ledger → Stock movements: shows history
- Dashboard & reports → Catalog data: reads
- Dashboard & reports → Purchases & items: aggregates
- Dashboard & reports → Stock movements: aggregates
- Catalog & supplier pricing → Catalog screens: renders
- Purchase workflow → Purchase screens: renders
- Dashboard & reports → Dashboard & report screens: renders
- Catalog screens → Authenticated layout: uses
- Purchase screens → Authenticated layout: uses
- Dashboard & report screens → Authenticated layout: uses
- Users → MySQL: persists
- Catalog data → MySQL: persists
- Purchases & items → MySQL: persists
- Stock movements → MySQL: persists
- Artisan → Schema migrations: runs
- Schema migrations → MySQL: creates tables
- Artisan → Initial admin seeder: runs
- Initial admin seeder → Users: creates administrator