# cristianvasquez/hypermedia-agents architecture

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

- Interactive diagram: https://gitdiagram.com/cristianvasquez/hypermedia-agents
- Repository: https://github.com/cristianvasquez/hypermedia-agents

## Overview

##### Project type and purpose
- Type: Static documentation website (built with GitBook)
- Purpose:
– Host markdown-based docs (“tutorial.md”, “hypermedia-spec-components.md”, etc.)
– Provide an interactive, client-side hypermedia/ArchiMate modeling viewer (in html/js/model.js)
– Serve hints for ArchiMate elements (html/hints/…)

##### High-level architecture components
A. Content authoring & build pipeline
1. Markdown source files (.md)
2. GitBook tool (Node.js-based)
3. Static site generator → produces html/, .gitbook/assets/
4. CI/CD or manual deploy to web host (e.g., GitHub Pages or any HTTP server)
B. Hosting / Delivery
1. HTTP server (static file host)
2. Assets: HTML, CSS, JS, images, font files
C. Client (browser)
1. UI shell (index.html + frame.js)
2. Content views (html/…/views/*.html)
3. Model viewer (html/…/elements/model.html + model.js + alasql)
4. Styling & layout: Bootstrap, jQuery UI Layout, custom CSS

##### Data flows & interactions
- Author → (GitBook build) → Static files → HTTP Server
- Browser requests index.html → loads CSS + JS libs → fetches view fragments (views/*.html) → renders pages

##### Architectural patterns & design principles
- Static site generation (“Jamstack”): content pre-built, served as static assets
- Client-side MVC:
– Model: data tables (in memory via alasql)
– View: HTML templates in html/…/elements/*.html, rendered by model.js
– Controller: frame.js handles user navigation & page assembly
- Separation of concerns:
– Build pipeline separate from runtime (client)
– Content (Markdown) separate from presentation (HTML/CSS) and logic (JS)
- Extensibility:
– New hint templates added to html/hints/ without changing code
– Additional Markdown topics simply rebuild into new pages

##### Key details to capture
- The “Jamstack” static-site build (GitBook → html/)
- Hosting environment (static HTTP server)
- Client architecture: frame.js orchestrator, model.js + alasql engine, HTML hint-templates, CSS/layout libs
- Data flow from prebuilt assets to dynamic in-browser model queries

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Build Pipeline"
    MD["Markdown Source Files (.md)"]:::build
    HS["SUMMARY.md & README.md"]:::build
    SB["GitBook Build Assets (.gitbook/)"]:::build
    SA["GitBook Assets (.gitbook/assets/)"]:::build
    GS["Static Site Generator (GitBook)"]:::build
    MD --> GS
    HS --> GS
    SB --> GS
    SA --> GS
    GS --> HTML["Generated HTML Site (html/)"]:::server
  end

  subgraph "Hosting / Delivery"
    HSrv["HTTP Server (Static File Host)"]:::server
    HTML --> HSrv
  end

  subgraph "Browser Client"
    AModel["UI Shell<br>(index.html & frame.js)"]:::client
    ASets["Static Assets<br>(CSS, JS, libraries)"]:::client
    Views["Content Views<br>(views/*.html)"]:::client
    Templates["Model Viewer & Empty Templates"]:::client
    Logic["Interactive Modeling Logic<br>(model.js & alasql)"]:::client
    Hints["ArchiMate Hint Templates<br>(html/hints/)"]:::client

    HSrv -->|"HTTP GET"| AModel
    AModel --> ASets
    AModel --> Views
    AModel --> Templates
    AModel --> Logic
    AModel --> Hints
    Logic --> Templates
    Logic --> Hints
  end

  click MD "https://github.com/cristianvasquez/hypermedia-agents/blob/master/tutorial.md"
  click MD "https://github.com/cristianvasquez/hypermedia-agents/blob/master/hypermedia-spec-components.md"
  click MD "https://github.com/cristianvasquez/hypermedia-agents/blob/master/implementing-a-hypermedia-server-with-node.md"
  click HS "https://github.com/cristianvasquez/hypermedia-agents/blob/master/SUMMARY.md"
  click HS "https://github.com/cristianvasquez/hypermedia-agents/blob/master/README.md"
  click SB "https://github.com/cristianvasquez/hypermedia-agents/tree/master/.gitbook/"
  click SA "https://github.com/cristianvasquez/hypermedia-agents/tree/master/.gitbook/assets/"
  click HTML "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/"
  click AModel "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/index.html"
  click AModel "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/js/frame.js"
  click Views "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/dae2005f-688d-4671-ba16-c0c13042da39/views/"
  click Templates "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/dae2005f-688d-4671-ba16-c0c13042da39/elements/model.html"
  click Templates "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/elements/empty-element.html"
  click Logic "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/js/model.js"
  click Logic "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/lib/alasql/"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/css/model.css"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/blob/master/html/css/i18n.css"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/lib/bootstrap/"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/lib/jquery-ui-layout/"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/lib/jquery-ui/"
  click ASets "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/lib/jquery/js/"
  click Hints "https://github.com/cristianvasquez/hypermedia-agents/tree/master/html/hints/"

  classDef build fill:#e6ffe6,stroke:#028A0F,color:#028A0F,stroke-width:2px;
  classDef server fill:#e6f2ff,stroke:#0059b3,color:#0059b3,stroke-width:2px;
  classDef client fill:#fff4e6,stroke:#b35b00,color:#b35b00,stroke-width:2px;
```
