# linarphy/phosphore architecture

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

- Interactive diagram: https://gitdiagram.com/linarphy/phosphore
- Repository: https://github.com/linarphy/phosphore

## Overview

1. **What this repo is**
   - PHosPhore is a **PHP 8 framework** for building multi-page websites.
   - Its architecture is **file- and folder-driven**: pages, classes, configs, templates, translations, and modules are all organized in parallel directory trees rather than being generated dynamically.

2. **Bootstrap and runtime entry**
   - The runtime starts at **`src/index.php`**.
   - Shared startup logic lives in **`src/func/core/init.php`** and utility helpers in **`src/func/core/utils.php`**.
   - The framework appears to centralize initialization, then load configuration, routing, and page logic from the filesystem.

3. **Core framework layer**
   - **`src/class/core`** contains the foundational abstractions:
     - `Base`, `Managed`, `Manager`
     - `LinkManager`
     - `Token`
     - `DBFactory`
   - This is the framework’s “engine room”: object lifecycle, entity management, relation/link handling, token handling, and database connection creation.

4. **Routing and request dispatch**
   - **`src/class/route`** models URL routing with `Router`, `Route`, `Folder`, and `Parameter`.
   - Route-specific configuration exists in **`src/config/class/route/config.php`**.
   - The route layer likely maps request paths into the corresponding page folder under `src/page/...` and handles path parameters.

5. **Page system**
   - Actual pages are stored under **`src/page`** as standalone page definitions, each with a `page.php`.
   - The repo currently includes at least:
     - `src/page/main/home/page.php`
     - `src/page/error/page.php`
   - This suggests page controllers are filesystem-backed and are likely the endpoint of the routing flow.

6. **Presentation and page elements**
   - UI rendering is split between:
     - **templates/assets** in `src/asset/template`
     - **page element classes** in `src/class/content/pageelement`
   - There are default HTML presets for reusable elements like `PageElement` and `NotificationElement`.
   - `src/asset/css/core/main.css` is the shared stylesheet, so styling is centralized but not tied to a web framework frontend stack.

7. **User, permissions, and notifications**
   - **`src/class/user`** contains domain objects for:
     - `User`, `Visitor`
     - `Role`, `Permission`
     - `Password`, `Token`
     - `Page`, `Notification`
   - Config folders under **`src/config/class/user/...`** indicate these are configurable subsystems, not just data models.
   - This boundary suggests authentication, authorization, and user-visible notifications are first-class framework concerns.

8. **Database layer**
   - Persistence is abstracted through **`src/class/database`**, including `request` and `parameter`.
   - Database setup is configured through **`src/config/class/core/DBFactory/config.php`**.
   - The README says the framework supports **MySQL/MariaDB/PostgreSQL**, so the architecture is database-agnostic at the abstraction layer, with DB-specific behavior hidden behind the factory/request APIs.

9. **Modules and extension points**
   - The repo includes **`src/mod/installed`**, plus documentation for modules under `doc/module`.
   - A hook system is present in **`src/hook/list.xml`**.
   - This means the framework is designed for **plugin/module extension**, with modules installed into a dedicated folder and integrated through hooks rather than direct code modification.

10. **Configuration as a parallel tree**
   - Configuration lives in **`src/config`**, mirrored to the class tree:
     - `class/content/pageelement`
     - `class/core/DBFactory`
     - `class/core/Logger`
     - `class/route`
     - `class/user/*`
   - This structure indicates classes are meant to be portable and configurable by matching config files, rather than hardcoding behavior in constructors.

11. **Localization and message catalogs**
   - Text resources are split into **`src/lang`** and **`src/locale`**.
   - Both mirror the class/page structure and contain `en.*` files for individual components and pages.
   - This means user-facing strings are externalized per subsystem, which is important for any architecture diagram showing presentation, domain, and translation boundaries.

12. **Documentation and conceptual model**
   - The `doc/` tree is not just marketing text; it documents framework concepts such as:
     - folders
     - globals
     - permissions
     - routes
     - variables
     - processes
     - page elements
   - That strongly suggests the framework’s runtime model is built around these named concepts, and the docs likely reflect the intended architecture closely.

13. **Key architectural boundary to diagram**
   - The clearest separation is:
     - **bootstrap/runtime** (`index.php`, `func`)
     - **framework classes** (`class`)
     - **configuration** (`config`)
     - **presentation assets/templates** (`asset`)
     - **pages** (`page`)
     - **translations** (`lang`, `locale`)
     - **modules/hooks** (`mod`, `hook`)
   - This separation is likely the most accurate way to draw the system, since the repo is explicitly organized around those directories.

14. **Likely request flow**
   - A request enters through `index.php`, initialization loads config and core services, routing resolves the target page, page logic assembles content elements, templates render the response, and domain services may access the DB, user subsystem, or installed modules as needed.

