# monapdx/modular-markup architecture

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

- Interactive diagram: https://gitdiagram.com/monapdx/modular-markup
- Repository: https://github.com/monapdx/modular-markup

## Overview

1. **What this repo is**
   - `Modular Markup` is a **static collection of browser-based HTML tools**.
   - The core architectural idea is: each tool is a self-contained HTML template that behaves like a lightweight app in the browser.

2. **Primary runtime boundary**
   - There is **no backend service, database, or account system**.
   - The entire runtime boundary is the **user’s browser**: templates load locally, accept edits, and persist state client-side.

3. **Main content layer**
   - The actual product surface is in `docs/TEMPLATES/`.
   - This directory contains the reusable HTML tools such as:
     - `EXPENSES.html`
     - `LOG.html`
     - `PROGRESS.html`
     - `PROJECT.html`
     - `QUOTE_LOG.html`
     - `SYMPTOMS.html`
     - `TASKS.html`
     - `blank-tables.html`
     - `knowledge-map.html`
     - `health.html`
     - `movies.html`
     - `sandbox.html`
   - These files are the core “modules” of the system.

4. **Template-first architecture**
   - Each HTML file is a **standalone template** designed to be edited and remixed.
   - The repo emphasizes **editable structure** rather than fixed views:
     - tables are editable
     - headers/categories can be changed
     - rows can be added or deleted
     - layouts can be customized

5. **Persistence flow**
   - User edits are saved in **LocalStorage** inside the browser.
   - The data flow is:
     - open HTML template
     - edit content in-browser
     - automatic local save
     - reopen later and restore prior state
   - This means persistence is **device/browser-local**, not shared or server-synced.

6. **Export/restore flow**
   - A key interaction boundary is the ability to:
     - **Export This Version**
     - **Restore Default**
   - Export turns the customized browser state into a **standalone HTML file**.
   - That exported file becomes a portable artifact that carries the user’s edits without needing the original repo or any service.

7. **Static assets and documentation**
   - `assets/` holds supporting media, especially screenshots and GIFs used in documentation and README examples.
   - The README functions as the main product documentation and showcases the templates as working tools, not mockups.

8. **Hosting/deployment**
   - `.github/workflows/pages.yml` indicates the repo is deployed through **GitHub Pages**.
   - That suggests the repo is distributed as a **static site**, likely serving the HTML templates directly from the repository contents.

9. **Repo organization vs. product organization**
   - `.github/ISSUE_TEMPLATE/` contains issue forms for requests, suggestions, and contributions.
   - This is the project’s **community intake layer**, not part of the runtime app.
   - It supports adding templates, resources, patterns, or reporting issues.

10. **Documentation/template packaging**
   - `docs/TEMPLATES/` also contains items like `STARTER.zip`, `_patch_export_snapshot.py`, and CSS files such as `neo-brutalist.css` and `neo-brutal-overrides.css`.
   - This suggests a packaging/export-oriented workflow around the templates, with styling and snapshot/export support bundled alongside the HTML files.

11. **UI/style system**
   - The visible design system is likely centered on the bundled CSS files in `docs/TEMPLATES/`.
   - The templates appear to share a consistent “neo-brutalist” presentation layer, which is a styling boundary across multiple tools rather than a shared backend component.

12. **Best diagram framing**
   - If you draw this repo, model it as:
     - **GitHub Pages static host**
     - serving **standalone HTML templates**
     - styled by shared CSS/assets
     - with **browser-local persistence via LocalStorage**
     - and an **export path** that produces portable HTML copies.

