# delipistacna/sperky architecture

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

- Interactive diagram: https://gitdiagram.com/delipistacna/sperky
- Repository: https://github.com/delipistacna/sperky

## Overview

##### Project Type and Purpose
- This is a full-stack PHP application that demonstrates a modular backend with clearly separated responsibilities (database, action handling, model/repository patterns) and a choice of frontend implementations (VanillaJS, jQuery, and Alpine.js).
- The application’s primary purpose is to handle various actions (via POST requests to action.php), work with a database to calculate and return warehouse values, and provide JSON responses.
- The README outlines how to expand actions, add new strategies, and how the Model/Repository pattern is used, suggesting an architecture that is easily extendable.

##### Analyzing the File Structure
- Backend Components:
- The “App” directory encapsulates the core backend logic.
- Under “App/Database”, you find connection handling, query wrappers (using PDO) and seeding logic via DatabaseSeeder.php.
- “App/Enums” contains enumerations like ActionsEnum which ensures proper action validation.
- “App/Functions” contains the ActionHandler and its related Strategy classes. The ActionStrategyFactory and specific strategies (like GetWarehouseValueStrategy and DoNothingStrategy) implement the strategy design pattern.
- “App/Http/Responses” has the classes for generating JSON responses (successful and failed) that encapsulate HTTP responses.
- “App/Interfaces” provides contracts (ActionStrategyInterface and ResponseInterface) ensuring consistency.
- “App/Models” and “App/Repositories” follow an MVC-like pattern where models perform business logic and communicate with repositories to abstract database interactions.
- Frontend Components:
- The root directory includes “index.html” and CSS files (input.css, output.css) which indicate the use of TailwindCSS.
- The “variants” folder features separate implementations using different JavaScript libraries (VanillaJS, jQuery, Alpine.js).
- Configuration / Setup:
- The setup.php and autoload.php files hint at script-based project initialization. The README also details database configuration and seeding.

a. Main Components to Include:
- Client/Frontend: Represent the HTML/CSS and the three JavaScript variants (VanillaJS, jQuery, Alpine.js) as separate but similar frontend nodes.
- HTTP Request Entry Point: “action.php” which receives POST requests.
- Action Handler Component: The ActionHandler class that processes incoming action requests.
- Action Strategies and Factory: ActionEnum, ActionStrategyFactory, and the individual Strategy implementations (e.g., GetWarehouseValueStrategy, DoNothingStrategy).
- Response System: The JSON response classes (JsonResponse, FailedJsonResponse, Response) that encapsulate the API response.
- Domain/Business Logic: The Models (Product, etc.) and Repositories that manage database interactions.
- Database Layer: The Database, Query, and Row classes, along with database configuration and seed logic.
- External Dependencies: PHP 8.3 runtime and MariaDB/MySQL database, plus TailwindCSS for styling.

b. Relationships and Interactions:
- Dependency from Strategy classes to the Model and Repository layer (for example, GetWarehouseValueStrategy invoking Product::getWarehouseValue()).
- Connection between the Repository layer and the Database/Query components which wrap the PDO functionality.

c. Architectural Patterns & Design Principles:
- Strategy design pattern for action handling.
- Separation of concerns: the Controller-like “action.php” serves as the entry point, the ActionHandler processes requests, distinct Strategy objects manage business logic, and the Repository pattern handles database interactions.
- Mention the use of interfaces to enforce contracts (i.e., for response and strategy implementation).

