# elagoht/collage architecture

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

- Interactive diagram: https://gitdiagram.com/elagoht/collage
- Repository: https://github.com/elagoht/collage
- Video tour (about a minute): https://gitdiagram.com/elagoht/collage/video

## Overview

Collage is a Go framework for server-side, component-based rendering, with a companion CLI for creating, developing, building, exporting, and serving sites. In the principal workflow, an application registers pages and fragments; an HTTP request is routed and rendered from templates and data, then returned with cache and dependency-tag behavior. Documents and mounted assets are additional serving paths, while plugins extend application behavior. The source excerpts show the public-to-core handoff and key rendering responsibilities; several internal connections are documented in package comments or the README rather than inspected call sites.

Main entry points: [`internal/httpx/handler.go`](https://github.com/elagoht/collage/blob/main/internal/httpx/handler.go) (HTTP Request Handler), [`internal/cli/cli.go`](https://github.com/elagoht/collage/blob/main/internal/cli/cli.go) (Collage CLI), [`internal/core/app.go`](https://github.com/elagoht/collage/blob/main/internal/core/app.go) (Application Orchestrator), [`pkg/collage/app.go`](https://github.com/elagoht/collage/blob/main/pkg/collage/app.go) (Public Application API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_public_api["Public Application API<br/>[app.go]"]
  node_core_app["Application Orchestrator<br/>[app.go]"]
  node_registration["Pages And Routes<br/>[registry.go]"]
end

subgraph group_serve["Request Serving"]
  node_http_handler["HTTP Request Handler<br/>[handler.go]"]
  node_router["Locale Router<br/>[router.go]"]
  node_actions["HTTP Actions<br/>[action.go]"]
  node_documents["Routed Documents<br/>[document.go]"]
  node_assets["Mounted Assets<br/>[mount.go]"]
end

subgraph group_render["Rendering"]
  node_render_engine["Page Render Engine<br/>[engine.go]"]
  node_fragment_render["Fragment Rendering<br/>[fragment.go]"]
  node_templates["Template Engine<br/>[engine.go]"]
  node_data_handlers["Fragment Data Handlers<br/>[datasource.go]"]
end

subgraph group_state["Caching And Extensions"]
  node_cache[("Render Cache<br/>[cache.go]")]
  node_dependency_tracker["Dependency Tracking<br/>[tracker.go]"]
  node_data_cache[("Data Cache<br/>[store.go]")]
  node_plugins["Plugin Registry And Hooks<br/>[registry.go]"]
  node_csrf["CSRF Protection<br/>[csrf.go]"]
end

subgraph group_tooling["Site Tooling"]
  node_cli["Collage CLI<br/>[cli.go]"]
  node_site_scaffold["Project Scaffolding<br/>[new.go]"]
  node_dev_loop["Development Loop<br/>[dev.go]"]
  node_site_export["Static Export<br/>[export.go]"]
  node_site_build_serve["Build And Static Serve<br/>[build.go]"]
end

node_site_author(("Site Author"))
node_reader(("Site Reader"))

node_site_author -->|"configures app"| node_public_api
node_public_api -->|"constructs"| node_core_app
node_public_api -->|"registers pages"| node_registration
node_core_app -->|"builds handler"| node_http_handler
node_reader -->|"sends request"| node_http_handler
node_http_handler -->|"resolves route"| node_router
node_http_handler -->|"renders page"| node_render_engine
node_http_handler -->|"reads and writes"| node_cache
node_http_handler -->|"tracks tags"| node_dependency_tracker
node_http_handler -->|"runs hooks"| node_plugins
node_http_handler -->|"protects forms"| node_csrf
node_router -.->|"routes documents"| node_documents
node_render_engine -->|"renders fragments"| node_fragment_render
node_fragment_render -->|"executes templates"| node_templates
node_fragment_render -->|"fetches fragment data"| node_data_handlers
node_render_engine -->|"collects dependency tags"| node_dependency_tracker
node_core_app -.->|"configures data cache"| node_data_cache
node_core_app -.->|"configures mounts"| node_assets
node_site_author -->|"runs commands"| node_cli
node_cli -->|"creates project"| node_site_scaffold
node_cli -->|"runs development"| node_dev_loop
node_cli -->|"exports static site"| node_site_export
node_cli -->|"builds or serves"| node_site_build_serve

click node_public_api "https://github.com/elagoht/collage/blob/main/pkg/collage/app.go"
click node_core_app "https://github.com/elagoht/collage/blob/main/internal/core/app.go"
click node_registration "https://github.com/elagoht/collage/blob/main/internal/core/registry.go"
click node_http_handler "https://github.com/elagoht/collage/blob/main/internal/httpx/handler.go"
click node_router "https://github.com/elagoht/collage/blob/main/internal/router/router.go"
click node_actions "https://github.com/elagoht/collage/blob/main/internal/httpx/action.go"
click node_documents "https://github.com/elagoht/collage/blob/main/internal/httpx/document.go"
click node_assets "https://github.com/elagoht/collage/blob/main/internal/asset/mount.go"
click node_render_engine "https://github.com/elagoht/collage/blob/main/internal/render/engine.go"
click node_fragment_render "https://github.com/elagoht/collage/blob/main/internal/render/fragment.go"
click node_templates "https://github.com/elagoht/collage/blob/main/internal/template/engine.go"
click node_data_handlers "https://github.com/elagoht/collage/blob/main/internal/types/datasource.go"
click node_cache "https://github.com/elagoht/collage/blob/main/internal/cache/cache.go"
click node_dependency_tracker "https://github.com/elagoht/collage/blob/main/internal/dependency/tracker.go"
click node_data_cache "https://github.com/elagoht/collage/blob/main/internal/datacache/store.go"
click node_plugins "https://github.com/elagoht/collage/blob/main/internal/plugin/registry.go"
click node_csrf "https://github.com/elagoht/collage/blob/main/internal/csrf/csrf.go"
click node_cli "https://github.com/elagoht/collage/blob/main/internal/cli/cli.go"
click node_site_scaffold "https://github.com/elagoht/collage/blob/main/internal/cli/new.go"
click node_dev_loop "https://github.com/elagoht/collage/blob/main/internal/cli/dev.go"
click node_site_export "https://github.com/elagoht/collage/blob/main/internal/cli/export.go"
click node_site_build_serve "https://github.com/elagoht/collage/blob/main/internal/cli/build.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_public_api,node_core_app,node_registration toneBlue
class node_http_handler,node_router,node_actions,node_documents,node_assets toneAmber
class node_render_engine,node_fragment_render,node_templates,node_data_handlers toneMint
class node_cache,node_dependency_tracker,node_data_cache,node_plugins,node_csrf toneRose
class node_cli,node_site_scaffold,node_dev_loop,node_site_export,node_site_build_serve,node_site_author,node_reader toneIndigo
```

## Components

### Application API

- [Public Application API](https://github.com/elagoht/collage/blob/main/pkg/collage/app.go): `pkg/collage/app.go`
- [Application Orchestrator](https://github.com/elagoht/collage/blob/main/internal/core/app.go): `internal/core/app.go`
- [Pages And Routes](https://github.com/elagoht/collage/blob/main/internal/core/registry.go): `internal/core/registry.go`

### Request Serving

- [HTTP Request Handler](https://github.com/elagoht/collage/blob/main/internal/httpx/handler.go): `internal/httpx/handler.go`
- [Locale Router](https://github.com/elagoht/collage/blob/main/internal/router/router.go): `internal/router/router.go`
- [HTTP Actions](https://github.com/elagoht/collage/blob/main/internal/httpx/action.go): `internal/httpx/action.go`
- [Routed Documents](https://github.com/elagoht/collage/blob/main/internal/httpx/document.go): `internal/httpx/document.go`
- [Mounted Assets](https://github.com/elagoht/collage/blob/main/internal/asset/mount.go): `internal/asset/mount.go`

### Rendering

- [Page Render Engine](https://github.com/elagoht/collage/blob/main/internal/render/engine.go): `internal/render/engine.go`
- [Fragment Rendering](https://github.com/elagoht/collage/blob/main/internal/render/fragment.go): `internal/render/fragment.go`
- [Template Engine](https://github.com/elagoht/collage/blob/main/internal/template/engine.go): `internal/template/engine.go`
- [Fragment Data Handlers](https://github.com/elagoht/collage/blob/main/internal/types/datasource.go): `internal/types/datasource.go`

### Caching And Extensions

- [Render Cache](https://github.com/elagoht/collage/blob/main/internal/cache/cache.go): `internal/cache/cache.go`
- [Dependency Tracking](https://github.com/elagoht/collage/blob/main/internal/dependency/tracker.go): `internal/dependency/tracker.go`
- [Data Cache](https://github.com/elagoht/collage/blob/main/internal/datacache/store.go): `internal/datacache/store.go`
- [Plugin Registry And Hooks](https://github.com/elagoht/collage/blob/main/internal/plugin/registry.go): `internal/plugin/registry.go`
- [CSRF Protection](https://github.com/elagoht/collage/blob/main/internal/csrf/csrf.go): `internal/csrf/csrf.go`

### Site Tooling

- [Collage CLI](https://github.com/elagoht/collage/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Project Scaffolding](https://github.com/elagoht/collage/blob/main/internal/cli/new.go): `internal/cli/new.go`
- [Development Loop](https://github.com/elagoht/collage/blob/main/internal/cli/dev.go): `internal/cli/dev.go`
- [Static Export](https://github.com/elagoht/collage/blob/main/internal/cli/export.go): `internal/cli/export.go`
- [Build And Static Serve](https://github.com/elagoht/collage/blob/main/internal/cli/build.go): `internal/cli/build.go`

### Other components

- **Site Author**
- **Site Reader**

## Connections

- Site Author → Public Application API: configures app (evidence: `README.md`)
- Public Application API → Application Orchestrator: constructs (evidence: `pkg/collage/app.go`)
- Public Application API → Pages And Routes: registers pages (evidence: `pkg/collage/app.go`)
- Application Orchestrator → HTTP Request Handler: builds handler (evidence: `internal/core/app.go`)
- Site Reader → HTTP Request Handler: sends request (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → Locale Router: resolves route (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → Page Render Engine: renders page (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → Render Cache: reads and writes (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → Dependency Tracking: tracks tags (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → Plugin Registry And Hooks: runs hooks (evidence: `internal/httpx/handler.go`)
- HTTP Request Handler → CSRF Protection: protects forms (evidence: `internal/httpx/handler.go`)
- Locale Router → Routed Documents: routes documents (evidence: `internal/router/router.go`)
- Page Render Engine → Fragment Rendering: renders fragments (evidence: `internal/render/engine.go`)
- Fragment Rendering → Template Engine: executes templates (evidence: `internal/render/fragment.go`)
- Fragment Rendering → Fragment Data Handlers: fetches fragment data (evidence: `internal/render/fragment.go`)
- Page Render Engine → Dependency Tracking: collects dependency tags (evidence: `internal/render/engine.go`)
- Application Orchestrator → Data Cache: configures data cache (evidence: `internal/core/app.go`)
- Application Orchestrator → Mounted Assets: configures mounts (evidence: `internal/core/app.go`)
- Site Author → Collage CLI: runs commands (evidence: `README.md`)
- Collage CLI → Project Scaffolding: creates project (evidence: `README.md`)
- Collage CLI → Development Loop: runs development (evidence: `README.md`)
- Collage CLI → Static Export: exports static site (evidence: `README.md`)
- Collage CLI → Build And Static Serve: builds or serves (evidence: `README.md`)