# mkblbj/estock-lite architecture

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

- Interactive diagram: https://gitdiagram.com/mkblbj/estock-lite
- Repository: https://github.com/mkblbj/estock-lite

## Overview

This project is a PHP-based web application for managing e-shop stock (a lightweight stock management system, referred to as estock-lite). With a structure inspired by the Grocy household management system, it provides both a web front end (via Blade views and static assets in the public directory) and a full REST API (with API controllers and integrated Swagger UI). It follows an MVC-style architecture enhanced by a middleware layer and a service layer.

##### Main Components and Their Roles
- Frontend (User Interface):
- Located in the “views” directory (Blade templates) along with assets (CSS, JavaScript, images) in the “public” directory.
- Includes various UI components (e.g., battery cards, calendar cards, datetime pickers) and shorthands for user interactions.
- API Layer and Controllers:
- “controllers” directory holds both standard web controllers (e.g., LoginController, RecipesController, StockController) and API-specific controllers (e.g., BatteriesApiController, CalendarApiController).
- Responsible for processing incoming HTTP requests, handling forms/data input (through the REST API) and returning appropriate views or JSON.
- Service Layer:
- “services” directory encapsulates business logic for key application areas (stock, tasks, recipes, users, etc.). Services abstract data processing and operations.
- Middleware:
- “middleware” directory contains various middlewares (e.g., AuthMiddleware, CorsMiddleware, SessionAuthMiddleware) that manage request validation, session control, and cross-cutting concerns.
- Helpers and Plugins:
- “helpers” directory includes utility classes for barcode lookup, pagination, URL management, and additional functions.
- “plugins” directory hosts external extension points (e.g., DemoBarcodeLookupPlugin and OpenFoodFactsBarcodeLookupPlugin) that allow integration with external services.
- Database & Migrations:
- The “migrations” directory holds incremental SQL migration scripts (or PHP migration scripts) used to create and update the database schema (SQLite is recommended per the README).
- The DatabaseService in “services/DatabaseService.php” encapsulates database connectivity and execution of migrations.
- Configuration and Data Persistence:
- “config-dist.php” is a template for configuration; users copy this to “data/config.php”. The “data” folder also contains custom and persistent data (e.g., settings, locale files, plugins configuration).
- Entry Points:
- “index.php” in the root and “public/index.php” which serve as the entryways to the application.
- “app.php” may serve as a bootstrap file.

##### Relationships & Interactions
- External clients (web browsers, barcode scanners via native client or external services) interact with the application through HTTP requests.
- Requests pass through the middleware stack (authentication, CORS, JSON parsing) before reaching controllers.
- Controllers use the service layer to process business logic and access the database through migration-managed schemas.
- API controllers handle requests from external systems and return JSON responses, seamlessly integrating with the Swagger-enabled documentation.
- The frontend makes AJAX calls (using public/js files) to the REST API, creating a clear separation between presentation and business logic.

##### Architectural Patterns & Design Principles
- MVC Pattern: Separates the user interface (views), user input handling (controllers), and business logic (services).
- Layered Architecture: Distinct layers for middleware, controllers, services, and persistence.
- Plugin Extensibility: A dedicated “plugins” folder allows for additional features (e.g., external barcode lookup) without altering core functionality.
- Configuration & Environment Management: Externalized configuration, as seen by “config-dist.php” and usage of a “data” directory, supports different deployment modes (e.g., demo mode, embedded mode).

##### Technologies & Frameworks
- PHP (specifically PHP 8.2/8.3) as the backend language.
- Composer for dependency management.
- Yarn for managing front-end dependencies.
- SQLite as a lightweight database system (with required extensions such as pdo_sqlite).
- Blade templating (by convention, given the “.blade.php” files) for the view layer.
- REST and OpenAPI (Swagger UI provided in the API Controller) for API documentation and client integration.

##### Elements
- From the client to middleware, from middleware to controllers, and from controllers to services.
- From services to the database (via migration-managed schema).
- From API controllers to external clients.
- If possible, annotate with technologies (PHP, SQLite, Composer, Blade) for clarity.
- Interaction flows (e.g., request processing pipeline, API response cycle).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    EC("External Clients"):::external

    %% Entry Points
    subgraph "Entry Points"
        EP1("index.php (root)"):::entry
        EP2("public/index.php"):::entry
        EP3("app.php (bootstrap)"):::entry
    end

    %% Middleware
    MW("Middleware (middleware/)"):::middleware

    %% Controllers
    CT("Controllers (controllers/)"):::controller

    %% Service Layer
    SV("Service Layer (services/)"):::service
    DBS("DatabaseService (services/DatabaseService.php)"):::service

    %% Database & Migrations
    DB("Database & Migrations (migrations/)"):::database

    %% Frontend/UI
    subgraph "Frontend UI"
        FV("Blade Views (views/)"):::frontend
        PA("Static Assets (public/)"):::frontend
    end

    %% Support Components
    HP("Helpers (helpers/)"):::helper
    PL("Plugins (plugins/)"):::plugin
    subgraph "Configuration and Data"
        CFG("Config Template (config-dist.php)"):::config
        DP("Persistent Data (data/)"):::config
    end

    %% Data Flow Connections
    EC -->|"sendsRequest"| EP1
    EC -->|"sendsRequest"| EP2
    EC -->|"sendsRequest"| EP3

    EP1 -->|"processes"| MW
    EP2 -->|"processes"| MW
    EP3 -->|"processes"| MW

    MW -->|"forwards"| CT
    CT -->|"invokes"| SV
    CT -->|"renders"| FV

    SV -->|"calls"| DBS
    DBS -->|"executes"| DB

    SV -->|"utilizes"| HP
    SV -->|"integrates"| PL

    CFG -->|"provides"| SV
    DP -->|"provides"| SV

    %% Click Events
    click FV "https://github.com/mkblbj/estock-lite/tree/main/views/"
    click PA "https://github.com/mkblbj/estock-lite/tree/main/public/"
    click CT "https://github.com/mkblbj/estock-lite/tree/main/controllers/"
    click SV "https://github.com/mkblbj/estock-lite/tree/main/services/"
    click DBS "https://github.com/mkblbj/estock-lite/blob/main/services/DatabaseService.php"
    click MW "https://github.com/mkblbj/estock-lite/tree/main/middleware/"
    click HP "https://github.com/mkblbj/estock-lite/tree/main/helpers/"
    click PL "https://github.com/mkblbj/estock-lite/tree/main/plugins/"
    click DB "https://github.com/mkblbj/estock-lite/tree/main/migrations/"
    click CFG "https://github.com/mkblbj/estock-lite/blob/main/config-dist.php"
    click DP "https://github.com/mkblbj/estock-lite/tree/main/data/"
    click EP1 "https://github.com/mkblbj/estock-lite/blob/main/index.php"
    click EP2 "https://github.com/mkblbj/estock-lite/blob/main/public/index.php"
    click EP3 "https://github.com/mkblbj/estock-lite/blob/main/app.php"

    %% Styles
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef entry fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef middleware fill:#ffffcc,stroke:#bbbb00,stroke-width:2px;
    classDef controller fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef service fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef database fill:#ffebcc,stroke:#ff9900,stroke-width:2px;
    classDef frontend fill:#e6e6fa,stroke:#6666ff,stroke-width:2px;
    classDef helper fill:#ddffdd,stroke:#339933,stroke-width:2px;
    classDef plugin fill:#ffdddd,stroke:#cc3333,stroke-width:2px;
    classDef config fill:#d9edf7,stroke:#31708f,stroke-width:2px;
```
