# megabre/stokmasterpro architecture

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

- Interactive diagram: https://gitdiagram.com/megabre/stokmasterpro
- Repository: https://github.com/megabre/stokmasterpro

## Overview

1. **High-level shape**
   - This is a **server-rendered PHP inventory/ERP-style application** built around a modular admin interface.
   - The codebase is organized into shared infrastructure (`core/`, `config/`, `includes/`) plus feature areas under `modules/` and JSON/AJAX endpoints under `api/`.

2. **Primary entrypoints and request flow**
   - `index.php` is the main authenticated landing point, typically driving the dashboard.
   - `login.php` and `logout.php` handle session start/end.
   - `reset-admin.php` is a maintenance/bootstrap script for restoring admin access.
   - Most browser requests flow: **browser → PHP page/controller → core services → MySQL/MariaDB → HTML response**.

3. **Core application services**
   - `core/Database.php` and `config/database.php` define the database layer, using **PDO** against **MySQL/MariaDB**.
   - `core/Authentication.php`, `core/Session.php`, and `core/Security.php` enforce login state, role checks, CSRF/XSS protection, and input handling.
   - `core/Cache.php`, `core/Language.php`, and `core/DynamicFields.php` provide caching, localization, and extensible entity schemas.
   - Shared utility functions live in `core/functions.php` and `core/helpers.php`.

4. **Feature modules as the main domain boundary**
   - Each domain is isolated under `modules/<domain>/` and usually contains CRUD screens plus special actions.
   - Key domains are **dashboard, products, categories, customers, stock, orders, transactions, profile, settings, tools, and activity**.
   - The module layout is mostly page-based rather than service-based: `index.php`, `add.php`, `edit.php`, `delete.php`, `view.php`, etc.

5. **Data-heavy business subsystems**
   - **Products, categories, customers, and stock** are the core inventory entities and are tightly connected through dynamic fields and import/export templates.
   - **Orders** manage lifecycle/state transitions and include dedicated print and status-update pages.
   - **Transactions** cover payments, debts, expenses, and cash summaries, with customer-linked financial history.
   - **Dashboard** aggregates counts, charts, recent activity, and widget visibility settings.

6. **API/AJAX boundary**
   - The `api/` folder exposes lightweight endpoints for asynchronous UI operations and dashboard configuration.
   - Examples include dashboard settings get/save, system update, and entity-related endpoints for products, stock, orders, customers, categories, and transactions.
   - This is the main boundary where the front-end JavaScript talks back to the server without full page reloads.

7. **Front-end composition**
   - Shared layout pieces live in `includes/header.php`, `includes/sidebar.php`, and `includes/footer.php`.
   - Static assets are in `assets/`, with separate CSS and JavaScript for the general app and dashboard experience.
   - Notable scripts include `dashboard.js`, `chart-utils.js`, `dynamic-fields.js`, and `main.js`; the UI is built around **Tabler** and uses **ApexCharts**, with `jQuery`, `Select2`, and `DataTables` as supporting libraries.

8. **Database and persistent data**
   - The canonical schema/data source is `stok.sql`, indicating a classic relational backend.
   - `backup/` contains timestamped SQL dumps, showing that backups are a first-class operational feature.
   - The app also persists uploaded files in structured folders under `uploads/` for company assets, products, profiles, and imported data.

9. **Import/export and templates**
   - `templates/` contains CSV/XLSX templates for bulk import/export across major entities such as products, orders, customers, stock, categories, and transactions.
   - `modules/tools/import-export.php` and related pages likely coordinate file ingestion and generation.
   - `uploads/import/` stores imported source files, reinforcing that batch data loading is an important workflow.

10. **Settings, administration, and operational tools**
   - `modules/settings/` centralizes system configuration: roles, users, currencies, units, customer tags, inventory settings, and system metadata.
   - `modules/tools/` provides backups, cache management, optimization, calculators, and reports.
   - `modules/activity/` is the audit log subsystem, separate from operational data but cross-cutting across the app.

11. **Cross-cutting concerns**
   - The repository emphasizes **role-based access control**, **multi-language support** (`lang/en.php`, `lang/tr.php`), **secure file uploads**, and **audit logging**.
   - The presence of dynamic field definitions across products/categories/customers/stock suggests a schema-extensibility layer on top of the relational model.
   - Security and session handling are central architectural boundaries rather than just UI features.

12. **Operational/runtime context**
   - The app is designed for deployment on **Apache or Nginx with PHP 7.4+** and **MySQL/MariaDB 5.7+**.
   - Writable runtime directories include `uploads/` and `backup/`, which are part of the application’s operational surface.
   - `assets/vendor/` indicates bundled third-party front-end dependencies rather than external CDN-only delivery.