Main entry points: [`src/func/core/init.php`](https://github.com/linarphy/phosphore/blob/main/src/func/core/init.php) (init), [`src/index.php`](https://github.com/linarphy/phosphore/blob/main/src/index.php) (index.php), [`src/config/class/core/DBFactory/config.php`](https://github.com/linarphy/phosphore/blob/main/src/config/class/core/DBFactory/config.php) (DBFactory), [`src/page/main/home/page.php`](https://github.com/linarphy/phosphore/blob/main/src/page/main/home/page.php) (home page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_index["index.php<br/>entrypoint<br/>[index.php]"]
  node_init["init<br/>bootstrap<br/>[init.php]"]
  node_utils["utils<br/>helpers<br/>[utils.php]"]
  node_core_config["core config<br/>settings<br/>[config.php]"]
end

subgraph group_core["Core"]
  node_base(("Base<br/>core class"))
  node_manager(("Manager<br/>core class"))
  node_link_manager(("LinkManager<br/>core class"))
  node_db_factory[("DBFactory<br/>core class<br/>[config.php]")]
end

subgraph group_routing["Routing & Pages"]
  node_router{{"Router<br/>route class"}}
  node_route{{"Route"}}
  node_folder{{"Folder<br/>route class"}}
  node_parameter{{"Parameter<br/>route class"}}
  node_main_home["home page<br/>[page.php]"]
  node_error_page["error page<br/>[page.php]"]
end

subgraph group_presentation["Presentation"]
  node_pageelement["PageElement<br/>ui class<br/>[PageElement.html]"]
  node_notification["Notification<br/>ui class"]
  node_main_css["main.css<br/>stylesheet<br/>[main.css]"]
end

subgraph group_data["Data & User"]
  node_user(("User<br/>domain class"))
  node_permission(("Permission<br/>domain class"))
  node_notification_domain(("Notification<br/>domain class"))
end

subgraph group_extensibility["Modules & Hooks"]
  node_hook_list["hook list<br/>hook registry<br/>[list.xml]"]
  node_installed_mods["installed mods<br/>module store"]
end

subgraph group_localization["Localization"]
  node_core_lang["core lang<br/>translations<br/>[en.lang.php]"]
  node_core_locale["core locale<br/>[en.locale.php]"]
end

node_index -->|"boots"| node_init
node_index -->|"loads"| node_core_config
node_init -->|"uses"| node_utils
node_init -->|"creates"| node_router
node_init -->|"binds"| node_db_factory
node_init -->|"registers"| node_hook_list
node_router -->|"resolves"| node_route
node_route -->|"groups"| node_folder
node_route -->|"parses"| node_parameter
node_router -->|"dispatches"| node_main_home
node_router -->|"falls back"| node_error_page
node_main_home -->|"renders"| node_pageelement
node_error_page -->|"renders"| node_notification
node_pageelement -->|"styled by"| node_main_css
node_db_factory -->|"serves"| node_user
node_user -->|"governs"| node_permission
node_user -->|"receives"| node_notification_domain
node_installed_mods -->|"integrates"| node_hook_list
node_core_lang -.->|"describes"| node_base
node_core_locale -.->|"localizes"| node_router

click node_index "https://github.com/linarphy/phosphore/blob/main/src/index.php"
click node_init "https://github.com/linarphy/phosphore/blob/main/src/func/core/init.php"
click node_utils "https://github.com/linarphy/phosphore/blob/main/src/func/core/utils.php"
click node_core_config "https://github.com/linarphy/phosphore/blob/main/src/config/core/config.php"
click node_db_factory "https://github.com/linarphy/phosphore/blob/main/src/config/class/core/DBFactory/config.php"
click node_main_home "https://github.com/linarphy/phosphore/blob/main/src/page/main/home/page.php"
click node_error_page "https://github.com/linarphy/phosphore/blob/main/src/page/error/page.php"
click node_pageelement "https://github.com/linarphy/phosphore/blob/main/src/asset/template/preset/default/html/PageElement.html"
click node_notification "https://github.com/linarphy/phosphore/blob/main/src/asset/template/preset/default/html/NotificationElement.html"
click node_main_css "https://github.com/linarphy/phosphore/blob/main/src/asset/css/core/main.css"
click node_hook_list "https://github.com/linarphy/phosphore/blob/main/src/hook/list.xml"
click node_installed_mods "https://github.com/linarphy/phosphore/tree/main/src/mod/installed"
click node_core_lang "https://github.com/linarphy/phosphore/blob/main/src/lang/core/en.lang.php"
click node_core_locale "https://github.com/linarphy/phosphore/blob/main/src/locale/core/en.locale.php"

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_index,node_init,node_utils,node_core_config,node_core_lang,node_core_locale toneBlue
class node_base,node_manager,node_link_manager,node_db_factory toneAmber
class node_router,node_route,node_folder,node_parameter,node_main_home,node_error_page toneMint
class node_pageelement,node_notification,node_main_css toneRose
class node_user,node_permission,node_notification_domain toneIndigo
class node_hook_list,node_installed_mods toneTeal
```

## Components

### Bootstrap

Entry point and shared startup logic.

- [index.php](https://github.com/linarphy/phosphore/blob/main/src/index.php): entrypoint · Main runtime entry. · `src/index.php`
- [init](https://github.com/linarphy/phosphore/blob/main/src/func/core/init.php): bootstrap · Shared initialization flow. · `src/func/core/init.php`
- [utils](https://github.com/linarphy/phosphore/blob/main/src/func/core/utils.php): helpers · Common runtime helpers. · `src/func/core/utils.php`
- [core config](https://github.com/linarphy/phosphore/blob/main/src/config/core/config.php): settings · Global framework configuration. · `src/config/core/config.php`

### Core

Foundational framework classes and services.

- **Base**: core class · Foundational base object.
- **Manager**: core class · Lifecycle and collection manager.
- **LinkManager**: core class · Relationship and link handling.
- [DBFactory](https://github.com/linarphy/phosphore/blob/main/src/config/class/core/DBFactory/config.php): core class · Database connection factory. · `src/config/class/core/DBFactory/config.php`

### Routing & Pages

Request dispatch and filesystem-backed pages.

- **Router**: route class · Top-level request router.
- **Route**: route class · Concrete route mapping.
- **Folder**: route class · Filesystem route grouping.
- **Parameter**: route class · Path parameter model.
- [home page](https://github.com/linarphy/phosphore/blob/main/src/page/main/home/page.php): page · Main landing page. · `src/page/main/home/page.php`
- [error page](https://github.com/linarphy/phosphore/blob/main/src/page/error/page.php): page · Fallback error page. · `src/page/error/page.php`

### Presentation

Templates, assets, and page elements.

- [PageElement](https://github.com/linarphy/phosphore/blob/main/src/asset/template/preset/default/html/PageElement.html): ui class · Reusable page element abstraction. · `src/asset/template/preset/default/html/PageElement.html`
- [Notification](https://github.com/linarphy/phosphore/blob/main/src/asset/template/preset/default/html/NotificationElement.html): ui class · Notification element preset. · `src/asset/template/preset/default/html/NotificationElement.html`
- [main.css](https://github.com/linarphy/phosphore/blob/main/src/asset/css/core/main.css): stylesheet · Shared base styling. · `src/asset/css/core/main.css`

### Data & User

Persistence and user-related domain objects.

- **User**: domain class · User identity and account model.
- **Permission**: domain class · Authorization rules.
- **Notification**: domain class · User-facing notification model.

### Modules & Hooks

Extension points and installed modules.

- [hook list](https://github.com/linarphy/phosphore/blob/main/src/hook/list.xml): hook registry · Framework hook registry. · `src/hook/list.xml`
- [installed mods](https://github.com/linarphy/phosphore/tree/main/src/mod/installed): module store · Installed module area. · `src/mod/installed`

### Localization

Language and locale resources.

- [core lang](https://github.com/linarphy/phosphore/blob/main/src/lang/core/en.lang.php): translations · Global language resources. · `src/lang/core/en.lang.php`
- [core locale](https://github.com/linarphy/phosphore/blob/main/src/locale/core/en.locale.php): locale · Global locale resources. · `src/locale/core/en.locale.php`

## Connections

- index.php → init: boots · Starts shared initialization.
- index.php → core config: loads · Reads global configuration.
- init → utils: uses · Shares common helpers.
- init → Router: creates · Initializes request dispatch.
- init → DBFactory: binds · Sets up database access.
- init → hook list: registers · Loads extension hooks.
- Router → Route: resolves · Maps a request to a route.
- Route → Folder: groups · Organizes route folders.
- Route → Parameter: parses · Handles route parameters.
- Router → home page: dispatches · Resolves the home page.
- Router → error page: falls back · Uses error page on failure.
- home page → PageElement: renders · Builds the page from elements.
- error page → Notification: renders · Uses notification-oriented UI.
- PageElement → main.css: styled by · Uses shared stylesheet.
- DBFactory → User: serves · Supports persistence for domain objects.
- User → Permission: governs · Authorization boundary.
- User → Notification: receives · User-visible notifications.
- installed mods → hook list: integrates · Modules connect through hooks.
- core lang → Base: describes · Localization for core classes.
- core locale → Router: localizes · Locale resources mirror runtime classes.