Main entry points: [`docs/TEMPLATES/index.html`](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/index.html) (Template index), [`docs/TEMPLATES/neo-brutalist.css`](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/neo-brutalist.css) (Neo CSS), [`docs/TEMPLATES/EXPENSES.html`](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/EXPENSES.html) (Expenses), [`docs/TEMPLATES/LOG.html`](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/LOG.html) (Log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosting["Hosting"]
  node_pages_workflow["Pages deploy<br/>GitHub Actions workflow<br/>[pages.yml]"]
  node_static_host["Static site<br/>GitHub Pages host"]
end

subgraph group_templates["Template Library"]
  node_template_index["Template index<br/>HTML entrypoint<br/>[index.html]"]
  node_expenses["Expenses<br/>editable tool<br/>[EXPENSES.html]"]
  node_log["Log<br/>editable tool<br/>[LOG.html]"]
  node_progress["Progress<br/>editable tool<br/>[PROGRESS.html]"]
  node_project["Project<br/>editable tool<br/>[PROJECT.html]"]
  node_tasks["Tasks<br/>editable tool<br/>[TASKS.html]"]
  node_knowledge_map["Knowledge map<br/>editable tool<br/>[knowledge-map.html]"]
  node_other_templates["Other templates<br/>tool bundle"]
end

subgraph group_runtime["Browser Runtime"]
  node_browser_state[("LocalStorage<br/>client persistence")]
  node_export_copy["Exported HTML<br/>portable artifact"]
end

subgraph group_packaging["Styling & Packaging"]
  node_neo_css["Neo CSS<br/>shared styles<br/>[neo-brutalist.css]"]
  node_neo_overrides["Style overrides<br/>shared styles"]
  node_export_helper["Export helper<br/>python utility"]
  node_starter_zip[("Starter pack<br/>bundle<br/>[STARTER.zip]")]
end

subgraph group_docs["Docs & Media"]
  node_readme["README<br/>documentation<br/>[README.md]"]
  node_media["Media<br/>screenshots/gifs"]
end

subgraph group_community["Community Intake"]
  node_issue_templates["Issue forms<br/>community intake<br/>[add-template.yml]"]
end

node_pages_workflow -->|"deploys"| node_static_host
node_static_host -->|"serves"| node_template_index
node_template_index -->|"opens"| node_expenses
node_template_index -->|"opens"| node_log
node_template_index -->|"opens"| node_progress
node_template_index -->|"opens"| node_project
node_template_index -->|"opens"| node_tasks
node_template_index -->|"opens"| node_knowledge_map
node_template_index -.->|"groups"| node_other_templates
node_expenses -->|"saves"| node_browser_state
node_log -->|"saves"| node_browser_state
node_progress -->|"saves"| node_browser_state
node_project -->|"saves"| node_browser_state
node_tasks -->|"saves"| node_browser_state
node_knowledge_map -->|"saves"| node_browser_state
node_browser_state -->|"exports"| node_export_copy
node_export_helper -->|"builds"| node_export_copy
node_neo_css -->|"styles"| node_expenses
node_neo_css -->|"styles"| node_log
node_neo_css -->|"styles"| node_progress
node_neo_css -->|"styles"| node_project
node_neo_css -->|"styles"| node_tasks
node_neo_css -->|"styles"| node_knowledge_map
node_neo_overrides -->|"styles"| node_template_index
node_starter_zip -->|"packages"| node_other_templates
node_readme -->|"documents"| node_template_index
node_readme -->|"illustrates"| node_media
node_issue_templates -.->|"requests"| node_other_templates

click node_pages_workflow "https://github.com/monapdx/modular-markup/blob/main/.github/workflows/pages.yml"
click node_template_index "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/index.html"
click node_expenses "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/EXPENSES.html"
click node_log "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/LOG.html"
click node_progress "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/PROGRESS.html"
click node_project "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/PROJECT.html"
click node_tasks "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/TASKS.html"
click node_knowledge_map "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/knowledge-map.html"
click node_neo_css "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/neo-brutalist.css"
click node_neo_overrides "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/neo-brutal-overrides.css"
click node_export_helper "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/_patch_export_snapshot.py"
click node_starter_zip "https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/STARTER.zip"
click node_readme "https://github.com/monapdx/modular-markup/blob/main/README.md"
click node_media "https://github.com/monapdx/modular-markup/tree/main/assets/gif"
click node_issue_templates "https://github.com/monapdx/modular-markup/blob/main/.github/ISSUE_TEMPLATE/add-template.yml"

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_pages_workflow,node_static_host toneBlue
class node_template_index,node_expenses,node_log,node_progress,node_project,node_tasks,node_knowledge_map,node_other_templates toneAmber
class node_browser_state,node_export_copy toneMint
class node_neo_css,node_neo_overrides,node_export_helper,node_starter_zip toneRose
class node_readme,node_media toneIndigo
class node_issue_templates toneTeal
```

## Components

### Hosting

Static delivery and deployment boundary.

- [Pages deploy](https://github.com/monapdx/modular-markup/blob/main/.github/workflows/pages.yml): GitHub Actions workflow · Build/deploy path for publishing the static site. · `.github/workflows/pages.yml`
- **Static site**: GitHub Pages host · Public static delivery surface for the repository.

### Template Library

Browser-editable HTML tools and entry points.

- [Template index](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/index.html): HTML entrypoint · Landing page that surfaces the browser tools. · `docs/TEMPLATES/index.html`
- [Expenses](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/EXPENSES.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/EXPENSES.html`
- [Log](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/LOG.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/LOG.html`
- [Progress](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/PROGRESS.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/PROGRESS.html`
- [Project](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/PROJECT.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/PROJECT.html`
- [Tasks](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/TASKS.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/TASKS.html`
- [Knowledge map](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/knowledge-map.html): editable tool · Standalone editable HTML template. · `docs/TEMPLATES/knowledge-map.html`
- **Other templates**: tool bundle · Additional browser tools and starter pages bundled with the library.

### Browser Runtime

Client-side persistence and export behavior inside the user’s browser.

- **LocalStorage**: client persistence · Browser-local saved state for edited templates.
- **Exported HTML**: portable artifact · Standalone HTML copy produced from customized browser state.

### Styling & Packaging

Shared presentation, export helpers, and bundled artifacts.

- [Neo CSS](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/neo-brutalist.css): shared styles · Common neo-brutalist presentation layer. · `docs/TEMPLATES/neo-brutalist.css`
- [Style overrides](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/neo-brutal-overrides.css): shared styles · Template-specific visual overrides. · `docs/TEMPLATES/neo-brutal-overrides.css`
- [Export helper](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/_patch_export_snapshot.py): python utility · Snapshot/export support used around template packaging. · `docs/TEMPLATES/_patch_export_snapshot.py`
- [Starter pack](https://github.com/monapdx/modular-markup/blob/main/docs/TEMPLATES/STARTER.zip): bundle · Packaged starter archive distributed with templates. · `docs/TEMPLATES/STARTER.zip`

### Docs & Media

Repository documentation and visual examples.

- [README](https://github.com/monapdx/modular-markup/blob/main/README.md): documentation · Main repository documentation and product showcase. · `README.md`
- [Media](https://github.com/monapdx/modular-markup/tree/main/assets/gif): screenshots/gifs · Documentation assets used to show the templates in use. · `assets/gif`

### Community Intake

Issue templates for requests and submissions.

- [Issue forms](https://github.com/monapdx/modular-markup/blob/main/.github/ISSUE_TEMPLATE/add-template.yml): community intake · Contribution and request forms for templates, resources, and patterns. · `.github/ISSUE_TEMPLATE/add-template.yml`

## Connections

- Pages deploy → Static site: deploys · Publishes the repository as a static site.
- Static site → Template index: serves · Entry point to the template library.
- Template index → Expenses: opens · Links to a representative editable tool.
- Template index → Log: opens · Links to a representative editable tool.
- Template index → Progress: opens · Links to a representative editable tool.
- Template index → Project: opens · Links to a representative editable tool.
- Template index → Tasks: opens · Links to a representative editable tool.
- Template index → Knowledge map: opens · Links to a representative editable tool.
- Template index → Other templates: groups · Covers the remaining bundled template pages.
- Expenses → LocalStorage: saves · Template edits persist in browser-local storage.
- Log → LocalStorage: saves · Template edits persist in browser-local storage.
- Progress → LocalStorage: saves · Template edits persist in browser-local storage.
- Project → LocalStorage: saves · Template edits persist in browser-local storage.
- Tasks → LocalStorage: saves · Template edits persist in browser-local storage.
- Knowledge map → LocalStorage: saves · Template edits persist in browser-local storage.
- LocalStorage → Exported HTML: exports · Saved state can be rendered into a portable HTML file.
- Export helper → Exported HTML: builds · Supports snapshot/export packaging.
- Neo CSS → Expenses: styles · Shared presentation layer used by templates.
- Neo CSS → Log: styles · Shared presentation layer used by templates.
- Neo CSS → Progress: styles · Shared presentation layer used by templates.
- Neo CSS → Project: styles · Shared presentation layer used by templates.
- Neo CSS → Tasks: styles · Shared presentation layer used by templates.
- Neo CSS → Knowledge map: styles · Shared presentation layer used by templates.
- Style overrides → Template index: styles · Overrides the shared template presentation.
- Starter pack → Other templates: packages · Bundled starter/archive material for remixing templates.
- README → Template index: documents · Shows the templates as the main product surface.
- README → Media: illustrates · Uses screenshots and GIFs to demonstrate the tools.
- Issue forms → Other templates: requests · Community intake for new templates and related contributions.
