How sparkuru/firefly works
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: runtime.ts Terminal runtime · pipeline.ts Document pipeline · site Astro publication · runner.ts Shell execution
Components 23
Publication and Content
- Markdown content
content - Content access
apps/site/src/lib/content.ts - Content themes
apps/site/src/lib/content-theme.mjs - Astro publication
apps/site
Document Core
- Document pipeline
packages/x-core/src/pipeline.ts - Document contracts
packages/x-core/src/contracts.ts - Adapter registry
packages/x-core/src/registry.ts - Diagnostics
packages/x-core/src/diagnostics.ts
Reading Presentations
- Terminal runtime
presentations/terminal/src/runtime.ts - Shell execution
presentations/terminal/src/shell/runner.ts - Shell parser
presentations/terminal/src/shell/parser.ts - Virtual filesystem
presentations/terminal/src/vfs/public-index.ts - Terminal commands
presentations/terminal/src/commands/registry.ts - Semantic presentation
presentations/semantic/src/index.ts
Comments
- Comments plugin
plugins/comments/public.mjs - Site comments adapter
apps/site/src/plugins/comments/site.mjs - Comments service
services/comments/src/service.ts - Comments HTTP server
services/comments/src/server.ts - Comment repository
services/comments/src/sqlite-repository.ts
Experiments
- Majo experiment
experiments/majo/src/scripts/majo-player.ts - Nerv experiment
experiments/nerv
Other components
- Content author
- Publication reader
Connections 24
- 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
packages/x-core/src/pipeline.ts - Document pipeline → Document contracts: normalizes input
packages/x-core/src/pipeline.ts - Document pipeline → Diagnostics: raises errors
packages/x-core/src/pipeline.ts - Semantic presentation → Document contracts: uses core contracts
presentations/semantic/src/index.ts - Terminal runtime → Shell parser: parses input
presentations/terminal/src/runtime.ts - Terminal runtime → Shell execution: resolves commands
presentations/terminal/src/runtime.ts - Shell execution → Shell parser: parses shell input
presentations/terminal/src/shell/runner.ts - Shell execution → Terminal commands: dispatches commands
presentations/terminal/src/shell/runner.ts - Terminal runtime → Virtual filesystem: reads public index
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