# ba-calderonmorales/my-life-as-a-dev architecture

> Architecture diagram of the GitHub repository ba-calderonmorales/my-life-as-a-dev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ba-calderonmorales/my-life-as-a-dev
- Repository: https://github.com/ba-calderonmorales/my-life-as-a-dev

## Overview

##### Project type and purpose
- This is a **docs-as-code static site generator** built with **MkDocs (Material theme)**, extended by:
- Custom **Python plugins** (`mkdocs_plugins/ai_plugin.py`, versioning plugin)
- A **Rust-based CLI tool** (`scripts/doc-cli.rs`, `bump-version.rs`, etc.) wrapped by `doc-cli.sh`
- **GitHub Actions** → **GitHub Pages** for CI/CD deployments
- **Browser-based AI Playground** calling the **OpenAI REST API**

##### File structure
- **Content sources**: `docs/` (Markdown, assets, theme overrides)
- **Build config**: `mkdocs.yml`, `requirements.txt`, `setup.py`
- **Plugins**: `mkdocs_plugins/` (Python modules for AI integration, versioning)
- **CLI tooling**: `scripts/` (Rust Cargo projects), `doc-cli.sh`
- **CI/CD**: `.github/workflows/github_pages.yml`, Dependabot, test workflows
- **Hosting artifacts**: generated `site/` directory → published via GitHub Pages

##### Key sections from the README
- **Local dev**: Python venv → `pip install -r requirements.txt` → `mkdocs serve` (with PYTHONPATH)
- **AI plugin**: build-time OpenAI integration (via env var or `.env`)
- **Rust CLI**: startup, bump-version, deploy commands
- **CI**: on push → compile Rust → `mkdocs build` → mike versioning → deploy to GitHub Pages
- **Browser AI Demo**: JS widgets (`docs/assets/js/components/aiPlayground`) invoke OpenAI directly

##### Main components & interactions (to model
a. **Developer Local Environment**
- Python interpreter + MkDocs + custom Python plugins
- Rust toolchain (Cargo) + `doc-cli.sh` wrapper
- .env / environment variables for OpenAI key
b. **CI/CD Pipeline (GitHub Actions)**
- Checkout source → compile Rust → install Python deps → `mkdocs build --verbose` → mike versioning → deploy to GitHub Pages
c. **Static Site Hosting**
- GitHub Pages serves the generated `site/` directory
d. **End-User Browser**
- Requests HTML/CSS/JS assets
- Renders interactive pages (AI-Playground widgets, particle backgrounds, etc.)
- For AI demo, front-end JS calls the OpenAI REST API using the user’s provided API key
e. **OpenAI API**
- External service for run-time JS calls (Playground)
- Also used at build time by Python AI plugin if configured

##### Architectural patterns & principles
- **Static site generation (SSG)** with **plugin-based extension** (Python plugin hook points)
- **Docs-as-code**: Markdown source under version control, repeatable build
- **Micro-tooling**: Rust CLI implements SOLID, DRY, error handling, interactive menus
- **CI/CD as code**: workflow files in `.github/workflows` automate build/test/deploy
- **Separation of concerns**: content (docs/), build logic (mkdocs plugins), deployment (GitHub Actions)

