# kn0ws/diba-php architecture

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

- Interactive diagram: https://gitdiagram.com/kn0ws/diba-php
- Repository: https://github.com/kn0ws/diba-php

## Overview

##### Project type and purpose
- This is “DIBA PHP,” a lightweight, intent-driven microframework written in PHP.
- Purpose: let application developers declare “what they want to do” via YAML Intents, then resolve and execute them through a chain of Executors, dispatch events/jobs, generate responses, and optionally handle asynchronous workflows.

##### File structure
- Top-level directories:
- public/ – HTTP entrypoint (`index.php`) behind Apache/nginx
- app/ – User application modules (Constraints, Intents, Executors, Models, Services, Views, etc.)
- diba/ – Core framework (Kernel, IntentResolver, ExecutorDispatcher, MiddlewareRunner, EventQueue, JobQueue, etc.)
- cli/ – CLI interface and commands (`diba.php`, worker, make- commands)
- config/ – Configuration (DB, routes, events, queue, middleware)
- database/ – Connection manager, migrations
- plugins/ – Pluggable extensions (Intents, Executors, Services)
- stubs/ – Boilerplate templates for code generators
- logs/ – Runtime logs
- Key config files: `config/env.php`, `database.php`, `route_types.php`
- CLI commands under `cli/commands` generate or introspect Intents/Executors/Responses/Constraints/Jobs/Plugins.

##### README for additional insights
- Confirms the Intent → Executors → Effects → on_effects chain, state-emitted events, async job queue (worker).
- Notes MVC-style Views, custom Responses, flexible middleware/constraints, DB connectivity, plugin architecture, CLI tooling for rapid scaffolding and documentation.

##### Main components
a. Frontend (HTTP)
- Apache/Nginx → public/index.php
- diba\Kernel: bootstrap, routing to Intents
b. Intent Resolver & Router
- Reads YAML Intents (app/Intents + plugins)
- Matches incoming route/event to an Intent definition
c. Middleware/Constraints
- diba\MiddlewareRunner applies pre/post filters
- app/Constraints + diba/Middlewares
d. Executor Dispatcher
- Chains Executors (app/Executors, services) per Intent
e. Services & Models
- Business logic services (app/Services, plugins)
- DB access via Eloquent models (app/Models) and database/ConnectionManager
f. State & Event System
- diba\State emits effects → diba\EventQueue → jobs
g. Job Queue & Worker
- Configured queue (Redis/DB) → worker.php runs async Executors
h. Response layer
- diba\Responses (Json, Html, View, Redirect) + custom ones (app/Responses)
- HTTP response back to client
i. CLI subsystem
- cli/diba.php → commands for scaffolding, simulation, docs, queue runner

##### Relationships and interactions
- HTTP Request → Kernel → Router → IntentResolver
- IntentResolver → MiddlewareRunner (constraints) → ExecutorDispatcher
- ExecutorDispatcher → sequential calls to Executors → underlying Services → Models → DB
- Executors may call State::emit() → EventQueue → add Job to JobQueue
- Worker process dequeues jobs → ExecutorDispatcher → follow-on Executors
- Final Response object → sent back via Kernel
- CLI commands invoke Kernel for simulate, validate, graph Intent definitions, generate code, run queue, run tests.

##### Architectural patterns/design principles
- Intent-Driven Architecture: decouples “what” from “how.”
- Chain of Responsibility (Executor chain).
- Event-driven / Pub-Sub for async effects.
- MVC-style Views for HTML.
- Plugin architecture—Intents/Executors/Services can live outside core code.
- Code generation and config-driven patterns for rapid development.

