# ponder2000/embedded-guide architecture

> Architecture diagram of the GitHub repository ponder2000/embedded-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ponder2000/embedded-guide
- Repository: https://github.com/ponder2000/embedded-guide

## Overview

This is a Go-generated, static educational website: learners follow a registered sequence of embedded-systems lessons, with browser-side reading aids and interactive simulations. The generation path combines chapter content, HTML templates, embedded assets, and optional SEO metadata into deployable files; a separate preview server serves those files without rendering templates. The graph includes documented browser capabilities even where their implementation was not sampled. Edges are limited to relationships visible in excerpts or stated in the README.

Main entry points: [`internal/site/site.go`](https://github.com/ponder2000/embedded-guide/blob/main/internal/site/site.go) (Site generator), [`web/static/js/app.js`](https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/app.js) (Settings and progress), [`internal/render/template.go`](https://github.com/ponder2000/embedded-guide/blob/main/internal/render/template.go) (Template renderer), [`internal/content/chapters.go`](https://github.com/ponder2000/embedded-guide/blob/main/internal/content/chapters.go) (Chapter registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Static generation"]
  node_site_generator["Site generator<br/>[site.go]"]
  node_template_renderer["Template renderer<br/>[template.go]"]
  node_embedded_assets["Embedded assets<br/>[assets.go]"]
  node_seo_metadata["SEO metadata<br/>[seo.go]"]
  node_output_writer["Output writer<br/>[output.go]"]
end

subgraph group_learning["Learning content"]
  node_chapter_registry["Chapter registry<br/>[chapters.go]"]
  node_chapter_reviews["Chapter reviews<br/>[checkpoints.go]"]
  node_lesson_templates["Lesson templates"]
  node_shared_templates["Shared page templates"]
  node_static_pages["Generated static pages"]
end

subgraph group_browser["Browser experience"]
  node_browser_app["Settings and progress<br/>[app.js]"]
  node_browser_storage[("IndexedDB state")]
  node_tab_sync["Tab synchronization"]
  node_simulations["Interactive simulations<br/>[simulations.js]"]
  node_web_audio["Synthesized sound<br/>[app.js]"]
  node_visitor_counter["Visits counter"]
end

subgraph group_preview["Local preview"]
  node_preview_server["Preview server<br/>[preview.go]"]
  node_server_command["Server command<br/>[main.go]"]
end

node_learner(("Learner"))
node_static_host(("Static host"))

node_site_generator -->|"reads chapters"| node_chapter_registry
node_site_generator -->|"renders pages"| node_template_renderer
node_site_generator -->|"loads assets"| node_embedded_assets
node_site_generator -->|"builds metadata"| node_seo_metadata
node_site_generator -.->|"writes files"| node_output_writer
node_template_renderer -->|"parses templates"| node_shared_templates
node_chapter_registry -->|"registers lessons"| node_lesson_templates
node_site_generator -->|"generates pages"| node_static_pages
node_learner -.->|"opens lessons"| node_static_host
node_static_host -.->|"serves pages"| node_static_pages
node_static_pages -.->|"enables features"| node_browser_app
node_static_pages -.->|"hosts simulations"| node_simulations
node_browser_app -->|"reads and writes"| node_browser_storage
node_browser_app -.->|"syncs tabs"| node_tab_sync
node_browser_app -->|"synthesizes tones"| node_web_audio
node_simulations -->|"dispatches feedback"| node_browser_app
node_chapter_reviews -.->|"provides reviews"| node_lesson_templates
node_static_pages -.->|"loads badge"| node_visitor_counter
node_server_command -->|"starts preview"| node_preview_server
node_preview_server -->|"serves generated files"| node_static_pages

click node_site_generator "https://github.com/ponder2000/embedded-guide/blob/main/internal/site/site.go"
click node_template_renderer "https://github.com/ponder2000/embedded-guide/blob/main/internal/render/template.go"
click node_embedded_assets "https://github.com/ponder2000/embedded-guide/blob/main/assets.go"
click node_seo_metadata "https://github.com/ponder2000/embedded-guide/blob/main/internal/site/seo.go"
click node_output_writer "https://github.com/ponder2000/embedded-guide/blob/main/internal/site/output.go"
click node_chapter_registry "https://github.com/ponder2000/embedded-guide/blob/main/internal/content/chapters.go"
click node_chapter_reviews "https://github.com/ponder2000/embedded-guide/blob/main/internal/content/checkpoints.go"
click node_lesson_templates "https://github.com/ponder2000/embedded-guide/tree/main/web/templates/chapters"
click node_shared_templates "https://github.com/ponder2000/embedded-guide/tree/main/web/templates"
click node_browser_app "https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/app.js"
click node_simulations "https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/simulations.js"
click node_web_audio "https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/app.js"
click node_preview_server "https://github.com/ponder2000/embedded-guide/blob/main/internal/preview/preview.go"
click node_server_command "https://github.com/ponder2000/embedded-guide/blob/main/cmd/server/main.go"

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_site_generator,node_template_renderer,node_embedded_assets,node_seo_metadata,node_output_writer toneBlue
class node_chapter_registry,node_chapter_reviews,node_lesson_templates,node_shared_templates,node_static_pages toneAmber
class node_browser_app,node_browser_storage,node_tab_sync,node_simulations,node_web_audio,node_visitor_counter toneMint
class node_preview_server,node_server_command toneRose
class node_learner,node_static_host toneIndigo
```

## Components

### Static generation

- [Site generator](https://github.com/ponder2000/embedded-guide/blob/main/internal/site/site.go): `internal/site/site.go`
- [Template renderer](https://github.com/ponder2000/embedded-guide/blob/main/internal/render/template.go): `internal/render/template.go`
- [Embedded assets](https://github.com/ponder2000/embedded-guide/blob/main/assets.go): `assets.go`
- [SEO metadata](https://github.com/ponder2000/embedded-guide/blob/main/internal/site/seo.go): `internal/site/seo.go`
- [Output writer](https://github.com/ponder2000/embedded-guide/blob/main/internal/site/output.go): `internal/site/output.go`

### Learning content

- [Chapter registry](https://github.com/ponder2000/embedded-guide/blob/main/internal/content/chapters.go): `internal/content/chapters.go`
- [Chapter reviews](https://github.com/ponder2000/embedded-guide/blob/main/internal/content/checkpoints.go): `internal/content/checkpoints.go`
- [Lesson templates](https://github.com/ponder2000/embedded-guide/tree/main/web/templates/chapters): `web/templates/chapters`
- [Shared page templates](https://github.com/ponder2000/embedded-guide/tree/main/web/templates): `web/templates`
- **Generated static pages**

### Browser experience

- [Settings and progress](https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/app.js): `web/static/js/app.js`
- **IndexedDB state**
- **Tab synchronization**
- [Interactive simulations](https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/simulations.js): `web/static/js/simulations.js`
- [Synthesized sound](https://github.com/ponder2000/embedded-guide/blob/main/web/static/js/app.js): `web/static/js/app.js`
- **Visits counter**

### Local preview

- [Preview server](https://github.com/ponder2000/embedded-guide/blob/main/internal/preview/preview.go): `internal/preview/preview.go`
- [Server command](https://github.com/ponder2000/embedded-guide/blob/main/cmd/server/main.go): `cmd/server/main.go`

### Other components

- **Learner**
- **Static host**

## Connections

- Site generator → Chapter registry: reads chapters (evidence: `internal/site/site.go`)
- Site generator → Template renderer: renders pages (evidence: `internal/site/site.go`)
- Site generator → Embedded assets: loads assets (evidence: `internal/site/site.go`)
- Site generator → SEO metadata: builds metadata (evidence: `internal/site/site.go`)
- Site generator → Output writer: writes files
- Template renderer → Shared page templates: parses templates (evidence: `internal/render/template.go`)
- Chapter registry → Lesson templates: registers lessons (evidence: `internal/content/chapters.go`)
- Site generator → Generated static pages: generates pages (evidence: `internal/site/site.go`)
- Learner → Static host: opens lessons
- Static host → Generated static pages: serves pages
- Generated static pages → Settings and progress: enables features
- Generated static pages → Interactive simulations: hosts simulations
- Settings and progress → IndexedDB state: reads and writes (evidence: `web/static/js/app.js`)
- Settings and progress → Tab synchronization: syncs tabs (evidence: `README.md`)
- Settings and progress → Synthesized sound: synthesizes tones (evidence: `web/static/js/app.js`)
- Interactive simulations → Settings and progress: dispatches feedback (evidence: `web/static/js/simulations.js`)
- Chapter reviews → Lesson templates: provides reviews (evidence: `README.md`)
- Generated static pages → Visits counter: loads badge (evidence: `README.md`)
- Server command → Preview server: starts preview (evidence: `cmd/server/main.go`)
- Preview server → Generated static pages: serves generated files (evidence: `internal/preview/preview.go`)