How mkblbj/estock-lite works
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).