# fangfengxiang/beacon architecture

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

- Interactive diagram: https://gitdiagram.com/fangfengxiang/beacon
- Repository: https://github.com/fangfengxiang/beacon

## Overview

php-beacon-extension is a PHP-FPM C extension for pool health, governance-worker scheduling, and shared-memory service discovery. Its main flow is: FPM workers publish pool activity and use Beacon APIs; a separate governance process invokes PHP-provided registry callbacks, calculates health, and refreshes the shared node cache for workers. The README also documents built-in FileRegistry operation, load balancing, failover, and Yar integration. Some internal calls and the implementation of the unsampled governance script are not shown, so those links rely on README statements rather than inferred source relationships.

Main entry points: [`beacon_shm.c`](https://github.com/fangfengxiang/beacon/blob/main/beacon_shm.c) (双缓冲共享内存), [`beacon.c`](https://github.com/fangfengxiang/beacon/blob/main/beacon.c) (Module hooks), [`beacon_api_governance.c`](https://github.com/fangfengxiang/beacon/blob/main/beacon_api_governance.c) (Governance API), [`governance.php`](https://github.com/fangfengxiang/beacon/blob/main/governance.php) (Governance loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Extension lifecycle"]
  node_fpm_master["FPM master"]
  node_module_hooks["Module hooks<br/>[beacon.c]"]
  node_worker_lifecycle["Worker lifecycle"]
  node_runtime_config["Runtime configuration<br/>[beacon_config.c]"]
  node_logging["Logging<br/>[beacon_log.c]"]
end

subgraph group_request["Request APIs"]
  node_fpm_workers["FPM workers"]
  node_beacon_api["Beacon API<br/>[beacon_api.c]"]
  node_node_selection["Node selection"]
  node_health_calc["Pool health"]
end

subgraph group_governance["Governance runtime"]
  node_governance_api["Governance API"]
  node_callback_spi["Callback SPI<br/>[beacon_callback.c]"]
  node_governance_script["Governance loop<br/>[governance.php]"]
  node_file_registry["FileRegistry<br/>[governance.php]"]
end

subgraph group_state["Shared state"]
  node_shared_memory[("双缓冲共享内存<br/>[beacon_shm.c]")]
  node_shared_layout["共享数据 layout<br/>[beacon_shm.h]"]
end

node_php_app(("PHP application"))
node_registry["Registry service"]

node_php_app -->|"calls"| node_beacon_api
node_beacon_api -->|"selects nodes"| node_node_selection
node_node_selection -->|"reads node cache"| node_shared_memory
node_php_app -->|"reports health"| node_beacon_api
node_fpm_workers -->|"updates counters"| node_shared_memory
node_fpm_master -->|"runs lifecycle hooks"| node_module_hooks
node_module_hooks -->|"initializes shared state"| node_shared_memory
node_module_hooks -->|"spawns worker"| node_worker_lifecycle
node_worker_lifecycle -->|"executes script"| node_governance_script
node_governance_script -->|"invokes callbacks"| node_callback_spi
node_callback_spi -->|"calls injected logic"| node_registry
node_governance_script -->|"uses API"| node_governance_api
node_governance_api -->|"writes node cache"| node_shared_memory
node_governance_api -->|"calculates health"| node_health_calc
node_health_calc -->|"reads counters"| node_shared_memory
node_file_registry -.->|"provides local registry"| node_registry
node_runtime_config -.->|"configures runtime"| node_module_hooks
node_module_hooks -.->|"logs lifecycle"| node_logging
node_shared_layout -.->|"defines layout"| node_shared_memory

click node_module_hooks "https://github.com/fangfengxiang/beacon/blob/main/beacon.c"
click node_worker_lifecycle "https://github.com/fangfengxiang/beacon/blob/main/beacon_governance_worker.c"
click node_runtime_config "https://github.com/fangfengxiang/beacon/blob/main/beacon_config.c"
click node_beacon_api "https://github.com/fangfengxiang/beacon/blob/main/beacon_api.c"
click node_node_selection "https://github.com/fangfengxiang/beacon/blob/main/beacon_service_select.c"
click node_health_calc "https://github.com/fangfengxiang/beacon/blob/main/beacon_service_health.c"
click node_governance_api "https://github.com/fangfengxiang/beacon/blob/main/beacon_api_governance.c"
click node_callback_spi "https://github.com/fangfengxiang/beacon/blob/main/beacon_callback.c"
click node_governance_script "https://github.com/fangfengxiang/beacon/blob/main/governance.php"
click node_file_registry "https://github.com/fangfengxiang/beacon/blob/main/governance.php"
click node_shared_memory "https://github.com/fangfengxiang/beacon/blob/main/beacon_shm.c"
click node_shared_layout "https://github.com/fangfengxiang/beacon/blob/main/beacon_shm.h"
click node_logging "https://github.com/fangfengxiang/beacon/blob/main/beacon_log.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fpm_master,node_module_hooks,node_worker_lifecycle,node_runtime_config,node_logging toneBlue
class node_fpm_workers,node_beacon_api,node_node_selection,node_health_calc toneAmber
class node_governance_api,node_callback_spi,node_governance_script,node_file_registry toneMint
class node_shared_memory,node_shared_layout toneRose
class node_php_app,node_registry toneIndigo
```

## Components

### Extension lifecycle

- **FPM master**
- [Module hooks](https://github.com/fangfengxiang/beacon/blob/main/beacon.c): `beacon.c`
- [Worker lifecycle](https://github.com/fangfengxiang/beacon/blob/main/beacon_governance_worker.c): `beacon_governance_worker.c`
- [Runtime configuration](https://github.com/fangfengxiang/beacon/blob/main/beacon_config.c): `beacon_config.c`
- [Logging](https://github.com/fangfengxiang/beacon/blob/main/beacon_log.c): `beacon_log.c`

### Request APIs

- **FPM workers**
- [Beacon API](https://github.com/fangfengxiang/beacon/blob/main/beacon_api.c): `beacon_api.c`
- [Node selection](https://github.com/fangfengxiang/beacon/blob/main/beacon_service_select.c): `beacon_service_select.c`
- [Pool health](https://github.com/fangfengxiang/beacon/blob/main/beacon_service_health.c): `beacon_service_health.c`

### Governance runtime

- [Governance API](https://github.com/fangfengxiang/beacon/blob/main/beacon_api_governance.c): `beacon_api_governance.c`
- [Callback SPI](https://github.com/fangfengxiang/beacon/blob/main/beacon_callback.c): `beacon_callback.c`
- [Governance loop](https://github.com/fangfengxiang/beacon/blob/main/governance.php): `governance.php`
- [FileRegistry](https://github.com/fangfengxiang/beacon/blob/main/governance.php): `governance.php`

### Shared state

- [双缓冲共享内存](https://github.com/fangfengxiang/beacon/blob/main/beacon_shm.c): `beacon_shm.c`
- [共享数据 layout](https://github.com/fangfengxiang/beacon/blob/main/beacon_shm.h): `beacon_shm.h`

### Other components

- **PHP application**
- **Registry service**

## Connections

- PHP application → Beacon API: calls (evidence: `README.md`)
- Beacon API → Node selection: selects nodes (evidence: `README.md`)
- Node selection → 双缓冲共享内存: reads node cache (evidence: `README.md`)
- PHP application → Beacon API: reports health (evidence: `README.md`)
- FPM workers → 双缓冲共享内存: updates counters (evidence: `README.md`)
- FPM master → Module hooks: runs lifecycle hooks (evidence: `beacon.c`)
- Module hooks → 双缓冲共享内存: initializes shared state (evidence: `README.md`)
- Module hooks → Worker lifecycle: spawns worker (evidence: `beacon.c`)
- Worker lifecycle → Governance loop: executes script (evidence: `beacon_governance_worker.c`)
- Governance loop → Callback SPI: invokes callbacks (evidence: `README.md`)
- Callback SPI → Registry service: calls injected logic (evidence: `README.md`)
- Governance loop → Governance API: uses API (evidence: `README.md`)
- Governance API → 双缓冲共享内存: writes node cache (evidence: `beacon_api_governance.c`)
- Governance API → Pool health: calculates health (evidence: `README.md`)
- Pool health → 双缓冲共享内存: reads counters (evidence: `beacon_service_health.c`)
- FileRegistry → Registry service: provides local registry (evidence: `README.md`)
- Runtime configuration → Module hooks: configures runtime
- Module hooks → Logging: logs lifecycle (evidence: `beacon.c`)
- 共享数据 layout → 双缓冲共享内存: defines layout (evidence: `beacon_shm.h`)
