# noviscient/factsheet-wiki architecture

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

- Interactive diagram: https://gitdiagram.com/noviscient/factsheet-wiki
- Repository: https://github.com/noviscient/factsheet-wiki

## Overview

##### Project Type and Purpose
- This is an open-source documentation site (“Factsheet-Wiki”) built with MkDocs and intended to explain the code and formulas behind a financial factsheet generation library. It produces a static HTML site (hosted via ReadTheDocs or GitHub Pages) containing the README and additional content in the docs/ folder.

##### File Structure Analysis
- Top‐level config files:
- .readthedocs.yaml – ReadTheDocs build configuration
- mkdocs.yml – MkDocs site configuration
- pyproject.toml – Python packaging metadata
- Content:
- README.md – Landing page and detailed table of contents/formulas
- docs/index.md – Main MkDocs landing page content
- docs/requirements.txt – Python dependencies for docs
- No src/ or code directories: this repo purely generates documentation (the actual calculation.py, plotting.py live elsewhere or are imported).

a. Main Components
1. Authoring Environment (local machine)
– Markdown source: README.md + docs/*.md
– Configuration: mkdocs.yml, pyproject.toml
– Dependencies: docs/requirements.txt
2. Build Engine
– MkDocs (Python static site generator)
– ReadTheDocs build service (CI/CD)
3. Artifact
– Static HTML/CSS/JS site
4. Hosting / Delivery
– ReadTheDocs server or GitHub Pages
– End-user (browser)

b. Relationships and Data Flow
1. Developer writes Markdown under docs/ and README.md
→ mkdocs.yml config instructs MkDocs how to structure navigation and theme
2. mkdocs build (locally or CI)
→ parses Markdown + config → outputs static site files
3. CI (ReadTheDocs or GitHub Actions)
– triggered on push → installs docs/requirements.txt → runs mkdocs build → deploys to hosting
4. End-user requests docs site
→ ReadTheDocs / GitHub Pages serves static assets

c. Architectural Patterns / Design Principles
- Static Site Generator pattern: source files → build → static output
- CI/CD pipeline for documentation: “docs as code” best practice
- Single-page application style navigation via MkDocs theme

d. Key Technologies and Libraries
- MkDocs (Python)
- Markdown (.md files)
- Python packaging (PEP 517 pyproject.toml)
- ReadTheDocs / GitHub Pages for hosting
- CI/CD: ReadTheDocs build or GitHub Actions (implied)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Authoring Environment
    subgraph "Authoring Environment"
        direction TB
        READMENode["README.md"]:::source
        DocsIndex["docs/index.md"]:::source
        MkdocsConfig["mkdocs.yml"]:::source
        Pyproject["pyproject.toml"]:::source
        Requirements["docs/requirements.txt"]:::source
    end

    %% CI/CD Service
    subgraph "CI/CD Build Service"
        direction TB
        CICD["ReadTheDocs Build Service"]:::build
        RTDConfig[".readthedocs.yaml"]:::source
    end

    %% Build Engine
    MkDocs["MkDocs Site Generator"]:::build

    %% Hosting
    subgraph "Static Site Hosting"
        direction TB
        RTDHost["ReadTheDocs Host"]:::host
        GHHost["GitHub Pages Host"]:::host
    end

    %% End-user
    Browser["End-user Browser"]:::user

    %% Relationships
    READMENode -->|writes Markdown| MkDocs
    DocsIndex -->|writes Markdown| MkDocs
    MkdocsConfig -->|"configures build"| MkDocs
    Pyproject -->|"metadata"| READMENode
    Requirements -->|"dependencies"| MkDocs

    MkDocs -->|deploy site| RTDHost
    MkDocs -->|deploy site| GHHost

    READMENode -->|git push trigger| CICD
    DocsIndex -->|git push trigger| CICD
    MkdocsConfig -->|git push trigger| CICD
    RTDConfig -->|configures CI| CICD
    Requirements -->|installed in CI| CICD

    CICD -->|runs mkdocs build| MkDocs

    Browser -->|HTTP GET static assets| RTDHost
    Browser -->|HTTP GET static assets| GHHost

    %% Click Events
    click READMENode "https://github.com/noviscient/factsheet-wiki/blob/master/README.md"
    click DocsIndex "https://github.com/noviscient/factsheet-wiki/blob/master/docs/index.md"
    click MkdocsConfig "https://github.com/noviscient/factsheet-wiki/blob/master/mkdocs.yml"
    click Pyproject "https://github.com/noviscient/factsheet-wiki/blob/master/pyproject.toml"
    click Requirements "https://github.com/noviscient/factsheet-wiki/blob/master/docs/requirements.txt"
    click RTDConfig "https://github.com/noviscient/factsheet-wiki/blob/master/.readthedocs.yaml"

    %% Styles
    classDef source fill:#ADD8E6,stroke:#000,color:#000;
    classDef build fill:#90EE90,stroke:#000,color:#000;
    classDef host   fill:#FFA500,stroke:#000,color:#000;
    classDef user   fill:#D3D3D3,stroke:#000,color:#000;
```
