# zerodream-cn/zdocs architecture

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

- Interactive diagram: https://gitdiagram.com/zerodream-cn/zdocs
- Repository: https://github.com/zerodream-cn/zdocs

## Overview

##### Project type and purpose
- This is “ZDocs,” a lightweight PHP-based documentation system with no separate backend UI—every operation (CRUD on docs, category management, user login, theme switching, etc.) happens via the front end.
- It supports Markdown/HTML rendering (front-end), multi-user collaboration (BCRYPT-hashed passwords), categories/subcategories, sorting, and theme toggles.

##### File structure
Top-level files
– config.php: global configuration (DB or file paths, auth settings)
– index.php: front controller; routes all HTTP requests into the ZDocs engine
– README.md, LICENSE
Public assets (static content served directly by the web server)
– public/css/*.css (Materialize, custom styles, theme files)
– public/js/*.js (Markdown renderer, syntax highlighter, app scripts)
– public/webfonts/*
Main application code under zdocs/
– zdocs/zdocs.php: core bootstrap and request dispatcher
– zdocs/includes/
- header.php, footer.php – shared layout templates
- functions.php – business logic and data-access primitives
- actions.php – handlers for create/read/update/delete operations
- render.php – Markdown-to-HTML and view rendering routines

##### README for tech stack and architecture hints
– PHP 7+ runtime on the server
– Static file serving (CSS, JS) by the web server
– Front-end Markdown rendering via Cherry Markdown + Highlight.js
– UI built on Materialize CSS, jQuery, SortableJS, SweetAlert2, plus ECharts for charts
– Data persisted as flat files or small DB (config.php hints at storage config)

a. Main components (containers)
- Browser (Client UI)
- Web Server + PHP Runtime (Apache/Nginx + PHP-FPM)
- File Storage / Data Layer (flat files or small DB)
- External JS/CSS Libraries (Cherry Markdown, Highlight.js, ECharts, Materialize, etc.)
b. Component relationships & data flow
1. Browser requests a page (HTTP GET) → Web Server → index.php (front controller)
2. index.php loads config.php, invokes zdocs/zdocs.php (router)
3. zdocs.php calls includes/actions.php or render.php as per route
4. Business logic in functions.php reads/writes documents & user data from File Storage
5. render.php produces HTML (injects header/footer), returns to Browser
6. Browser fetches CSS/JS from public/ to style UI, handle MD rendering, sorting, dialogs
c. Architectural patterns & principles
- Front-Controller pattern (all requests pass through index.php)
- Modular “includes” for separation of concerns: routing, actions, rendering, business logic, templates
- Single-page-style interactivity using AJAX and JS libraries—no back-end admin pages
- Flat-file or micro-DB persistence (minimal footprint)
- PHP + Apache/Nginx (server)
- Cherry Markdown, Highlight.js (client-side MD rendering)
- Materialize CSS, jQuery, SortableJS, SweetAlert2, ECharts
- BCRYPT (password hashing in PHP)
- File system (or SQLite) as storage

##### Final advice
- Be precise but don’t over-complicate—this system is small and modular
- Where front-end libraries plug into the HTML output for markdown rendering, theme switching, and UI interactions
- Aim for a one-page overview that can be expanded into smaller views if needed for detailed discussions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client-side Browser and Assets
    subgraph "Browser & Frontend" 
        direction TB
        Browser["Browser"]:::client
        subgraph "Static Assets" 
            direction TB
            CSS["CSS Libraries"]:::client
            JS["JS Libraries"]:::client
            Fonts["Webfonts"]:::client
        end
    end

    %% Server-side Application
    subgraph "Web Server & PHP Runtime"
        direction TB
        FC["Front Controller<br/>(index.php)"]:::server
        Config["Global Configuration<br/>(config.php)"]:::server
        ZDocsCore["Core Bootstrap &<br/>Request Dispatcher<br/>(zdocs/zdocs.php)"]:::server

        subgraph "Includes Modules"
            direction TB
            Actions["CRUD Action Handlers<br/>(actions.php)"]:::server
            Functions["Business Logic & Data‐Access<br/>(functions.php)"]:::server
            Render["Markdown-to-HTML & View Engine<br/>(render.php)"]:::server
            Header["Header Template<br/>(header.php)"]:::server
            Footer["Footer Template<br/>(footer.php)"]:::server
        end
    end

    %% Storage Layer
    Storage["Document Store<br/>(Flat Files or SQLite)"]:::storage

    %% Data Flows
    Browser -->|HTTP Request| FC
    FC -->|"load config"| Config
    FC -->|"dispatch"| ZDocsCore
    ZDocsCore -->|"invoke"| Actions
    ZDocsCore -->|"invoke"| Render
    ZDocsCore -->|"use logic"| Functions
    Actions -->|"read/write"| Storage
    Functions -->|"read/write"| Storage
    Render -->|"inject templates"| Header
    Render -->|"inject templates"| Footer
    Render -->|HTTP Response| Browser

    Browser -->|fetch| CSS
    Browser -->|fetch| JS
    Browser -->|fetch| Fonts

    %% Click Events for component mappings
    click FC "https://github.com/zerodream-cn/zdocs/blob/main/index.php"
    click Config "https://github.com/zerodream-cn/zdocs/blob/main/config.php"
    click ZDocsCore "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/zdocs.php"
    click Actions "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/includes/actions.php"
    click Functions "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/includes/functions.php"
    click Render "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/includes/render.php"
    click Header "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/includes/header.php"
    click Footer "https://github.com/zerodream-cn/zdocs/blob/main/zdocs/includes/footer.php"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/materialize.css"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/style.css"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/atom-one-dark.css"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/atom-one-light.css"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/material-icons.css"
    click CSS "https://github.com/zerodream-cn/zdocs/blob/main/public/css/open-sans.css"
    click JS "https://github.com/zerodream-cn/zdocs/blob/main/public/js/highlight.pack.js"
    click JS "https://github.com/zerodream-cn/zdocs/blob/main/public/js/script.js"
    click Fonts "https://github.com/zerodream-cn/zdocs/tree/main/public/webfonts/"

    %% Styles
    classDef client fill:#e0ffe0,stroke:#2d882d,color:#2d882d
    classDef server fill:#e0f0ff,stroke:#1a66cc,color:#1a66cc
    classDef storage fill:#fff4e6,stroke:#cc7a00,color:#cc7a00
```
