# dunglas/frankenphp architecture

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

- Interactive diagram: https://gitdiagram.com/dunglas/frankenphp
- Repository: https://github.com/dunglas/frankenphp

## Overview

##### Main Components

a. Core Components:
- Caddy Web Server Integration (core foundation)
- PHP Runtime Environment
- Worker System
- Early Hints System
- Watcher System
- Metrics System

b. Integration Layers:
- Docker Container Runtime
- Go HTTP Server Interface
- PHP Extension Layer
- Configuration Management

##### Client Layer
- HTTP/HTTPS Clients
- HTTP/2 and HTTP/3 Support
- WebSocket Connections

##### Server Layer
- Caddy Server Integration
- TLS/Certificate Management
- Request Router

##### FrankenPHP Core
- PHP Thread Management
- Worker Mode Handler
- Early Hints System
- Mercure (Real-time) Handler
- Metrics Collector

##### Runtime Layer
- PHP Runtime (8.4)
- Go Runtime
- CGI Handler
- Environment Manager

##### Storage & State Layer
- File System Interface
- State Management
- Session Handling

##### Interaction Flows

- Request/Response Flow
- Worker Communication
- Real-time Events
- Configuration Loading
- Metric Collection Paths

##### Technical Details to Highlight

- CGI implementation (cgi.go)
- Backoff strategies (backoff.go)
- Metrics collection (metrics.go)
- Thread management (thread-*.go files)
- Worker implementation (worker.go)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph CL["Client Layer"]
        Client["HTTP/HTTPS Clients"]
        WS["WebSocket Connections"]
        HTTP["HTTP/2 & HTTP/3"]
    end

    subgraph SL["Server Layer"]
        Caddy["Caddy Server Integration"]:::caddy
        TLS["TLS/Certificate Management"]
        Router["Request Router"]
    end

    subgraph Core["FrankenPHP Core"]
        PHPCore["PHP Runtime Core"]:::phpcore
        ThreadMgr["Thread Management"]:::thread
        WorkerMode["Worker Mode Handler"]:::worker
        EarlyHints["Early Hints System"]
        Mercure["Mercure Handler"]
        Metrics["Metrics Collector"]:::metrics
    end

    subgraph RL["Runtime Layer"]
        PHPRuntime["PHP Runtime (8.4)"]
        GoRuntime["Go Runtime"]
        CGIHandler["CGI Handler"]:::cgi
        EnvMgr["Environment Manager"]:::env
    end

    subgraph STS["Storage & State Layer"]
        FSInterface["File System Interface"]
        StateMgr["State Management"]:::state
        SessionHandler["Session Handling"]
    end

    subgraph IL["Integration Layer"]
        Docker["Docker Container Runtime"]:::docker
        PHPExt["PHP Extension Layer"]:::phpext
        Config["Configuration Management"]:::config
        ErrorHandler["Error Handler"]:::error
    end

    %% Connections
    Client --> Caddy
    WS --> Caddy
    HTTP --> Caddy
    
    Caddy --> Router
    Router --> ThreadMgr
    Router --> WorkerMode
    
    ThreadMgr --> PHPCore
    WorkerMode --> PHPCore
    EarlyHints --> Caddy
    
    PHPCore --> CGIHandler
    PHPCore --> EnvMgr
    
    CGIHandler --> FSInterface
    EnvMgr --> StateMgr
    
    Metrics --> Docker
    PHPCore --> PHPExt
    Config --> Caddy
    ErrorHandler --> WorkerMode

    %% Styles
    classDef caddy fill:#a0d8ef
    classDef phpcore fill:#ffb6c1
    classDef worker fill:#98fb98
    classDef metrics fill:#dda0dd
    classDef thread fill:#f0e68c
    classDef docker fill:#d3d3d3
    classDef phpext fill:#ffa07a
    classDef config fill:#87ceeb
    classDef cgi fill:#98fb98
    classDef env fill:#dda0dd
    classDef state fill:#f0e68c
    classDef error fill:#ff6b6b

    %% Click Events
    click Caddy "https://github.com/dunglas/frankenphp/tree/main/caddy/*"
    click PHPCore "https://github.com/dunglas/frankenphp/blob/main/frankenphp.c"
    click WorkerMode "https://github.com/dunglas/frankenphp/blob/main/worker.go"
    click ThreadMgr "https://github.com/dunglas/frankenphp/blob/main/phpthread.go"
    click Metrics "https://github.com/dunglas/frankenphp/blob/main/metrics.go"
    click Docker "https://github.com/dunglas/frankenphp/tree/main/Dockerfile"
    click PHPExt "https://github.com/dunglas/frankenphp/blob/main/frankenphp.stub.php"
    click Config "https://github.com/dunglas/frankenphp/blob/main/options.go"
    click CGIHandler "https://github.com/dunglas/frankenphp/blob/main/cgi.go"
    click EnvMgr "https://github.com/dunglas/frankenphp/blob/main/env.go"
    click StateMgr "https://github.com/dunglas/frankenphp/blob/main/state.go"
    click ErrorHandler "https://github.com/dunglas/frankenphp/blob/main/backoff.go"
```
