# context-hub/generator architecture

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

- Interactive diagram: https://gitdiagram.com/context-hub/generator
- Repository: https://github.com/context-hub/generator

## Overview

##### Project type and purpose
- This is an open-source, PHP-based CLI tool (“ctx”) that also embeds a small HTTP/MCP server.
- Purpose: automatically gather and assemble context (code, diffs, docs, web pages, MCP items) into markdown files or serve them via an MCP API to LLMs.

##### Top-level architectural components
A. CLI Front-end
- `app.php`, `Console/*Command.php`
- Entrypoint for commands: `ctx init`, `ctx` (generate), `ctx server`, `ctx self-update`, etc.
B. Core Kernel & Bootloaders
- `src/Application/Kernel.php`, `Application/Bootloader/*`
- Microkernel pattern: each Bootloader registers services into the service container (config loader, HTTP client, source fetchers, modifier registry, compiler, logger).
C. Configuration subsystem
- `src/Config` (loader, parser, reader, importer, registry)
- Loads and validates `context.yaml` using `JsonSchema`, merges nested imports, applies exclusions, variables.
D. Source Fetchers & Registry
- `src/Source` and `src/Source/Registry`
- A registry of factories for file, GitHub, GitLab, GitDiff, URL, MCP sources.
E. Modifiers & Content Builders
- `src/Modifier/*`, `src/Lib/Content/*`
- Apply transformations (strip bodies, sanitize, extract PHP signatures), assemble content blocks, render to Markdown.
F. Document Compiler
- `src/Document/Compiler/DocumentCompiler.php`
- Coordinates sources + modifiers + content builders to produce `CompiledDocument` instances.
G. Logging
- `src/Application/Logger/*`
- Pluggable console or file loggers with levels and formatters.
H. MCP Server (optional)
- `src/McpServer/ServerRunner.php`, `Routing/*`, `Action/*`
- Bootloader for server; PSR-7 adapter; attribute-based routing to Action handlers for prompts, tools, resources, projects.
I. External integrations
- `src/Lib/GithubClient`, `src/Lib/GitlabClient`, `src/Lib/HttpClient`, `src/Lib/ComposerClient`
- Strategy and client classes to reach external APIs or local composer.

##### Relationships and data flow
- CLI invocation → Kernel loads Bootloaders → Service container ready → ConsoleDispatcher routes to a Command →
Config subsystem loads `context.yaml` → Source registry fetches content from FS, Git, Web, MCP → Modifiers applied → ContentBuilder/Renders → Markdown file output or stream to stdout.
- Server mode: CLI “ctx server” → Kernel loads MCPServerBootloader → ServerRunner starts HTTP server → Incoming request → PsrRequestAdapter → RouteRegistrar matches attribute → ActionCaller invokes Action → uses Source/Prompt/Tool registries → produces JSON response → Psr7ResponseStrategy writes HTTP response.

##### Architectural patterns and principles
- Microkernel with Bootloader plug-in pattern for modularity.
- Dependency Injection & Service Container to decouple modules.
- Composite & Strategy patterns for config loaders, parsers, renderers, modifiers, update strategies.
- Attribute-driven routing in the MCP server.
- Clear separation of concerns: Configuration, Sourcing, Modification, Compilation, Rendering, Delivery (CLI vs. HTTP).

