# maksimtsarykovich/transaction architecture

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

- Interactive diagram: https://gitdiagram.com/maksimtsarykovich/transaction
- Repository: https://github.com/maksimtsarykovich/transaction

## Overview

##### Project Type and Purpose
- The application is a full-stack web application that allows users to upload CSV files with a defined structure. On upload, the system processes the CSV, extracts transaction information, and displays it on a viewing page.
- Key technologies include PHP (core backend logic), Nginx (HTTP server), MySQL (database), and Docker for containerized deployment. The README also mentions phpMyAdmin for database administration.
- The application follows an MVC-like architecture with controllers, models, repositories, and service layers implemented within the “src” directory.

##### Analyzing the File Structure
- Docker Directory: Contains service configuration files and Dockerfiles for PHP, Nginx, and MySQL. This clearly defines the deployment architecture.
- Public Directory: Holds the entry point (index.php) and static assets (CSS/JS files) that form the frontend user interface.
- Src Directory:
- Core Application Files: Classes for app initialization (App.php, Config.php, Router.php, etc.) and view rendering (View.php).
- Controllers: Manage requests, e.g., FileController and TransactionController.
- Domain/Entities and Models: Represent business objects like File and Transaction, implying a separation between domain logic and data models.
- Repositories: Facilitate data persistence and retrieval (e.g., TransactionRepository, FileRepository).
- Exceptions and Utility Classes: Define error handling and support functions (e.g., FinanceCalculator, FlashMessage).
- Views Directory: Contains PHP templates for UI rendering (index, error pages, form upload, and transaction view).

##### Main Components
a. Frontend Component:
- Public assets (CSS, JavaScript, HTML templates)
- Forms for uploading CSV files and pages for displaying transaction information.
b. Backend Component:
- Application Core (initialization, configuration, and routing)
- Controllers (handle HTTP requests and business logic execution)
- Domain/Model Layer (Business entities such as File and Transaction)
- Repository Layer (handles data persistence with MySQL)
- Utility and Helper Functions (processing CSV files, calculation logic, etc.)
c. Database Component:
- MySQL database container as configured in Docker (with Dockerfile and init.sql)
d. Infrastructure & Deployment:
- Docker-managed Containers including:
- PHP Container – Hosting the backend code.
- Nginx Container – Serving static content and acting as a reverse proxy to PHP.
- MySQL Container – Data storage.
- (Optionally) phpMyAdmin Container – For database administration.
e. External Services:
- Environment configuration through .env (handled by the phpdotenv library).

##### Relationships and Interactions
- The user interacts with the frontend (via a web browser) that loads static assets from the public directory.
- HTTP requests are first handled by the Nginx container, which forwards them to the PHP container via fastCGI.
- Within the PHP container, the App class in the “src/Core” initializes routes (using the Router) and dispatches them to the appropriate Controllers.
- Controllers process business logic by invoking Services (like CSVService for handling CSV processing) and interacting with Domain Entities.
- Data operations are abstracted into the Repository layer. The PHP backend communicates with the MySQL container for CRUD operations.
- Error handling is managed through custom Exception classes to ensure maintainable and traceable error flows.
- When a CSV file is uploaded, it is received by the FileController, processed by utilities, and its data is persisted and displayed accordingly.
- Environment variables and configuration settings (.env file) are used to manage database connections and other settings.

