# lithephp/framework architecture

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

- Interactive diagram: https://gitdiagram.com/lithephp/framework
- Repository: https://github.com/lithephp/framework

## Overview

##### Main Components
- Core Framework Engine (src/App.php)
- HTTP Layer
- Request (src/Http/Request.php)
- Router (src/Http/Router.php & src/Orbis/Http/Router.php)
- Response (src/Http/Response.php)
- Middleware
- Configuration (src/Config: app settings, database config)
- Database Integration
- Database Manager (src/Database/Manager.php)
- ORM/Driver Interfaces (Eloquent, PDO, MySQLi via config)
- Migrations & Seeders (Console/Commands/Migrations, Seeders)
- Console CLI (src/Console & Commands: migrations, controllers, models, middleware, server serve)
- Helpers & Utilities (src/Orbis/helpers.php, exceptions)
- External Dependencies
- Composer Autoloader
- Third-party libraries loaded via composer.json
- Testing Suite (tests/* using PHPUnit)

##### Relationships & Data Flows
- HTTP Request Flow:
1. Client → Web Server (PHP-FPM/Apache)
2. Composer Autoloader → App Boots (App.php)
3. App loads Config → instantiates Router
4. Router receives Request → matches route → runs Middleware chain → invokes route callback
5. Callback interacts with Database Manager (if needed) → returns Data
6. Response object sent back to Client
- Database Flow:
- App reads database config → Database Manager connects via chosen driver/ORM → executes queries/migrations
- CLI Flow:
1. Developer runs “php line <command>”
2. Autoloader → Console/Line dispatcher → maps to specific Command class (make:migration, migrate, serve, etc.)
3. Command uses Config, Database Manager, File System to scaffold or run tasks
- Testing Flow:
- PHPUnit loads tests → uses Mocked Config/Database → asserts behavior of Request, Router, Database Manager

##### Architectural Patterns & Principles
- Modularity: clear separation of HTTP, Console, Database, Config
- Middleware chain (inspired by Express.js)
- Convention-over-configuration for Console commands & directory structure
- Single Responsibility in command classes (one command per file)
- Dependency Injection via static configuration in App.php or environment variables
- Extensibility: external ORMs, drivers, custom middleware

##### Elements
- Clear, human-readable labels for each module
- Rectangles for code modules

- The flow of an HTTP request through Lithe
- How console commands plug into the framework
- How configuration and environment variables drive behavior
- The pluggable database layer and migrations system
- The overall modular structure that makes Lithe simple, flexible, and efficient

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        Composer["Composer Autoloader & Third-Party\compo­ser.json"]:::external
    end

    %% Core & Helpers
    subgraph "Core & Helpers"
        App["Core Framework Engine\n(src/App.php)"]:::core
        Helpers["Helpers & Utilities\n(src/Orbis/helpers.php)"]:::helper
        Exception["Exception Handling Utility\n(src/Exceptions/InvalidParameterTypeException.php)"]:::helper
    end

    %% Configuration
    subgraph "Configuration"
        ConfEngines["App Engines\n(src/Config/app/engines.php)"]:::config
        ConfSettings["App Settings\n(src/Config/app/settings.php)"]:::config
        ConfDB["Database Config\n(src/Config/database.php)"]:::config
    end

    %% HTTP Engine
    subgraph "HTTP Engine"
        Request["Request\n(src/Http/Request.php)"]:::http
        RouterCore["Router Core\n(src/Http/Router.php)"]:::http
        RouterOrbis["Router Orbis Override\n(src/Orbis/Http/Router.php)"]:::http
        Middleware["Middleware Chain"]:::http
        Response["Response\n(src/Http/Response.php)"]:::http
    end

    %% Database Layer
    subgraph "Database Layer"
        DBManager["Database Manager\n(src/Database/Manager.php)"]:::db
        DBCylinder[(Database Server)]:::db
    end

    %% Migrations
    subgraph "Migrations"
        MakeMig["Make Migration\n(src/Console/Commands/Migrations/make.php)"]:::cli
        RunMig["Run Migrations\n(src/Console/Commands/Migrations/migrate.php)"]:::cli
        RefreshMig["Refresh Migrations\n(src/Console/Commands/Migrations/refresh.php)"]:::cli
        ResetMig["Reset Migrations\n(src/Console/Commands/Migrations/reset.php)"]:::cli
        RollbackMig["Rollback Migrations\n(src/Console/Commands/Migrations/rollback.php)"]:::cli
    end

    %% Seeders
    subgraph "Seeders"
        MakeSeed["Make Seeder\n(src/Console/Commands/Seeders/make.php)"]:::cli
        RunSeed["Run Seeder\n(src/Console/Commands/Seeders/seed.php)"]:::cli
    end

    %% Generators & Serve
    subgraph "Generators & Server"
        MakeController["Controller Generator\n(src/Console/Commands/Controller/make.php)"]:::cli
        MakeModel["Model Generator\n(src/Console/Commands/Models/make.php)"]:::cli
        MakeMiddleware["Middleware Generator\n(src/Console/Commands/Middleware/make.php)"]:::cli
        ServeCmd["Server Serve\n(src/Console/Commands/Server/serve.php)"]:::cli
    end

    %% CLI Entry
    Line["CLI Entry Point\n(src/Console/Line.php)"]:::cli

    %% Testing Suite
    subgraph "Testing Suite"
        TestApp["AppTest\n(tests/AppTest.php)"]:::test
        TestDB["Database Manager Test\n(tests/Database/ManagerTest.php)"]:::test
        TestReq["HTTP Request Test\n(tests/Http/RequestTest.php)"]:::test
        TestRouter["HTTP Router Test\n(tests/Http/RouterTest.php)"]:::test
    end

    %% Flows
    Composer -->|loads| App
    App -->|loads| ConfEngines
    App -->|loads| ConfSettings
    App -->|loads| ConfDB

    App -->|instantiates| RouterCore
    App -->|instantiates| RouterOrbis

    Request -->|matched by| RouterCore
    Request -->|matched by| RouterOrbis
    RouterCore -->|runs| Middleware
    RouterOrbis -->|runs| Middleware
    Middleware -->|invokes| App
    App -->|processes| DBManager
    DBManager -->|queries| DBCylinder
    DBManager -->|uses config| ConfDB

    App -->|returns| Response

    %% CLI Flow
    Line --> MakeMig
    Line --> RunMig
    Line --> RefreshMig
    Line --> ResetMig
    Line --> RollbackMig

    Line --> MakeSeed
    Line --> RunSeed

    Line --> MakeController
    Line --> MakeModel
    Line --> MakeMiddleware
    Line --> ServeCmd

    MakeMig -->|uses| DBManager
    RunMig -->|uses| DBManager
    RefreshMig -->|uses| DBManager
    ResetMig -->|uses| DBManager
    RollbackMig -->|uses| DBManager
    RunSeed -->|uses| DBManager

    %% Testing Flow
    TestApp -->|tests| App
    TestDB -->|tests| DBManager
    TestReq -->|tests| Request
    TestRouter -->|tests| RouterCore

    %% Click Events
    click App "https://github.com/lithephp/framework/blob/master/src/App.php"
    click Request "https://github.com/lithephp/framework/blob/master/src/Http/Request.php"
    click RouterCore "https://github.com/lithephp/framework/blob/master/src/Http/Router.php"
    click RouterOrbis "https://github.com/lithephp/framework/blob/master/src/Orbis/Http/Router.php"
    click Response "https://github.com/lithephp/framework/blob/master/src/Http/Response.php"
    click ConfEngines "https://github.com/lithephp/framework/blob/master/src/Config/app/engines.php"
    click ConfSettings "https://github.com/lithephp/framework/blob/master/src/Config/app/settings.php"
    click ConfDB "https://github.com/lithephp/framework/blob/master/src/Config/database.php"
    click DBManager "https://github.com/lithephp/framework/blob/master/src/Database/Manager.php"
    click MakeMig "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Migrations/make.php"
    click RunMig "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Migrations/migrate.php"
    click RefreshMig "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Migrations/refresh.php"
    click ResetMig "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Migrations/reset.php"
    click RollbackMig "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Migrations/rollback.php"
    click MakeSeed "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Seeders/make.php"
    click RunSeed "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Seeders/seed.php"
    click MakeController "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Controller/make.php"
    click MakeModel "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Models/make.php"
    click MakeMiddleware "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Middleware/make.php"
    click ServeCmd "https://github.com/lithephp/framework/blob/master/src/Console/Commands/Server/serve.php"
    click Line "https://github.com/lithephp/framework/blob/master/src/Console/Line.php"
    click Helpers "https://github.com/lithephp/framework/blob/master/src/Orbis/helpers.php"
    click Exception "https://github.com/lithephp/framework/blob/master/src/Exceptions/InvalidParameterTypeException.php"
    click Composer "https://github.com/lithephp/framework/blob/master/composer.json"
    click TestApp "https://github.com/lithephp/framework/blob/master/tests/AppTest.php"
    click TestDB "https://github.com/lithephp/framework/blob/master/tests/Database/ManagerTest.php"
    click TestReq "https://github.com/lithephp/framework/blob/master/tests/Http/RequestTest.php"
    click TestRouter "https://github.com/lithephp/framework/blob/master/tests/Http/RouterTest.php"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef http fill:#bbf,stroke:#333,stroke-width:1px
    classDef db fill:#bfb,stroke:#333,stroke-width:1px
    classDef cli fill:#fbc,stroke:#333,stroke-width:1px
    classDef config fill:#ddd,stroke:#333,stroke-width:1px
    classDef helper fill:#eee,stroke:#333,stroke-width:1px
    classDef external fill:#dff,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
```
