# wsoft-ws/docs architecture

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

- Interactive diagram: https://gitdiagram.com/wsoft-ws/docs
- Repository: https://github.com/wsoft-ws/docs

## Overview

##### Project Type and Purpose
- WSOFTDocs is a static documentation website that uses Markdown files (stored under a very detailed “docs” folder structure) to serve as content for a website.
- The project is built with Python3, MkDocs, and the Lantana library. It is meant to generate and deploy a documentation site (https://docs.wsoft.ws/), and it has build scripts for both Windows and Unix-based systems.

##### File Structure
- Key Top-Level Directories/Files:
- “docs”: Contains all of the Markdown content divided across different sections (e.g., about, blog, contribute, products, legal, media, etc.).
- “mkdocs.yml”: The configuration file for MkDocs that drives how the static site is built.
- “build.sh” and “build.bat”: Scripts controlling the build process.
- “theme_ext”: Holds custom HTML fragments (before_header.html and after_header.html) to modify the MkDocs-generated theme.
- “tools” and “install.sh”: These provide support for the platform-specific binaries (e.g., various “cei” executables) required during the build process.
- “.github” and related GitHub CI/issue templates indicate community contribution guidelines and issue handling.
- The extensive “docs” directory indicates a well-organized content repository that is the heart of this documentation project.

##### Reading the README for Additional Insights
- The README details how to execute and build WSOFTDocs. It clearly states dependency on Python3, MkDocs, and Lantana.
- It describes the build process and the need to tweak platform-specific settings via build scripts.
- It also outlines how contributors can suggest changes, report issues, or directly edit Markdown files through GitHub, suggesting a strong collaboration and source-control based workflow.

##### Main Components
a. Source Repository (GitHub):
- Contains code, Markdown content in “docs”, configuration files (mkdocs.yml), build scripts, theme customizations, and community contribution/issue handling guidelines.

b. Content Repository:
- “docs” folder: All Markdown content files, subdirectories for separate sections (blog, products, legal, etc.), and associated media/assets.

c. Build Process:
- Build Scripts (“build.sh” and “build.bat”): Initiate the build process.
- Dependencies: Python3 runtime, MkDocs framework, and Lantana library.
- Tools: “tools/cei” executables are used during the build (with platform-specific adjustments).

d. MkDocs Engine:
- Acts as the converter that transforms Markdown files (with configuration from mkdocs.yml and theme extensions from “theme_ext”) into static HTML/CSS/JS files.

e. Generated Static Site and Deployment:
- Output of the MkDocs build process (static files) that are then published and served at https://docs.wsoft.ws/.

f. Contributor and Workflow Components:
- GitHub issue templates, pull request workflows, and contribution guidelines that facilitate editing and reviewing changes in the repository.

##### Relationships and Data Flow
- Developers contribute by updating Markdown files or configuration.
- The source code (Markdown content and configuration) is kept in the GitHub repository.
- When a build is triggered (using build.sh/bat), the build process calls MkDocs—powered by Python3 and Lantana—to read the content from the “docs” directory.
- MkDocs uses the configuration from “mkdocs.yml” and customizations from “theme_ext” to generate static site files.
- The generated static files are then deployed (or served) on the live site.
- Continuous integration and issue tracking (through the .github folder) manage collaboration.

##### Architectural Patterns
- Separation of Concerns: Clear divisions exist between content (docs), build scripts (automation), configuration (mkdocs.yml), and theme customization (theme_ext).
- Static Site Generation: Follows a pipeline paradigm where source Markdown is transformed into deployable static assets.
- Modularity: The “docs” folder is broken down by subject areas (e.g., products, blog), reflecting a modular information architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Source Repository"]:::repo
    B["Content Repository"]:::content
    C["Contributor Workflow"]:::contrib
    C2["Contribution Guidelines (CONTRIBUTING.md)"]:::contrib
    D["Build Process"]:::build
    D1["Build Script (build.sh)"]:::buildScript
    D2["Build Script (build.bat)"]:::buildScript
    D3["Install Script (install.sh)"]:::buildScript
    D4["Tools (cei binaries)"]:::buildTool
    E["MkDocs Engine"]:::engine
    E1["MkDocs Config (mkdocs.yml)"]:::config
    E2["Theme Extensions (theme_ext)"]:::theme
    F["Static Site Output"]:::output
    G["Deployed Website (docs.wsoft.ws)"]:::deployment

    A -->|"contains"| B
    A -->|"contains"| D
    A -->|"contains"| C
    A -->|"contains"| C2
    D --> D1
    D --> D2
    D --> D3
    D --> D4
    D -->|"triggers"| E
    E --> E1
    E --> E2
    E -->|"generates"| F
    F -->|"deployed"| G

    click A "https://github.com/wsoft-ws/docs/blob/master/."

    click B "https://github.com/wsoft-ws/docs/tree/master//docs"

    click D1 "https://github.com/wsoft-ws/docs/blob/master//build.sh"
    click D2 "https://github.com/wsoft-ws/docs/blob/master//build.bat"
    click D3 "https://github.com/wsoft-ws/docs/blob/master//install.sh"
    click D4 "https://github.com/wsoft-ws/docs/tree/master//tools"

    click E1 "https://github.com/wsoft-ws/docs/blob/master//mkdocs.yml"
    click E2 "https://github.com/wsoft-ws/docs/tree/master//theme_ext"

    click C "https://github.com/wsoft-ws/docs/blob/master//.github"
    click C2 "https://github.com/wsoft-ws/docs/blob/master/CONTRIBUTING.md"

    classDef repo fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef content fill:#aed6f1,stroke:#154360,stroke-width:2px;
    classDef contrib fill:#d2b4de,stroke:#4a235a,stroke-width:2px;
    classDef build fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef buildScript fill:#a9dfbf,stroke:#196f3d,stroke-width:2px;
    classDef buildTool fill:#d5f5e3,stroke:#117864,stroke-width:2px;
    classDef engine fill:#fadbd8,stroke:#943126,stroke-width:2px;
    classDef config fill:#f5cba7,stroke:#935116,stroke-width:2px;
    classDef theme fill:#fdebd0,stroke:#7e5109,stroke-width:2px;
    classDef output fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef deployment fill:#d6eaf8,stroke:#21618c,stroke-width:2px;
```
