# debva/nix architecture

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

- Interactive diagram: https://gitdiagram.com/debva/nix
- Repository: https://github.com/debva/nix

## Overview

##### Project type and purpose
- This is an open-source PHP micro-framework (“NIX PHP Framework”) designed as a reusable library for building web applications.
- It provides a minimal HTTP kernel, routing, middleware support, a service container, database adapters, console commands, task scheduling, and extension points for external APIs.

##### File structure
- Top-level:
- composer.json / vendor (external dependencies via Composer)
- public/index.php (web-server entry point)
- routes/ (user-defined route handlers)
- src/ (framework core classes)
- extensions/ (adapters for external healthcare APIs)
- plugins/ (custom plugins, e.g., task scheduler)
- stubs/ (code-generation templates)
- Patterns:
- Service Container / Facade style (src/App binds & exposes services)
- Adapter pattern for Database (Base, MySQL, PostgreSQL) and for external services in extensions
- Layered: HTTP → Routing → Business logic → Data access

##### README for technical stack
- Core technologies: PHP 7+, Composer, PSR-style autoloading
- Features: request/response, routing, validation, database, transactions, datatable, console & tasks, environment management, custom extensions (e.g., SatuSehat)

##### Main components & relationships
a. Public Entry Point
- public/index.php receives all HTTP traffic → loads Composer autoloader → instantiates Debva\Nix\App → invokes the HTTP kernel
b. HTTP Kernel & Router
- Debva\Nix\App acts as service container & kernel
- src/Http dispatches to src/Route, applies middleware, resolves route callback (in routes/)
c. Middleware & Services
- src/Authentication, Authorization, Validator, Cryptography, Session, Storage, Environment
- Each service registered in the App container, injected/resolved at runtime
d. Business Logic / User Code
- routes/*.php define endpoints using closures or controllers
- services under src/ and plugins may be called here
e. Data Layer
- src/Database\Base + adapters for MySQL, PostgreSQL
- src/Datatable for tabular queries
- src/Transaction, src/Query
f. Console & Scheduler
- src/Console & plugins/task_scheduler.py for cron-style job scheduling
- src/Task for background jobs, src/Telegram for messaging integration
g. Extensions / External Integrations
- extensions/ folder: BPJS, InaCBGs, SatuSehat (FHIR-style adapter)
- Each extension defines Auth, Base client, DataType, Mapping layers
h. Stubs & Code Generation
- stubs/ for generating commands, services, routes, middleware

##### Architectural patterns & principles
- Layered architecture (Presentation / HTTP, Application / Routing & Middleware, Domain / Business logic, Persistence / Database)
- Service Container / Dependency Injection
- Adapter pattern (DB, external APIs)
- Single responsibility per class (e.g., Database/MySQL, Auth vs DataType in extensions)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        WS["Web Server\n(Nginx/Apache + PHP-FPM)"]:::external
        Entry["public/index.php\n(Entry Point)"]:::core
    end

    WS --> Entry

    %% Core Framework
    subgraph "Core Framework"
        App["Debva\\Nix\\App\n(Service Container & Kernel)"]:::core
        Http["HTTP Kernel\n(src/Http.php)"]:::core
        Route["Router Dispatcher\n(src/Route.php)"]:::core
        Authentication["Authentication Service"]:::core
        Authorization["Authorization Service"]:::core
        Validator["Validation Service"]:::core
        Cryptography["Cryptography Service"]:::core
        Session["Session Service"]:::core
        Storage["Storage Service"]:::core
        Environment["Environment Management"]:::core
    end

    Entry --> App
    App --> Http
    Http --> Route
    App --> Authentication
    App --> Authorization
    App --> Validator
    App --> Cryptography
    App --> Session
    App --> Storage
    App --> Environment

    %% User Application
    subgraph "User Application\n(Routes & Controllers)"
        Routes["routes/*.php"]:::app
        SR["welcome.php"]:::app
    end

    Route --> Routes
    Routes --> SR

    %% Persistence Layer
    subgraph "Persistence Layer"
        DBFacade["Database Facade\n(src/Database.php)"]:::core
        Base["Base Adapter\n(src/Database/Base.php)"]:::core
        MySQL["MySQL Adapter\n(src/Database/MySQL.php)"]:::core
        Pg["PostgreSQL Adapter\n(src/Database/PostgreSQL.php)"]:::core
        Datatable["Datatable Support\n(src/Datatable.php)"]:::core
    end

    App --> DBFacade
    DBFacade --> Base
    Base --> MySQL
    Base --> Pg
    App --> Datatable

    %% Extensions & Plugins
    subgraph "Extensions & Plugins"
        BPJS["BPJS Adapter"]:::ext
        InaCBGs["InaCBGs Adapter"]:::ext
        subgraph "SatuSehat Extension"
            SSEntry["extensions/SatuSehat.php"]:::ext
            SSAuth["Auth"]:::ext
            SSBase["Base Client"]:::ext
            SSData["Data Types"]:::ext
            SSMap["Mapping Layers"]:::ext
            SSVal["ValueSets"]:::ext
        end
        TaskSched["Task Scheduler Plugin"]:::ext
    end

    App --> BPJS
    App --> InaCBGs
    App --> SSEntry
    SSEntry --> SSAuth
    SSEntry --> SSBase
    SSEntry --> SSData
    SSEntry --> SSMap
    SSEntry --> SSVal
    App --> TaskSched

    %% CLI Layer
    subgraph "CLI Layer"
        Console["Console Kernel\n(src/Console.php)"]:::core
        Task["Task Definition\n(src/Task.php)"]:::core
        Telegram["Telegram Integration\n(src/Telegram.php)"]:::core
    end

    Console --> Task
    Task --> DBFacade
    Task --> SSEntry

    %% Code Generation Stubs
    subgraph "Code Generation Stubs"
        CommandStub["command.stub"]:::core
        EnvStub["env.stub"]:::core
        MiddlewareStub["middleware.stub"]:::core
        RouteStub["route.stub"]:::core
        ServiceStub["service.stub"]:::core
        TaskStub["task.stub"]:::core
    end

    App --> CommandStub
    App --> EnvStub
    App --> MiddlewareStub
    App --> RouteStub
    App --> ServiceStub
    App --> TaskStub

    %% Click Events
    click App "https://github.com/debva/nix/blob/main/src/App.php"
    click Http "https://github.com/debva/nix/blob/main/src/Http.php"
    click Route "https://github.com/debva/nix/blob/main/src/Route.php"
    click Authentication "https://github.com/debva/nix/blob/main/src/Authentication.php"
    click Authorization "https://github.com/debva/nix/blob/main/src/Authorization.php"
    click Validator "https://github.com/debva/nix/blob/main/src/Validator.php"
    click Cryptography "https://github.com/debva/nix/blob/main/src/Cryptography.php"
    click Session "https://github.com/debva/nix/blob/main/src/Session.php"
    click Storage "https://github.com/debva/nix/blob/main/src/Storage.php"
    click Environment "https://github.com/debva/nix/blob/main/src/Environment.php"
    click SR "https://github.com/debva/nix/blob/main/routes/welcome.php"
    click DBFacade "https://github.com/debva/nix/blob/main/src/Database.php"
    click Base "https://github.com/debva/nix/blob/main/src/Database/Base.php"
    click MySQL "https://github.com/debva/nix/blob/main/src/Database/MySQL.php"
    click Pg "https://github.com/debva/nix/blob/main/src/Database/PostgreSQL.php"
    click Datatable "https://github.com/debva/nix/blob/main/src/Datatable.php"
    click Console "https://github.com/debva/nix/blob/main/src/Console.php"
    click Task "https://github.com/debva/nix/blob/main/src/Task.php"
    click Telegram "https://github.com/debva/nix/blob/main/src/Telegram.php"
    click TaskSched "https://github.com/debva/nix/blob/main/plugins/task_scheduler.py"
    click BPJS "https://github.com/debva/nix/blob/main/extensions/BPJS.php"
    click InaCBGs "https://github.com/debva/nix/blob/main/extensions/InaCBGs.php"
    click SSEntry "https://github.com/debva/nix/blob/main/extensions/SatuSehat.php"
    click SSAuth "https://github.com/debva/nix/blob/main/extensions/SatuSehat/Auth.php"
    click SSBase "https://github.com/debva/nix/blob/main/extensions/SatuSehat/Base.php"
    click SSData "https://github.com/debva/nix/tree/main/extensions/SatuSehat/DataType"
    click SSMap "https://github.com/debva/nix/tree/main/extensions/SatuSehat/Mapping"
    click SSVal "https://github.com/debva/nix/tree/main/extensions/SatuSehat/ValueSet"
    click CommandStub "https://github.com/debva/nix/blob/main/stubs/command.stub"
    click EnvStub "https://github.com/debva/nix/blob/main/stubs/env.stub"
    click MiddlewareStub "https://github.com/debva/nix/blob/main/stubs/middleware.stub"
    click RouteStub "https://github.com/debva/nix/blob/main/stubs/route.stub"
    click ServiceStub "https://github.com/debva/nix/blob/main/stubs/service.stub"
    click TaskStub "https://github.com/debva/nix/blob/main/stubs/task.stub"

    %% Styles
    classDef core fill:#D6E4F0,stroke:#0366D6,color:#0366D6
    classDef app fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef ext fill:#FFD8B5,stroke:#E34A00,color:#E34A00
    classDef external fill:#FEE2E2,stroke:#B31D1D,color:#B31D1D
```