##### Final checklist
- **essential modules**: `docs/`, `mkdocs_plugins/`, `scripts/`, GitHub Actions, GitHub Pages, Browser, OpenAI

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Developer Local Environment
  subgraph "Developer Local Environment"
    direction TB
    PY["Python Interpreter & venv"]:::devtools
    MKDOCS["MkDocs (mkdocs.yml)"]:::devtools
    REQ["requirements.txt"]:::devtools
    SETUP["setup.py"]:::devtools
    AI_PLUGIN["AI Plugin (mkdocs_plugins/ai_plugin.py)"]:::devtools
    DOCS_SRC["Docs-as-code Content (docs/)"]:::devtools
    DOC_CLI_SH["CLI Wrapper (doc-cli.sh)"]:::devtools
    subgraph "Rust CLI Toolchain"
      direction TB
      CARGO_TOML["Cargo.toml & Cargo.lock"]:::devtools
      DOC_CLI_RS["doc-cli.rs"]:::devtools
      BUMP_RS["bump-version.rs"]:::devtools
      DEPLOY_RS["deploy-all-versions.rs"]:::devtools
      STARTUP_RS["startup.rs"]:::devtools
    end
    DOCS_SRC -->|sources| MKDOCS
    MKDOCS -->|uses| AI_PLUGIN
    MKDOCS -->|reads| MKDOCS
    MKDOCS -->|reads| REQ
    MKDOCS -->|reads| SETUP
    DOC_CLI_SH -->|invokes| DOC_CLI_RS
    DOC_CLI_SH -->|invokes| BUMP_RS
    DOC_CLI_SH -->|invokes| DEPLOY_RS
    DOC_CLI_SH -->|invokes| STARTUP_RS
  end

  %% CI/CD Pipeline
  subgraph "CI/CD Pipeline (GitHub Actions)"
    direction TB
    CHECKOUT["Checkout Source"]:::ci
    COMPILE_RUST["Compile Rust CLI"]:::ci
    INSTALL_PY["Install Python Deps"]:::ci
    MKDOCS_BUILD["mkdocs build --verbose"]:::ci
    MIKE_VERSION["Mike Versioning"]:::ci
    DEPLOY_ACTION["Deploy to GitHub Pages"]:::ci
    CHECKOUT --> COMPILE_RUST
    COMPILE_RUST --> INSTALL_PY
    INSTALL_PY --> MKDOCS_BUILD
    MKDOCS_BUILD --> MIKE_VERSION
    MIKE_VERSION --> DEPLOY_ACTION
  end

  %% Hosting Infrastructure
  subgraph "Hosting Infrastructure"
    direction TB
    SITE_DIR["Generated site/"]:::hosting
    GITHUB_PAGES["GitHub Pages"]:::hosting
    DEPLOY_ACTION --> SITE_DIR
    SITE_DIR --> GITHUB_PAGES
  end

  %% Client / Runtime
  subgraph "Client / Runtime"
    direction TB
    BROWSER["End-User Browser"]:::client
    AI_WIDGETS["AI Playground Widgets"]:::client
    VERSION_SELECTOR_HTML["Version Selector UI (partials/version-selector.html)"]:::client
    VERSION_SELECTOR_JS["VersionSelector JS (docs/assets/js/custom/versionSelector)"]:::client
    AI_DEMO_DIR["AI Demo Assets (docs/ai-demo/ai-playground)"]:::client
    AI_COMPONENTS["AI Components (docs/assets/js/components/aiPlayground)"]:::client
    BROWSER -->|fetch assets| SITE_DIR
    BROWSER -->|renders| AI_WIDGETS
    AI_WIDGETS -->|UI template| VERSION_SELECTOR_HTML
    AI_WIDGETS -->|JS code| VERSION_SELECTOR_JS
    AI_WIDGETS -->|demo code| AI_DEMO_DIR
    AI_WIDGETS -->|components| AI_COMPONENTS
    AI_WIDGETS -->|call| OPENAI_API
  end

  %% External Services
  OPENAI_API["OpenAI REST API"]:::external

  %% Build-time AI integration
  AI_PLUGIN -->|API call at build| OPENAI_API

  %% Additional Mappings
  DOCS_SRC --> SITE_DIR
  MKDOCS_BUILD --> SITE_DIR
  DOC_CLI_SH --> DEPLOY_ACTION

  %% Component Mappings Click Events
  click DOCS_SRC "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/"
  click MKDOCS "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/mkdocs.yml"
  click REQ "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/requirements.txt"
  click SETUP "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/setup.py"
  click AI_PLUGIN "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/mkdocs_plugins/ai_plugin.py"
  click VERSION_SELECTOR_HTML "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/docs/overrides/partials/version-selector.html"
  click VERSION_SELECTOR_JS "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/assets/js/custom/versionSelector"
  click DOC_CLI_RS "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/scripts/doc-cli.rs"
  click BUMP_RS "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/scripts/bump-version.rs"
  click DEPLOY_RS "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/scripts/deploy-all-versions.rs"
  click STARTUP_RS "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/scripts/startup.rs"
  click CARGO_TOML "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/scripts/Cargo.toml"
  click DOC_CLI_SH "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/doc-cli.sh"
  click CHECKOUT "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/.github/workflows/github_pages.yml"
  click COMPILE_RUST "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/.github/tests/test_github_pages.yml"
  click INSTALL_PY "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/.github/dependabot.yml"
  click AI_DEMO_DIR "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/ai-demo/ai-playground"
  click AI_COMPONENTS "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/assets/js/components/aiPlayground"
  click DOCS_SRC "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/overrides/"
  click AI_COMPONENTS "https://github.com/ba-calderonmorales/my-life-as-a-dev/tree/main/docs/assets/templates/"
  click SITE_DIR "https://github.com/ba-calderonmorales/my-life-as-a-dev/blob/main/versions.json"

  %% Styles
  classDef devtools fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px
  classDef ci fill:#E6FFED,stroke:#28A745,color:#28A745,stroke-width:1px
  classDef hosting fill:#FFF5BA,stroke:#FFD33D,color:#995C00,stroke-width:1px
  classDef client fill:#FFE3EC,stroke:#D6336C,color:#D6336C,stroke-width:1px
  classDef external fill:#E5E5E5,stroke:#6C757D,color:#495057,stroke-width:1px
```