##### Technologies & frameworks
- PHP >= 8.0, Composer for dependency management.
- Eloquent ORM for models (Laravel components).
- YAML for Intent definitions.
- PSR-4 autoloading.
- Optional Redis/DB for queue (config/queue.php).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HTTP Entry
    subgraph "HTTP Entry" 
        WS["Web Server (Apache/Nginx)"]:::infrastructure
        INDEX["public/index.php"]:::infrastructure
    end

    %% Core Framework
    subgraph "Core Framework" 
        KERNEL["diba/Kernel"]:::core
        ROUTER["IntentRouter"]:::core
        INTENT_RESOLVER["IntentResolver"]:::core
        MIDDLEWARE["MiddlewareRunner"]:::core
        CONSTRAINT_CHECKER["ConstraintChecker"]:::core
        EXECUTOR_DISPATCHER["ExecutorDispatcher"]:::core
        STATE["State"]:::core
        EVENT_EMITTER["EventEmitter"]:::core
        EVENT_QUEUE["EventQueue"]:::core
        JOB_QUEUE["JobQueue"]:::core
        REQUEST["Request"]:::core
        RESPONSE["Response"]:::core
    end

    %% App Modules
    subgraph "App Modules" 
        INTENTS["app/Intents"]:::app
        CONSTRAINTS["app/Constraints"]:::app
        EXECUTORS["app/Executors"]:::app
        SERVICES["app/Services"]:::app
        MODELS["app/Models"]:::app
        VIEWS["app/Views"]:::app
        RESPONSES_APP["app/Responses"]:::app
    end

    %% Plugins
    subgraph "Plugins" 
        P_INTENTS["plugins/Sample/Intents"]:::plugin
        P_EXECUTORS["plugins/Sample/Executors"]:::plugin
        P_SERVICES["plugins/Sample/Services"]:::plugin
    end

    %% Config
    subgraph "Configuration" 
        ENV["config/env.php"]:::config
        ROUTES_CONF["config/route_types.php"]:::config
        MIDDLEWARE_CONF["config/middlewares.php"]:::config
        EVENTS_CONF["config/events.php"]:::config
        QUEUE_CONF["config/queue.php"]:::config
    end

    %% Database
    subgraph "Database" 
        DB["DB (MySQL/Postgres/SQLite)"]:::infrastructure
        CONNECTOR["database/ConnectionManager.php"]:::infrastructure
        MIGRATIONS["database/migrations"]:::infrastructure
    end

    %% CLI
    subgraph "CLI Subsystem" 
        CLI["cli/diba.php"]:::cli
        CMDS["cli/commands"]:::cli
        UTILS["cli/utils.php"]:::cli
        WORKER["cli/worker.php"]:::cli
    end

    %% Stubs & Logs
    subgraph "Stubs & Logging"
        STUBS["stubs/"]:::config
        LOGS["logs/"]:::infrastructure
    end

    %% Request Flow
    WS --> INDEX
    INDEX --> REQUEST
    REQUEST --> KERNEL
    KERNEL --> ROUTER
    ROUTER --> INTENT_RESOLVER
    INTENT_RESOLVER --> MIDDLEWARE
    MIDDLEWARE --> CONSTRAINT_CHECKER
    CONSTRAINT_CHECKER --> EXECUTOR_DISPATCHER
    EXECUTOR_DISPATCHER --> EXECUTORS
    EXECUTORS --> SERVICES
    SERVICES --> MODELS
    MODELS --> DB
    EXECUTOR_DISPATCHER --> STATE
    STATE --> EVENT_EMITTER
    EVENT_EMITTER --> EVENT_QUEUE
    EVENT_QUEUE -->|async| JOB_QUEUE
    JOB_QUEUE -->|async| WORKER
    WORKER --> EXECUTOR_DISPATCHER
    EXECUTOR_DISPATCHER --> RESPONSE
    RESPONSE --> INDEX

    %% Config loading
    KERNEL --> ENV
    KERNEL --> ROUTES_CONF
    KERNEL --> MIDDLEWARE_CONF
    STATE --> EVENTS_CONF
    JOB_QUEUE --> QUEUE_CONF

    %% App & Plugins integration
    INTENT_RESOLVER --> INTENTS
    INTENT_RESOLVER --> P_INTENTS
    MIDDLEWARE --> CONSTRAINTS
    MIDDLEWARE --> P_SERVICES
    EXECUTOR_DISPATCHER --> P_EXECUTORS
    EXECUTOR_DISPATCHER --> EXECUTORS
    EXECUTOR_DISPATCHER --> SERVICES
    VIEWS --> RESPONSES_APP

    %% CLI interactions
    CLI --> KERNEL
    CLI --> WORKER
    CLI --> CONNECTOR
    CLI --> CMDS

    %% Click Events
    click INDEX "https://github.com/kn0ws/diba-php/blob/main/public/index.php"
    click KERNEL "https://github.com/kn0ws/diba-php/blob/main/diba/Kernel.php"
    click INTENT_RESOLVER "https://github.com/kn0ws/diba-php/blob/main/diba/IntentResolver.php"
    click ROUTES_CONF "https://github.com/kn0ws/diba-php/blob/main/config/route_types.php"
    click MIDDLEWARE "https://github.com/kn0ws/diba-php/blob/main/diba/MiddlewareRunner.php"
    click CONSTRAINT_CHECKER "https://github.com/kn0ws/diba-php/blob/main/diba/ConstraintChecker.php"
    click INTENTS "https://github.com/kn0ws/diba-php/tree/main/app/Intents"
    click CONSTRAINTS "https://github.com/kn0ws/diba-php/blob/main/app/Constraints/RequireName.php"
    click EXECUTOR_DISPATCHER "https://github.com/kn0ws/diba-php/blob/main/diba/ExecutorDispatcher.php"
    click EXECUTORS "https://github.com/kn0ws/diba-php/blob/main/app/Executors/WelcomeExecutor.php"
    click STATE "https://github.com/kn0ws/diba-php/blob/main/diba/State.php"
    click EVENT_EMITTER "https://github.com/kn0ws/diba-php/blob/main/diba/EventEmitter.php"
    click EVENT_QUEUE "https://github.com/kn0ws/diba-php/blob/main/diba/EventQueue.php"
    click EVENTS_CONF "https://github.com/kn0ws/diba-php/blob/main/config/events.php"
    click JOB_QUEUE "https://github.com/kn0ws/diba-php/blob/main/diba/JobQueue.php"
    click WORKER "https://github.com/kn0ws/diba-php/blob/main/cli/worker.php"
    click QUEUE_CONF "https://github.com/kn0ws/diba-php/blob/main/config/queue.php"
    click REQUEST "https://github.com/kn0ws/diba-php/blob/main/diba/Request.php"
    click RESPONSE "https://github.com/kn0ws/diba-php/blob/main/diba/Response.php"
    click STUBS "https://github.com/kn0ws/diba-php/tree/main/stubs/"
    click DB "https://github.com/kn0ws/diba-php/blob/main/database/ConnectionManager.php"
    click CONNECTOR "https://github.com/kn0ws/diba-php/blob/main/database/ConnectionManager.php"
    click CLI "https://github.com/kn0ws/diba-php/blob/main/cli/diba.php"
    click CMDS "https://github.com/kn0ws/diba-php/tree/main/cli/commands/"
    click VIEWS "https://github.com/kn0ws/diba-php/blob/main/app/Views/welcome.php"
    click SERVICES "https://github.com/kn0ws/diba-php/tree/main/app/Services/"
    click MODELS "https://github.com/kn0ws/diba-php/tree/main/app/Models/"
    click RESPONSES_APP "https://github.com/kn0ws/diba-php/tree/main/app/Responses/"

    %% Styles
    classDef infrastructure fill:#D6E9FF,stroke:#333,stroke-width:1px
    classDef core fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef app fill:#E6F9E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFF0E6,stroke:#333,stroke-width:1px
    classDef config fill:#F9E0F9,stroke:#333,stroke-width:1px
    classDef cli fill:#E6FFE6,stroke:#333,stroke-width:1px
```
