# sparkuru/firefly architecture

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

- Interactive diagram: https://gitdiagram.com/sparkuru/firefly
- Repository: https://github.com/sparkuru/firefly

## Overview

Firefly is a Markdown-backed static publication with two reading presentations: a Terminal-style interface and a semantic layout. Its main workflow takes authored posts and pages through site content handling and shared document processing into a presentation readers can browse. The repository also includes an optional comments service and independent experiments. Several site and integration modules are listed but unsampled, so uncertain runtime connections are omitted or marked unverified.

Main entry points: [`presentations/terminal/src/runtime.ts`](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/runtime.ts) (Terminal runtime), [`packages/x-core/src/pipeline.ts`](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/pipeline.ts) (Document pipeline), [`apps/site`](https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/apps/site) (Astro publication), [`presentations/terminal/src/shell/runner.ts`](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/shell/runner.ts) (Shell execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_publication["Publication and Content"]
  node_markdown["Markdown content"]
  node_content["Content access<br/>[content.ts]"]
  node_themes["Content themes<br/>[content-theme.mjs]"]
  node_site["Astro publication"]
end

subgraph group_core["Document Core"]
  node_pipeline["Document pipeline<br/>[pipeline.ts]"]
  node_contracts["Document contracts<br/>[contracts.ts]"]
  node_registry["Adapter registry<br/>[registry.ts]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.ts]"]
end

subgraph group_presentations["Reading Presentations"]
  node_terminal["Terminal runtime<br/>[runtime.ts]"]
  node_shell["Shell execution<br/>[runner.ts]"]
  node_parser["Shell parser<br/>[parser.ts]"]
  node_vfs["Virtual filesystem<br/>[public-index.ts]"]
  node_commands["Terminal commands<br/>[registry.ts]"]
  node_semantic["Semantic presentation<br/>[index.ts]"]
end

subgraph group_comments["Comments"]
  node_commentsplugin["Comments plugin<br/>[public.mjs]"]
  node_commentssite["Site comments adapter<br/>[site.mjs]"]
  node_commentsservice["Comments service<br/>[service.ts]"]
  node_http["Comments HTTP server<br/>[server.ts]"]
  node_repository[("Comment repository")]
end

subgraph group_experiments["Experiments"]
  node_majo["Majo experiment<br/>[majo-player.ts]"]
  node_nerv["Nerv experiment"]
end

node_author(("Content author"))
node_reader(("Publication reader"))

node_author -->|"authors"| node_markdown
node_markdown -.->|"provides content"| node_content
node_content -.->|"feeds publication"| node_site
node_themes -->|"styles articles"| node_site
node_site -->|"publishes pages"| node_reader
node_site -.->|"processes documents"| node_pipeline
node_pipeline -->|"resolves adapter"| node_registry
node_pipeline -->|"normalizes input"| node_contracts
node_pipeline -->|"raises errors"| node_diagnostics
node_semantic -->|"uses core contracts"| node_contracts
node_terminal -->|"parses input"| node_parser
node_terminal -->|"resolves commands"| node_shell
node_shell -->|"parses shell input"| node_parser
node_shell -->|"dispatches commands"| node_commands
node_terminal -->|"reads public index"| node_vfs
node_terminal -->|"presents terminal"| node_reader
node_reader -->|"chooses semantic layout"| node_semantic
node_commentsplugin -.->|"site integration"| node_commentssite
node_commentssite -.->|"connects service"| node_http
node_http -.->|"serves requests"| node_commentsservice
node_commentsservice -.->|"persists comments"| node_repository
node_reader -.->|"optional commenting"| node_commentsplugin
node_reader -.->|"opens experiment"| node_majo
node_reader -.->|"opens experiment"| node_nerv

click node_markdown "https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/content"
click node_content "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/lib/content.ts"
click node_themes "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/lib/content-theme.mjs"
click node_site "https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/apps/site"
click node_pipeline "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/pipeline.ts"
click node_contracts "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/contracts.ts"
click node_registry "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/registry.ts"
click node_diagnostics "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/diagnostics.ts"
click node_terminal "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/runtime.ts"
click node_shell "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/shell/runner.ts"
click node_parser "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/shell/parser.ts"
click node_vfs "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/vfs/public-index.ts"
click node_commands "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/commands/registry.ts"
click node_semantic "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/semantic/src/index.ts"
click node_commentsplugin "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/plugins/comments/public.mjs"
click node_commentssite "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/plugins/comments/site.mjs"
click node_commentsservice "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/service.ts"
click node_http "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/server.ts"
click node_repository "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/sqlite-repository.ts"
click node_majo "https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/experiments/majo/src/scripts/majo-player.ts"
click node_nerv "https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/experiments/nerv"

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_markdown,node_content,node_themes,node_site toneBlue
class node_pipeline,node_contracts,node_registry,node_diagnostics toneAmber
class node_terminal,node_shell,node_parser,node_vfs,node_commands,node_semantic toneMint
class node_commentsplugin,node_commentssite,node_commentsservice,node_http,node_repository toneRose
class node_majo,node_nerv,node_author,node_reader toneIndigo
```

## Components

### Publication and Content

- [Markdown content](https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/content): `content`
- [Content access](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/lib/content.ts): `apps/site/src/lib/content.ts`
- [Content themes](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/lib/content-theme.mjs): `apps/site/src/lib/content-theme.mjs`
- [Astro publication](https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/apps/site): `apps/site`

### Document Core

- [Document pipeline](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/pipeline.ts): `packages/x-core/src/pipeline.ts`
- [Document contracts](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/contracts.ts): `packages/x-core/src/contracts.ts`
- [Adapter registry](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/registry.ts): `packages/x-core/src/registry.ts`
- [Diagnostics](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/packages/x-core/src/diagnostics.ts): `packages/x-core/src/diagnostics.ts`

### Reading Presentations

- [Terminal runtime](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/runtime.ts): `presentations/terminal/src/runtime.ts`
- [Shell execution](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/shell/runner.ts): `presentations/terminal/src/shell/runner.ts`
- [Shell parser](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/shell/parser.ts): `presentations/terminal/src/shell/parser.ts`
- [Virtual filesystem](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/vfs/public-index.ts): `presentations/terminal/src/vfs/public-index.ts`
- [Terminal commands](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/terminal/src/commands/registry.ts): `presentations/terminal/src/commands/registry.ts`
- [Semantic presentation](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/presentations/semantic/src/index.ts): `presentations/semantic/src/index.ts`

### Comments

- [Comments plugin](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/plugins/comments/public.mjs): `plugins/comments/public.mjs`
- [Site comments adapter](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/apps/site/src/plugins/comments/site.mjs): `apps/site/src/plugins/comments/site.mjs`
- [Comments service](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/service.ts): `services/comments/src/service.ts`
- [Comments HTTP server](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/server.ts): `services/comments/src/server.ts`
- [Comment repository](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/services/comments/src/sqlite-repository.ts): `services/comments/src/sqlite-repository.ts`

### Experiments

- [Majo experiment](https://github.com/sparkuru/firefly/blob/anti-entropy-loss-syndrome/experiments/majo/src/scripts/majo-player.ts): `experiments/majo/src/scripts/majo-player.ts`
- [Nerv experiment](https://github.com/sparkuru/firefly/tree/anti-entropy-loss-syndrome/experiments/nerv): `experiments/nerv`

### Other components

- **Content author**
- **Publication reader**

## Connections

- Content author → Markdown content: authors
- Markdown content → Content access: provides content
- Content access → Astro publication: feeds publication
- Content themes → Astro publication: styles articles
- Astro publication → Publication reader: publishes pages
- Astro publication → Document pipeline: processes documents
- Document pipeline → Adapter registry: resolves adapter (evidence: `packages/x-core/src/pipeline.ts`)
- Document pipeline → Document contracts: normalizes input (evidence: `packages/x-core/src/pipeline.ts`)
- Document pipeline → Diagnostics: raises errors (evidence: `packages/x-core/src/pipeline.ts`)
- Semantic presentation → Document contracts: uses core contracts (evidence: `presentations/semantic/src/index.ts`)
- Terminal runtime → Shell parser: parses input (evidence: `presentations/terminal/src/runtime.ts`)
- Terminal runtime → Shell execution: resolves commands (evidence: `presentations/terminal/src/runtime.ts`)
- Shell execution → Shell parser: parses shell input (evidence: `presentations/terminal/src/shell/runner.ts`)
- Shell execution → Terminal commands: dispatches commands (evidence: `presentations/terminal/src/shell/runner.ts`)
- Terminal runtime → Virtual filesystem: reads public index (evidence: `presentations/terminal/src/runtime.ts`)
- Terminal runtime → Publication reader: presents terminal
- Publication reader → Semantic presentation: chooses semantic layout
- Comments plugin → Site comments adapter: site integration
- Site comments adapter → Comments HTTP server: connects service
- Comments HTTP server → Comments service: serves requests
- Comments service → Comment repository: persists comments
- Publication reader → Comments plugin: optional commenting
- Publication reader → Majo experiment: opens experiment
- Publication reader → Nerv experiment: opens experiment
