# kush-singh-26/kosh architecture

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

- Interactive diagram: https://gitdiagram.com/kush-singh-26/kosh
- Repository: https://github.com/kush-singh-26/kosh

## Overview

Kosh is a Go static-site generator. Its principal workflow is to scan Markdown and site metadata, process assets, parse and render content, run site-wide generators, and atomically publish output; `kosh serve --dev` adds watching and incremental rebuilds. The map also includes persistent metadata/search/SSR caching, search-index generation and WASM querying, and the documented asset, PWA, and social features. Edges follow README build descriptions and the shown engine, worker, search-manager, and server excerpts; unsampled subsystems are represented at their existing directory paths.

Main entry points: [`builder/orchestration/engine.go`](https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/engine.go) (Build engine), [`builder/services/content/service.go`](https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/service.go) (Content service), [`builder/orchestration/incremental/manager.go`](https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/incremental/manager.go) (Incremental manager), [`builder/services/content/worker.go`](https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/worker.go) (Content worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build orchestration"]
  node_engine["Build engine<br/>[engine.go]"]
  node_scanner["Metadata scanner"]
  node_incremental["Incremental manager<br/>[manager.go]"]
  node_filesystem["Build filesystem"]
end

subgraph group_content["Content and rendering"]
  node_content_service["Content service<br/>[service.go]"]
  node_content_worker["Content worker<br/>[worker.go]"]
  node_parser["Markdown parser<br/>[parser.go]"]
  node_render_service["Render service<br/>[render_service.go]"]
  node_renderer["Page renderer<br/>[renderer.go]"]
end

subgraph group_assets["Assets and generators"]
  node_asset_service["Asset service<br/>[service.go]"]
  node_asset_pipeline["Asset processing<br/>[assets.go]"]
  node_generators["Site generators"]
  node_social["Social cards<br/>[social.go]"]
  node_hashing["Asset fingerprinting<br/>[hash.go]"]
end

subgraph group_state["Cache and search"]
  node_cache_service["Cache service<br/>[cache_service.go]"]
  node_cache_store[("Metadata and SSR cache<br/>[store.go]")]
  node_search_manager["Search index manager<br/>[manager.go]"]
  node_search_generator["Search index builder<br/>[search.go]"]
  node_search_engine["Search engine<br/>[engine.go]"]
  node_wasm_search["WASM search API<br/>[main.go]"]
end

subgraph group_dev["Development serving"]
  node_server["Dev server<br/>[server.go]"]
  node_watcher["File watcher<br/>[watch.go]"]
end

node_author(("Site author"))
node_cli["Kosh CLI"]
node_browser(("Site visitor"))

node_author -->|"provides site"| node_cli
node_cli -->|"starts build"| node_engine
node_engine -->|"scans metadata"| node_scanner
node_engine -->|"builds assets"| node_asset_service
node_asset_service -->|"processes assets"| node_asset_pipeline
node_engine -->|"processes content"| node_content_service
node_content_service -->|"dispatches work"| node_content_worker
node_content_worker -->|"parses Markdown"| node_parser
node_content_service -->|"renders content"| node_render_service
node_render_service -->|"renders pages"| node_renderer
node_engine -->|"runs generators"| node_generators
node_engine -->|"publishes output"| node_filesystem
node_content_service -->|"generates cards"| node_social
node_engine -->|"uses cache"| node_cache_service
node_cache_service -->|"reads and writes"| node_cache_store
node_asset_pipeline -->|"fingerprints assets"| node_hashing
node_engine -->|"manages indexing"| node_search_manager
node_search_manager -->|"generates index"| node_search_generator
node_content_worker -->|"uses cached records"| node_cache_service
node_wasm_search -->|"runs queries"| node_search_engine
node_browser -.->|"submits queries"| node_wasm_search
node_browser -.->|"requests pages"| node_server
node_server -->|"builds and serves"| node_engine
node_server -->|"starts watching"| node_watcher
node_watcher -->|"triggers rebuilds"| node_incremental
node_incremental -->|"rebuilds posts"| node_content_service
node_incremental -->|"refreshes search"| node_search_manager

click node_cli "https://github.com/kush-singh-26/kosh/tree/main/cmd/kosh"
click node_engine "https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/engine.go"
click node_scanner "https://github.com/kush-singh-26/kosh/tree/main/builder/services/scanner"
click node_incremental "https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/incremental/manager.go"
click node_asset_service "https://github.com/kush-singh-26/kosh/blob/main/builder/services/asset/service.go"
click node_asset_pipeline "https://github.com/kush-singh-26/kosh/blob/main/builder/fs/assets.go"
click node_content_service "https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/service.go"
click node_content_worker "https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/worker.go"
click node_parser "https://github.com/kush-singh-26/kosh/blob/main/builder/parser/parser.go"
click node_render_service "https://github.com/kush-singh-26/kosh/blob/main/builder/services/render/render_service.go"
click node_renderer "https://github.com/kush-singh-26/kosh/blob/main/builder/renderer/renderer.go"
click node_generators "https://github.com/kush-singh-26/kosh/tree/main/builder/generators"
click node_social "https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/social.go"
click node_filesystem "https://github.com/kush-singh-26/kosh/tree/main/builder/fs"
click node_cache_service "https://github.com/kush-singh-26/kosh/blob/main/builder/services/cache/cache_service.go"
click node_cache_store "https://github.com/kush-singh-26/kosh/blob/main/builder/cache/store/store.go"
click node_hashing "https://github.com/kush-singh-26/kosh/blob/main/builder/hashing/hash.go"
click node_search_manager "https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/search/manager.go"
click node_search_generator "https://github.com/kush-singh-26/kosh/blob/main/builder/generators/search.go"
click node_search_engine "https://github.com/kush-singh-26/kosh/blob/main/builder/search/engine.go"
click node_wasm_search "https://github.com/kush-singh-26/kosh/blob/main/cmd/search/main.go"
click node_server "https://github.com/kush-singh-26/kosh/blob/main/internal/server/server.go"
click node_watcher "https://github.com/kush-singh-26/kosh/blob/main/internal/watch/watch.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_engine,node_scanner,node_incremental,node_filesystem toneBlue
class node_content_service,node_content_worker,node_parser,node_render_service,node_renderer toneAmber
class node_asset_service,node_asset_pipeline,node_generators,node_social,node_hashing toneMint
class node_cache_service,node_cache_store,node_search_manager,node_search_generator,node_search_engine,node_wasm_search toneRose
class node_server,node_watcher,node_author,node_browser toneIndigo
class node_cli toneTeal
```

## Components

### Build orchestration

- [Build engine](https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/engine.go): `builder/orchestration/engine.go`
- [Metadata scanner](https://github.com/kush-singh-26/kosh/tree/main/builder/services/scanner): `builder/services/scanner`
- [Incremental manager](https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/incremental/manager.go): `builder/orchestration/incremental/manager.go`
- [Build filesystem](https://github.com/kush-singh-26/kosh/tree/main/builder/fs): `builder/fs`

### Content and rendering

- [Content service](https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/service.go): `builder/services/content/service.go`
- [Content worker](https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/worker.go): `builder/services/content/worker.go`
- [Markdown parser](https://github.com/kush-singh-26/kosh/blob/main/builder/parser/parser.go): `builder/parser/parser.go`
- [Render service](https://github.com/kush-singh-26/kosh/blob/main/builder/services/render/render_service.go): `builder/services/render/render_service.go`
- [Page renderer](https://github.com/kush-singh-26/kosh/blob/main/builder/renderer/renderer.go): `builder/renderer/renderer.go`

### Assets and generators

- [Asset service](https://github.com/kush-singh-26/kosh/blob/main/builder/services/asset/service.go): `builder/services/asset/service.go`
- [Asset processing](https://github.com/kush-singh-26/kosh/blob/main/builder/fs/assets.go): `builder/fs/assets.go`
- [Site generators](https://github.com/kush-singh-26/kosh/tree/main/builder/generators): `builder/generators`
- [Social cards](https://github.com/kush-singh-26/kosh/blob/main/builder/services/content/social.go): `builder/services/content/social.go`
- [Asset fingerprinting](https://github.com/kush-singh-26/kosh/blob/main/builder/hashing/hash.go): `builder/hashing/hash.go`

### Cache and search

- [Cache service](https://github.com/kush-singh-26/kosh/blob/main/builder/services/cache/cache_service.go): `builder/services/cache/cache_service.go`
- [Metadata and SSR cache](https://github.com/kush-singh-26/kosh/blob/main/builder/cache/store/store.go): `builder/cache/store/store.go`
- [Search index manager](https://github.com/kush-singh-26/kosh/blob/main/builder/orchestration/search/manager.go): `builder/orchestration/search/manager.go`
- [Search index builder](https://github.com/kush-singh-26/kosh/blob/main/builder/generators/search.go): `builder/generators/search.go`
- [Search engine](https://github.com/kush-singh-26/kosh/blob/main/builder/search/engine.go): `builder/search/engine.go`
- [WASM search API](https://github.com/kush-singh-26/kosh/blob/main/cmd/search/main.go): `cmd/search/main.go`

### Development serving

- [Dev server](https://github.com/kush-singh-26/kosh/blob/main/internal/server/server.go): `internal/server/server.go`
- [File watcher](https://github.com/kush-singh-26/kosh/blob/main/internal/watch/watch.go): `internal/watch/watch.go`

### Other components

- **Site author**
- [Kosh CLI](https://github.com/kush-singh-26/kosh/tree/main/cmd/kosh): `cmd/kosh`
- **Site visitor**

## Connections

- Site author → Kosh CLI: provides site (evidence: `README.md`)
- Kosh CLI → Build engine: starts build (evidence: `README.md`)
- Build engine → Metadata scanner: scans metadata (evidence: `builder/orchestration/engine.go`)
- Build engine → Asset service: builds assets (evidence: `builder/orchestration/engine.go`)
- Asset service → Asset processing: processes assets (evidence: `builder/services/asset/service.go`)
- Build engine → Content service: processes content (evidence: `README.md`)
- Content service → Content worker: dispatches work (evidence: `builder/services/content/service.go`)
- Content worker → Markdown parser: parses Markdown (evidence: `builder/services/content/worker.go`)
- Content service → Render service: renders content (evidence: `builder/services/content/service.go`)
- Render service → Page renderer: renders pages (evidence: `builder/services/render/render_service.go`)
- Build engine → Site generators: runs generators (evidence: `README.md`)
- Build engine → Build filesystem: publishes output (evidence: `README.md`)
- Content service → Social cards: generates cards (evidence: `builder/services/content/service.go`)
- Build engine → Cache service: uses cache (evidence: `builder/orchestration/engine.go`)
- Cache service → Metadata and SSR cache: reads and writes (evidence: `builder/services/cache/cache_service.go`)
- Asset processing → Asset fingerprinting: fingerprints assets (evidence: `README.md`)
- Build engine → Search index manager: manages indexing (evidence: `builder/orchestration/engine.go`)
- Search index manager → Search index builder: generates index (evidence: `builder/orchestration/search/manager.go`)
- Content worker → Cache service: uses cached records (evidence: `builder/services/content/worker.go`)
- WASM search API → Search engine: runs queries (evidence: `cmd/search/main.go`)
- Site visitor → WASM search API: submits queries (evidence: `README.md`)
- Site visitor → Dev server: requests pages (evidence: `README.md`)
- Dev server → Build engine: builds and serves (evidence: `internal/server/server.go`)
- Dev server → File watcher: starts watching (evidence: `internal/server/server.go`)
- File watcher → Incremental manager: triggers rebuilds (evidence: `internal/watch/watch.go`)
- Incremental manager → Content service: rebuilds posts (evidence: `builder/orchestration/incremental/manager.go`)
- Incremental manager → Search index manager: refreshes search (evidence: `builder/orchestration/incremental/manager.go`)
