How cristianvasquez/hypermedia-agents works
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