Main entry points: [`api/tools.php`](https://github.com/megabre/stokmasterpro/blob/main/api/tools.php) (API), [`modules/dashboard/index.php`](https://github.com/megabre/stokmasterpro/blob/main/modules/dashboard/index.php) (Dashboard), [`core/helpers.php`](https://github.com/megabre/stokmasterpro/blob/main/core/helpers.php) (Helpers), [`core/Database.php`](https://github.com/megabre/stokmasterpro/blob/main/core/Database.php) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & UI"]
  node_index["Home<br/>entrypoint<br/>[index.php]"]
  node_login["Login<br/>auth entry<br/>[login.php]"]
  node_logout["Logout<br/>auth exit<br/>[logout.php]"]
  node_header["Header<br/>layout partial<br/>[header.php]"]
  node_sidebar["Sidebar<br/>layout partial<br/>[sidebar.php]"]
  node_footer["Footer<br/>layout partial<br/>[footer.php]"]
end

subgraph group_core["Core Services"]
  node_db[("Database<br/>pdo layer<br/>[Database.php]")]
  node_configdb["DB Config<br/>db settings<br/>[database.php]"]
  node_auth["Auth<br/>access control<br/>[Authentication.php]"]
  node_session["Session<br/>[Session.php]"]
  node_security["Security<br/>csrf/xss guard<br/>[Security.php]"]
  node_dynfields{{"Dynamic Fields<br/>schema extension<br/>[DynamicFields.php]"}}
  node_cache["Cache<br/>[Cache.php]"]
  node_lang["Language<br/>i18n<br/>[Language.php]"]
  node_helpers["Helpers<br/>utility funcs<br/>[helpers.php]"]
end

subgraph group_features["Domain Modules"]
  node_dashboard["Dashboard<br/>[index.php]"]
  node_products["Products<br/>crud module<br/>[index.php]"]
  node_customers["Customers<br/>crud module<br/>[index.php]"]
  node_orders["Orders<br/>workflow module<br/>[index.php]"]
  node_stock["Stock<br/>inventory module<br/>[index.php]"]
  node_transactions["Transactions<br/>finance module<br/>[index.php]"]
  node_settings["Settings<br/>admin module<br/>[index.php]"]
  node_activity["Activity<br/>audit log<br/>[index.php]"]
end

subgraph group_ops["API & Operations"]
  node_tools["Tools<br/>ops module<br/>[index.php]"]
  node_api["API<br/>ajax endpoints<br/>[tools.php]"]
  node_uploads["Uploads<br/>runtime data"]
  node_backups["Backups<br/>runtime data"]
  node_schema[("Schema<br/>sql dump<br/>[stok.sql]")]
end

node_login -->|"start"| node_session
node_logout -->|"end"| node_session
node_index -->|"guarded by"| node_auth
node_index -->|"loads"| node_dashboard
node_dashboard -->|"reads"| node_db
node_dashboard -->|"uses"| node_cache
node_dashboard -.->|"refreshes via"| node_api
node_products -->|"extends with"| node_dynfields
node_customers -->|"extends with"| node_dynfields
node_stock -->|"extends with"| node_dynfields
node_orders -->|"references"| node_products
node_orders -->|"references"| node_customers
node_stock -->|"tracks"| node_products
node_transactions -->|"links to"| node_customers
node_settings -->|"admin check"| node_auth
node_settings -->|"persists"| node_db
node_tools -->|"creates"| node_backups
node_tools -->|"imports"| node_uploads
node_api -->|"serves"| node_dashboard
node_api -->|"serves"| node_products
node_api -->|"serves"| node_customers
node_api -->|"serves"| node_orders
node_api -->|"serves"| node_stock
node_api -->|"serves"| node_transactions
node_header -->|"shared with"| node_helpers
node_sidebar -->|"shared with"| node_helpers
node_footer -->|"shared with"| node_helpers
node_helpers -->|"loads"| node_lang
node_helpers -->|"uses"| node_security
node_configdb -->|"configures"| node_db
node_db -->|"targets"| node_schema

click node_index "https://github.com/megabre/stokmasterpro/blob/main/index.php"
click node_login "https://github.com/megabre/stokmasterpro/blob/main/login.php"
click node_logout "https://github.com/megabre/stokmasterpro/blob/main/logout.php"
click node_header "https://github.com/megabre/stokmasterpro/blob/main/includes/header.php"
click node_sidebar "https://github.com/megabre/stokmasterpro/blob/main/includes/sidebar.php"
click node_footer "https://github.com/megabre/stokmasterpro/blob/main/includes/footer.php"
click node_db "https://github.com/megabre/stokmasterpro/blob/main/core/Database.php"
click node_configdb "https://github.com/megabre/stokmasterpro/blob/main/config/database.php"
click node_auth "https://github.com/megabre/stokmasterpro/blob/main/core/Authentication.php"
click node_session "https://github.com/megabre/stokmasterpro/blob/main/core/Session.php"
click node_security "https://github.com/megabre/stokmasterpro/blob/main/core/Security.php"
click node_dynfields "https://github.com/megabre/stokmasterpro/blob/main/core/DynamicFields.php"
click node_cache "https://github.com/megabre/stokmasterpro/blob/main/core/Cache.php"
click node_lang "https://github.com/megabre/stokmasterpro/blob/main/core/Language.php"
click node_helpers "https://github.com/megabre/stokmasterpro/blob/main/core/helpers.php"
click node_dashboard "https://github.com/megabre/stokmasterpro/blob/main/modules/dashboard/index.php"
click node_products "https://github.com/megabre/stokmasterpro/blob/main/modules/products/index.php"
click node_customers "https://github.com/megabre/stokmasterpro/blob/main/modules/customers/index.php"
click node_orders "https://github.com/megabre/stokmasterpro/blob/main/modules/orders/index.php"
click node_stock "https://github.com/megabre/stokmasterpro/blob/main/modules/stock/index.php"
click node_transactions "https://github.com/megabre/stokmasterpro/blob/main/modules/transactions/index.php"
click node_settings "https://github.com/megabre/stokmasterpro/blob/main/modules/settings/index.php"
click node_tools "https://github.com/megabre/stokmasterpro/blob/main/modules/tools/index.php"
click node_activity "https://github.com/megabre/stokmasterpro/blob/main/modules/activity/index.php"
click node_api "https://github.com/megabre/stokmasterpro/blob/main/api/tools.php"
click node_uploads "https://github.com/megabre/stokmasterpro/tree/main/uploads/import"
click node_backups "https://github.com/megabre/stokmasterpro/blob/main/backup/backup_2025-05-25_03-14-12.sql"
click node_schema "https://github.com/megabre/stokmasterpro/blob/main/stok.sql"

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_index,node_login,node_logout,node_header,node_sidebar,node_footer toneBlue
class node_db,node_configdb,node_auth,node_session,node_security,node_dynfields,node_cache,node_lang,node_helpers toneAmber
class node_dashboard,node_products,node_customers,node_orders,node_stock,node_transactions,node_settings,node_activity toneMint
class node_tools,node_api,node_uploads,node_backups,node_schema toneRose
```

## Components

### Entry & UI

Browser entrypoints and shared page chrome.

- [Home](https://github.com/megabre/stokmasterpro/blob/main/index.php): entrypoint · Authenticated landing page and dashboard entry. · `index.php`
- [Login](https://github.com/megabre/stokmasterpro/blob/main/login.php): auth entry · Starts an authenticated session. · `login.php`
- [Logout](https://github.com/megabre/stokmasterpro/blob/main/logout.php): auth exit · Ends the user session. · `logout.php`
- [Header](https://github.com/megabre/stokmasterpro/blob/main/includes/header.php): layout partial · Shared top-of-page chrome. · `includes/header.php`
- [Sidebar](https://github.com/megabre/stokmasterpro/blob/main/includes/sidebar.php): layout partial · Shared navigation and module menu. · `includes/sidebar.php`
- [Footer](https://github.com/megabre/stokmasterpro/blob/main/includes/footer.php): layout partial · Shared bottom-of-page chrome. · `includes/footer.php`

### Core Services

Authentication, session, security, database, and shared helpers.

- [Database](https://github.com/megabre/stokmasterpro/blob/main/core/Database.php): pdo layer · PDO-backed database access to MySQL/MariaDB. · `core/Database.php`
- [DB Config](https://github.com/megabre/stokmasterpro/blob/main/config/database.php): db settings · Database connection configuration. · `config/database.php`
- [Auth](https://github.com/megabre/stokmasterpro/blob/main/core/Authentication.php): access control · Login state and role checks. · `core/Authentication.php`
- [Session](https://github.com/megabre/stokmasterpro/blob/main/core/Session.php): session mgmt · Session lifecycle and persistence. · `core/Session.php`
- [Security](https://github.com/megabre/stokmasterpro/blob/main/core/Security.php): csrf/xss guard · Input handling and request protection. · `core/Security.php`
- [Dynamic Fields](https://github.com/megabre/stokmasterpro/blob/main/core/DynamicFields.php): schema extension · Extensible entity fields used across modules. · `core/DynamicFields.php`
- [Cache](https://github.com/megabre/stokmasterpro/blob/main/core/Cache.php): runtime cache · Application caching for shared data. · `core/Cache.php`
- [Language](https://github.com/megabre/stokmasterpro/blob/main/core/Language.php): i18n · Locale loading and translated strings. · `core/Language.php`
- [Helpers](https://github.com/megabre/stokmasterpro/blob/main/core/helpers.php): utility funcs · Shared utility and helper functions. · `core/helpers.php`

### Domain Modules

Primary business areas implemented as page-based modules.

- [Dashboard](https://github.com/megabre/stokmasterpro/blob/main/modules/dashboard/index.php): module · Overview widgets, stats, and recent activity. · `modules/dashboard/index.php`
- [Products](https://github.com/megabre/stokmasterpro/blob/main/modules/products/index.php): crud module · Product catalog with dynamic fields. · `modules/products/index.php`
- [Customers](https://github.com/megabre/stokmasterpro/blob/main/modules/customers/index.php): crud module · Customer records, filters, and profiles. · `modules/customers/index.php`
- [Orders](https://github.com/megabre/stokmasterpro/blob/main/modules/orders/index.php): workflow module · Order lifecycle, printing, and status updates. · `modules/orders/index.php`
- [Stock](https://github.com/megabre/stokmasterpro/blob/main/modules/stock/index.php): inventory module · Stock movements and inventory records. · `modules/stock/index.php`
- [Transactions](https://github.com/megabre/stokmasterpro/blob/main/modules/transactions/index.php): finance module · Payments, debts, expenses, and cash summaries. · `modules/transactions/index.php`
- [Settings](https://github.com/megabre/stokmasterpro/blob/main/modules/settings/index.php): admin module · Users, roles, units, currencies, and system settings. · `modules/settings/index.php`
- [Activity](https://github.com/megabre/stokmasterpro/blob/main/modules/activity/index.php): audit log · Cross-cutting audit trail and activity history. · `modules/activity/index.php`

### API & Operations

Asynchronous endpoints, settings, tools, and runtime data.

- [Tools](https://github.com/megabre/stokmasterpro/blob/main/modules/tools/index.php): ops module · Backup, cache, optimization, import/export, and reports. · `modules/tools/index.php`
- [API](https://github.com/megabre/stokmasterpro/blob/main/api/tools.php): ajax endpoints · Lightweight endpoints for dashboard and entity actions. · `api/tools.php`
- [Uploads](https://github.com/megabre/stokmasterpro/tree/main/uploads/import): runtime data · Persistent uploaded company, product, profile, and import files. · `uploads/import`
- [Backups](https://github.com/megabre/stokmasterpro/blob/main/backup/backup_2025-05-25_03-14-12.sql): runtime data · Timestamped SQL backups created by the app. · `backup/backup_2025-05-25_03-14-12.sql`
- [Schema](https://github.com/megabre/stokmasterpro/blob/main/stok.sql): sql dump · Canonical relational database schema and seed data. · `stok.sql`

## Connections

- Login → Session: start · Creates and maintains the logged-in session.
- Logout → Session: end · Terminates the active session.
- Home → Auth: guarded by · Main landing page requires authenticated access.
- Home → Dashboard: loads · Authenticated home routes into the dashboard module.
- Dashboard → Database: reads · Fetches counts, widgets, and recent records.
- Dashboard → Cache: uses · Caches dashboard data and shared lookups.
- Dashboard → API: refreshes via · Dashboard widgets sync through AJAX endpoints.
- Products → Dynamic Fields: extends with · Supports configurable product attributes.
- Customers → Dynamic Fields: extends with · Supports configurable customer attributes.
- Stock → Dynamic Fields: extends with · Supports configurable stock attributes.
- Orders → Products: references · Orders depend on product records.
- Orders → Customers: references · Orders depend on customer records.
- Stock → Products: tracks · Inventory movements are tied to products.
- Transactions → Customers: links to · Financial history is customer-aware.
- Settings → Auth: admin check · User and role administration is protected.
- Settings → Database: persists · Stores configuration and master data.
- Tools → Backups: creates · Backup tooling writes SQL dumps.
- Tools → Uploads: imports · Import/export workflows use uploaded files.
- API → Dashboard: serves · Provides dashboard settings and data endpoints.
- API → Products: serves · Supports asynchronous product actions.
- API → Customers: serves · Supports asynchronous customer actions.
- API → Orders: serves · Supports asynchronous order actions.
- API → Stock: serves · Supports asynchronous stock actions.
- API → Transactions: serves · Supports asynchronous transaction actions.
- Header → Helpers: shared with · Layout pieces rely on common utilities.
- Sidebar → Helpers: shared with · Navigation uses shared utilities and state.
- Footer → Helpers: shared with · Footer shares common helper functions.
- Helpers → Language: loads · Helper layer supports localized output.
- Helpers → Security: uses · Common helpers participate in input handling.
- DB Config → Database: configures · Database connection settings feed the PDO layer.
- Database → Schema: targets · Database layer persists into the SQL schema.