##### Architectural Patterns and Design Principles
- MVC (or similar separation) is apparent through distinct directories dedicated to Controllers, Models/Entities, and Views.
- Dependency injection and modular design age might be inferred from using composer and organizing code into services, repositories, and utilities.
- The Dockerization of each service suggests the use of container orchestration for consistent deployment across environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    UserBrowser("User Browser"):::frontend
    subgraph "Frontend Component"
        Index("Index (public/index.php)"):::frontend
        Assets("Assets (public/assets)"):::frontend
        ViewTemplates("View Templates (views)"):::frontend
    end

    %% Deployment (Docker Containers)
    subgraph "Deployment & Infrastructure (Docker)"
        Nginx("Nginx Container"):::docker
        PHPCont("PHP Container"):::docker
        MySQL("MySQL Container"):::database
        DockerCompose("Docker Compose Configuration"):::docker
    end

    %% External Configuration
    Env("Env Config (.env)"):::backend

    %% Relationships: Frontend to Docker
    UserBrowser -->|"requests"| Index
    Index -->|"loads"| Assets
    Assets -->|"renders"| ViewTemplates
    UserBrowser -->|"HTTP_request"| Nginx

    %% Nginx forwards to PHP Container
    Nginx -->|"forwards"| PHPCont

    %% PHP Container Internal Structure
    subgraph "PHP Container Internal"
        %% Application Core (src/Core)
        subgraph "Application Core (src/Core)" 
            App("App"):::backend
            Config("Config"):::backend
            Router("Router"):::backend
            CoreView("View (Core)"):::backend
        end

        %% Controllers (src/Controllers)
        subgraph "Controllers (src/Controllers)"
            FileController("FileController"):::backend
            TransactionController("TransactionController"):::backend
            AbstractController("AbstractController"):::backend
        end

        %% Domain & Services (src/Domain)
        subgraph "Domain & Services (src/Domain)"
            FileEntity("File Entity"):::backend
            TransactionEntity("Transaction Entity"):::backend
            CSVService("CSV Service"):::backend
            TransactionProcessor("Transaction Processor"):::backend
            CurrencyVO("Currency VO"):::backend
        end

        %% Repository Layer (src/Repository)
        subgraph "Repository Layer (src/Repository)"
            FileRepository("File Repository"):::backend
            TransactionRepository("Transaction Repository"):::backend
            CurrencyRepository("Currency Repository"):::backend
        end

        %% Infrastructure & Utilities (src/Infrastructure, src/Utils, src/Exceptions)
        subgraph "Infrastructure & Utilities"
            DBConnector("DB Connector"):::backend
            QueryBuilder("Query Builder"):::backend
            CSVFile("CSV File Utility"):::backend
            HTTPRequest("HTTP Request"):::backend
            HTTPResponse("HTTP Response"):::backend
            FinanceCalculator("Finance Calculator"):::backend
            FlashMessage("Flash Message"):::backend
            Utils("Utils"):::backend
            FileNotFoundEx("FileNotFound Exception"):::backend
            ViewNotFoundEx("ViewNotFound Exception"):::backend
        end
    end

    %% Relationships within PHP Container
    App -->|"init"| FileController
    App -->|"init"| TransactionController
    FileController -->|"processCSV"| CSVService
    CSVService -->|"processData"| TransactionProcessor
    TransactionController -->|"displayTX"| TransactionEntity
    FileController -->|"persistFile"| FileRepository
    TransactionController -->|"persistTX"| TransactionRepository
    FileRepository -->|"query"| DBConnector
    TransactionRepository -->|"query"| DBConnector
    CSVService -->|"calc"| FinanceCalculator
    AbstractController -->|"handle"| FileNotFoundEx
    AbstractController -->|"handle"| ViewNotFoundEx

    %% PHP Container dependency on configuration
    PHPCont ---|"uses"| Env

    %% PHP Container interacts with Database
    PHPCont -->|"data_query"| MySQL

    %% Click Events for Frontend Component
    click Index "https://github.com/maksimtsarykovich/transaction/blob/main/public/index.php"
    click Assets "https://github.com/maksimtsarykovich/transaction/tree/main/public/assets"
    click ViewTemplates "https://github.com/maksimtsarykovich/transaction/tree/main/views/"

    %% Click Events for Backend Core Component (src/Core)
    click App "https://github.com/maksimtsarykovich/transaction/blob/main/src/Core/App.php"
    click Config "https://github.com/maksimtsarykovich/transaction/blob/main/src/Core/Config.php"
    click Router "https://github.com/maksimtsarykovich/transaction/blob/main/src/Core/Router.php"
    click CoreView "https://github.com/maksimtsarykovich/transaction/blob/main/src/Core/View.php"

    %% Click Events for Controllers (src/Controllers)
    click FileController "https://github.com/maksimtsarykovich/transaction/blob/main/src/Controllers/FileController.php"
    click TransactionController "https://github.com/maksimtsarykovich/transaction/blob/main/src/Controllers/TransactionController.php"
    click AbstractController "https://github.com/maksimtsarykovich/transaction/blob/main/src/Controllers/AbstractController.php"

    %% Click Events for Domain/Model Layer (src/Domain)
    click FileEntity "https://github.com/maksimtsarykovich/transaction/blob/main/src/Domain/Entities/File.php"
    click TransactionEntity "https://github.com/maksimtsarykovich/transaction/blob/main/src/Domain/Entities/Transaction.php"
    click CSVService "https://github.com/maksimtsarykovich/transaction/blob/main/src/Domain/Services/csv/CsvService.php"
    click TransactionProcessor "https://github.com/maksimtsarykovich/transaction/blob/main/src/Domain/Services/csv/TransactionProcessor.php"
    click CurrencyVO "https://github.com/maksimtsarykovich/transaction/blob/main/src/Domain/ValueObjects/Currency.php"

    %% Click Events for Repository Layer (src/Repository)
    click FileRepository "https://github.com/maksimtsarykovich/transaction/blob/main/src/Repository/FileRepository.php"
    click TransactionRepository "https://github.com/maksimtsarykovich/transaction/blob/main/src/Repository/TransactionRepository.php"
    click CurrencyRepository "https://github.com/maksimtsarykovich/transaction/blob/main/src/Repository/CurrencyRepository.php"

    %% Click Events for Infrastructure Component (src/Infrastructure)
    click DBConnector "https://github.com/maksimtsarykovich/transaction/blob/main/src/Infrastructure/Database/DB.php"
    click QueryBuilder "https://github.com/maksimtsarykovich/transaction/blob/main/src/Infrastructure/Database/QueryBuilder.php"
    click CSVFile "https://github.com/maksimtsarykovich/transaction/blob/main/src/Infrastructure/FileSystem/CsvFile.php"
    click HTTPRequest "https://github.com/maksimtsarykovich/transaction/blob/main/src/Infrastructure/Http/Request.php"
    click HTTPResponse "https://github.com/maksimtsarykovich/transaction/blob/main/src/Infrastructure/Http/Response.php"

    %% Click Events for Utility & Exception Handling (src/Utils & src/Exceptions)
    click FinanceCalculator "https://github.com/maksimtsarykovich/transaction/blob/main/src/Utils/FinanceCalculator.php"
    click FlashMessage "https://github.com/maksimtsarykovich/transaction/blob/main/src/Utils/FlashMessage.php"
    click Utils "https://github.com/maksimtsarykovich/transaction/blob/main/src/Utils/Utils.php"
    click FileNotFoundEx "https://github.com/maksimtsarykovich/transaction/blob/main/src/Exceptions/FileNotFound.php"
    click ViewNotFoundEx "https://github.com/maksimtsarykovich/transaction/blob/main/src/Exceptions/ViewNotFoundException.php"

    %% Click Events for Docker Components
    click PHPCont "https://github.com/maksimtsarykovich/transaction/tree/main/docker/php/Dockerfile"
    click Nginx "https://github.com/maksimtsarykovich/transaction/blob/main/docker/nginx/nginx.conf"
    click MySQL "https://github.com/maksimtsarykovich/transaction/tree/main/docker/mysql/Dockerfile"
    click DockerCompose "https://github.com/maksimtsarykovich/transaction/blob/main/docker/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#084298,stroke-width:2px
    classDef backend fill:#d1e7dd,stroke:#0f5132,stroke-width:2px
    classDef database fill:#f8d7da,stroke:#842029,stroke-width:2px
    classDef docker fill:#fff3cd,stroke:#997a00,stroke-width:2px
```