d. Relevant Technologies, Frameworks, and Libraries:
- Backend: PHP 8.3, using native OOP practices.
- Database: MariaDB/MySQL with a simple PDO wrapper.
- That dependency injection or autoloading (via autoload.php) exists.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client/Frontend"
        direction TB
        Client["Client Browser"]:::frontend
        HTML["index.html / input.css / output.css"]:::frontend
        Vanilla["VanillaJS Variant"]:::frontend
        jQueryVar["jQuery Variant"]:::frontend
        Alpine["Alpine.js Variant"]:::frontend
    end

    %% Entry Point
    Client -->|"HTTP_POST"| AP["action.php"]:::controller

    %% API & Business Logic
    AP -->|"Routes_to"| AH["ActionHandler"]:::controller
    AH -->|"ValidateAction"| AE["ActionsEnum"]:::strategy
    AH -->|"SelectStrategy"| ASF["ActionStrategyFactory"]:::strategy
    ASF -->|"Strategy"| GW["GetWarehouseValueStrategy"]:::strategy
    ASF -->|"Strategy"| DN["DoNothingStrategy"]:::strategy
    GW -->|"Executes"| ML["Models"]:::model
    DN -->|"Executes"| ML
    ML -->|"Calls"| RE["Repositories"]:::repository
    RE -->|"DB_Query"| DB["Database"]:::database
    DB -->|"Returns"| RE
    RE -->|"Returns_Data"| ML
    ML -->|"Pass_Data"| AH
    AH -->|"GenerateResponse"| RS["Response_System"]:::response
    RS -->|"Send_JSON"| Client

    %% Response System (Internal)
    RS1["JsonResponse"]:::response
    RS2["FailedJsonResponse"]:::response
    RS3["Response"]:::response
    RS --- RS1
    RS --- RS2
    RS --- RS3

    %% Configuration / Setup
    subgraph "Configuration/Setup"
        direction TB
        Autoload["autoload.php"]:::config
        Setup["setup.php"]:::config
        Readme["README.md"]:::config
    end
    Autoload -.-> AH
    Setup -.-> DB

    %% External Dependencies
    PHP["PHP_8.3_Runtime"]:::external
    MySQL["MariaDB/MySQL"]:::external
    Tailwind["TailwindCSS"]:::external
    PHP --> AH
    MySQL --> DB
    Tailwind --> HTML

    %% Annotation: Strategy Pattern Note
    Note["Note:_Update_ActionsEnum_and_ActionStrategyFactory_to_add_new_strategies."]:::config
    AH --- Note

    %% Annotation: Sample SQL Query Flow
    SQLNote["Sample_SQL:_SELECT*FROM_warehouse;"]:::database
    DB --- SQLNote

    %% Click Events
    click HTML "https://github.com/delipistacna/sperky/blob/main/index.html"
    click Vanilla "https://github.com/delipistacna/sperky/tree/main/variants/vanillajs"
    click jQueryVar "https://github.com/delipistacna/sperky/tree/main/variants/jquery"
    click Alpine "https://github.com/delipistacna/sperky/tree/main/variants/alpinejs"
    click AP "https://github.com/delipistacna/sperky/blob/main/action.php"
    click AH "https://github.com/delipistacna/sperky/blob/main/App/Functions/ActionHandler.php"
    click ASF "https://github.com/delipistacna/sperky/blob/main/App/Functions/ActionStrategies/ActionStrategyFactory.php"
    click GW "https://github.com/delipistacna/sperky/blob/main/App/Functions/ActionStrategies/GetWarehouseValueStrategy.php"
    click DN "https://github.com/delipistacna/sperky/blob/main/App/Functions/ActionStrategies/DoNothingStrategy.php"
    click AE "https://github.com/delipistacna/sperky/blob/main/App/Enums/ActionsEnum.php"
    click RS1 "https://github.com/delipistacna/sperky/blob/main/App/Http/Responses/JsonResponse.php"
    click RS2 "https://github.com/delipistacna/sperky/blob/main/App/Http/Responses/FailedJsonResponse.php"
    click RS3 "https://github.com/delipistacna/sperky/blob/main/App/Http/Responses/Response.php"
    click ML "https://github.com/delipistacna/sperky/tree/main/App/Models"
    click RE "https://github.com/delipistacna/sperky/tree/main/App/Repositories"
    click DB "https://github.com/delipistacna/sperky/blob/main/App/Database/Database.php"
    click Autoload "https://github.com/delipistacna/sperky/blob/main/autoload.php"
    click Setup "https://github.com/delipistacna/sperky/blob/main/setup.php"
    click Readme "https://github.com/delipistacna/sperky/blob/main/README.md"

    %% Class Definitions for Colors and Styles
    classDef frontend fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef controller fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef strategy fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef model fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef repository fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef database fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef response fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef config fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef external fill:#C0C0C0,stroke:#333,stroke-width:2px;
```