##### Key technologies and frameworks
- PHP 8+, Composer for autoloading and dependencies.
- JSON Schema validation (`json-schema.json`) and YAML/JSON readers.
- PSR-18 HTTP client, PSR-7 adapters.
- Custom console dispatcher (similar to Symfony Console).
- PHPUnit, Psalm, Rector for testing and static analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Entry["Entry Script\napp.php"]:::cli
        Commands["Console Commands\n(src/Console/)"]:::cli
        Dispatcher["Console Dispatcher\nConsoleDispatcher"]:::cli
    end

    %% Core Kernel
    subgraph "Core Kernel"
        direction TB
        Kernel["Kernel\nsrc/Application/Kernel.php"]:::kernel
        Bootloaders["Bootloaders\n(src/Application/Bootloader/)"]:::kernel
    end

    %% Core Subsystems
    subgraph "Core Subsystems"
        direction TB
        Config["Config Subsystem\n(src/Config/)"]:::core
        Schema["Schema Definition\njson-schema.json"]:::core
        SourceRegistry["Source Registry\nSourceRegistryBootloader"]:::core
        SourceImpl["Source Implementations\n(src/Source/)"]:::core
        Modifiers["Modifiers\n(src/Modifier/)"]:::core
        ContentBuilder["Content Builders\n(src/Lib/Content/)"]:::core
        DocumentCompiler["Document Compiler\nsrc/Document/Compiler/DocumentCompiler.php"]:::core
        CompiledDoc["Compiled Document Model\nCompiledDocument"]:::core
        Logging["Logging\nLoggerFactory"]:::core
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        MCPCommand["MCP Server Command\nMCPServerCommand"]:::server
        McpBootloader["MCP Server Bootloader\nsrc/McpServer/McpServerBootloader.php"]:::server
        ServerRunner["Server Runner\nServerRunner"]:::server
        Routing["Routing\n(src/McpServer/Routing/)"]:::server
        Actions["Action Handlers\n(src/McpServer/Action/)"]:::server
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        FS["File System"]:::external
        GitHub["GitHub API\n(src/Lib/GithubClient/)"]:::external
        GitLab["GitLab API\n(src/Lib/GitlabClient/)"]:::external
        HttpClient["HTTP Client\n(src/Lib/HttpClient/)"]:::external
        ComposerClient["Composer Client\n(src/Lib/ComposerClient/)"]:::external
    end

    %% Relationships - CLI flow
    Entry -->|invokes| Dispatcher
    Dispatcher -->|routes to Command| Commands
    Dispatcher -->|loads| Kernel
    Kernel -->|initializes| Bootloaders
    Bootloaders -->|register| Config
    Bootloaders -->|register| SourceRegistry
    Bootloaders -->|register| Modifiers
    Bootloaders -->|register| ContentBuilder
    Bootloaders -->|register| DocumentCompiler
    Bootloaders -->|register| Logging

    Commands -->|load config| Config
    Config -->|parse/validate| Schema
    Config -->|resolve sources| SourceRegistry
    SourceRegistry -->|fetch| SourceImpl
    SourceImpl -->|read files| FS
    SourceImpl -->|fetch over HTTP| HttpClient
    HttpClient -->|call| GitHub
    HttpClient -->|call| GitLab
    SourceRegistry -->|provide| Modifiers
    Modifiers -->|transform| ContentBuilder
    ContentBuilder -->|render| DocumentCompiler
    DocumentCompiler -->|produce| CompiledDoc
    CompiledDoc -->|output markdown| FS

    %% Server flow
    Entry -->|"ctx server"| MCPCommand
    MCPCommand -->|invoke| Kernel
    Kernel -->|initialize| McpBootloader
    McpBootloader -->|provide| ServerRunner
    ServerRunner -->|start| Routing
    Routing -->|dispatch| Actions
    Actions -->|use| SourceRegistry
    Actions -->|use| DocumentCompiler
    Actions -->|respond| ServerRunner

    %% Click events
    click Entry "https://github.com/context-hub/generator/blob/main/app.php"
    click Commands "https://github.com/context-hub/generator/tree/main/src/Console/"
    click Dispatcher "https://github.com/context-hub/generator/blob/main/src/Application/Dispatcher/ConsoleDispatcher.php"
    click Kernel "https://github.com/context-hub/generator/blob/main/src/Application/Kernel.php"
    click Bootloaders "https://github.com/context-hub/generator/tree/main/src/Application/Bootloader/"
    click Config "https://github.com/context-hub/generator/tree/main/src/Config/"
    click Schema "https://github.com/context-hub/generator/blob/main/json-schema.json"
    click SourceRegistry "https://github.com/context-hub/generator/blob/main/src/Source/Registry/SourceRegistryBootloader.php"
    click SourceImpl "https://github.com/context-hub/generator/tree/main/src/Source/"
    click Modifiers "https://github.com/context-hub/generator/tree/main/src/Modifier/"
    click ContentBuilder "https://github.com/context-hub/generator/tree/main/src/Lib/Content/"
    click DocumentCompiler "https://github.com/context-hub/generator/blob/main/src/Document/Compiler/DocumentCompiler.php"
    click CompiledDoc "https://github.com/context-hub/generator/blob/main/src/Document/Compiler/CompiledDocument.php"
    click Logging "https://github.com/context-hub/generator/blob/main/src/Application/Logger/LoggerFactory.php"
    click MCPCommand "https://github.com/context-hub/generator/blob/main/src/McpServer/Console/MCPServerCommand.php"
    click McpBootloader "https://github.com/context-hub/generator/blob/main/src/McpServer/McpServerBootloader.php"
    click ServerRunner "https://github.com/context-hub/generator/blob/main/src/McpServer/ServerRunner.php"
    click Routing "https://github.com/context-hub/generator/tree/main/src/McpServer/Routing/"
    click Actions "https://github.com/context-hub/generator/tree/main/src/McpServer/Action/"
    click GitHub "https://github.com/context-hub/generator/tree/main/src/Lib/GithubClient/"
    click GitLab "https://github.com/context-hub/generator/tree/main/src/Lib/GitlabClient/"
    click HttpClient "https://github.com/context-hub/generator/tree/main/src/Lib/HttpClient/"
    click ComposerClient "https://github.com/context-hub/generator/tree/main/src/Lib/ComposerClient/"

    %% Styles
    classDef cli fill:#D4F8D4,stroke:#2E8B57,color:#000;
    classDef kernel fill:#E8E8E8,stroke:#888888,color:#000;
    classDef core fill:#FFE8A3,stroke:#CC8400,color:#000;
    classDef server fill:#A3CFF4,stroke:#1E4E8C,color:#000;
    classDef external fill:#F4A3A3,stroke:#8C1E1E,color:#000;
```
