# aemgh/spatialmarkdown architecture

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

- Interactive diagram: https://gitdiagram.com/aemgh/spatialmarkdown
- Repository: https://github.com/aemgh/spatialmarkdown

## Overview

Spatial Markdown is a DOM-less streaming text layout engine. A user supplies markup directly or through an LLM stream adapter; the app or pipeline incrementally tokenizes and builds an AST, transforms it, measures content, solves constraints, calculates geometry, and emits renderer-independent draw commands. Those commands feed Canvas or the Android QuickJS/Compose runtime; static rendering and theme extraction are additional capabilities. The pipeline excerpt documents its orchestration, while the README documents public workflows and cross-platform behavior; some adapter and Android internals were not sampled.

Main entry points: [`src/pipeline.ts`](https://github.com/aemgh/spatialmarkdown/blob/main/src/pipeline.ts) (Layout pipeline), [`src/app/create-app.ts`](https://github.com/aemgh/spatialmarkdown/blob/main/src/app/create-app.ts) (App coordinator), [`src/app/mount.ts`](https://github.com/aemgh/spatialmarkdown/blob/main/src/app/mount.ts) (Mount API), [`android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngine.kt`](https://github.com/aemgh/spatialmarkdown/blob/main/android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngine.kt) (Android runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application APIs"]
  node_mount["Mount API<br/>[mount.ts]"]
  node_app["App coordinator<br/>[create-app.ts]"]
  node_pipeline["Layout pipeline<br/>[pipeline.ts]"]
end

subgraph group_parse["Parsing and Layout"]
  node_tokenizer["FSM tokenizer<br/>[state-machine.ts]"]
  node_ast["AST builder<br/>[builder.ts]"]
  node_transforms["AST transforms<br/>[auto-paragraph.ts]"]
  node_measurement["Text measurement"]
  node_solver["Constraint solver<br/>[solver.ts]"]
  node_geometry["Geometry calculator<br/>[calculator.ts]"]
end

subgraph group_render["Rendering Runtimes"]
  node_commands["Command builder<br/>[command-builder.ts]"]
  node_canvas["Canvas renderer<br/>[canvas-renderer.ts]"]
  node_android["Android runtime<br/>[SpatialEngine.kt]"]
  node_androidview["Compose view"]
  node_ssr["Server rendering<br/>[index.ts]"]
end

subgraph group_integrations["Streams and Themes"]
  node_streams["LLM stream adapters<br/>[from-openai.ts]"]
  node_theme["Theme extraction<br/>[extract-theme.ts]"]
end

node_user(("Markup author"))
node_llm(("LLM provider"))

node_user -->|"provides markup"| node_mount
node_mount -->|"creates app"| node_app
node_app -->|"coordinates"| node_pipeline
node_llm -->|"streams response"| node_streams
node_streams -->|"feeds stream"| node_app
node_user -->|"feeds markup"| node_pipeline
node_pipeline -->|"tokenizes"| node_tokenizer
node_pipeline -->|"builds AST"| node_ast
node_pipeline -->|"transforms AST"| node_transforms
node_pipeline -->|"measures text"| node_measurement
node_pipeline -->|"solves constraints"| node_solver
node_pipeline -->|"calculates geometry"| node_geometry
node_pipeline -->|"builds commands"| node_commands
node_pipeline -->|"renders commands"| node_canvas
node_pipeline -->|"runs in QuickJS"| node_android
node_android -->|"supplies runtime"| node_androidview
node_user -->|"requests static render"| node_ssr
node_user -->|"extracts theme"| node_theme

click node_mount "https://github.com/aemgh/spatialmarkdown/blob/main/src/app/mount.ts"
click node_app "https://github.com/aemgh/spatialmarkdown/blob/main/src/app/create-app.ts"
click node_pipeline "https://github.com/aemgh/spatialmarkdown/blob/main/src/pipeline.ts"
click node_tokenizer "https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/tokenizer/state-machine.ts"
click node_ast "https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/ast/builder.ts"
click node_transforms "https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/transforms/auto-paragraph.ts"
click node_measurement "https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/measurement/measurement-context.ts"
click node_solver "https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/constraints/solver.ts"
click node_geometry "https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/geometry/calculator.ts"
click node_commands "https://github.com/aemgh/spatialmarkdown/blob/main/src/renderer/command-builder.ts"
click node_canvas "https://github.com/aemgh/spatialmarkdown/blob/main/src/renderer/canvas/canvas-renderer.ts"
click node_android "https://github.com/aemgh/spatialmarkdown/blob/main/android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngine.kt"
click node_androidview "https://github.com/aemgh/spatialmarkdown/blob/main/android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngineView.kt"
click node_streams "https://github.com/aemgh/spatialmarkdown/blob/main/src/streams/from-openai.ts"
click node_theme "https://github.com/aemgh/spatialmarkdown/blob/main/src/theme/extract-theme.ts"
click node_ssr "https://github.com/aemgh/spatialmarkdown/blob/main/src/ssr/index.ts"

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_mount,node_app,node_pipeline toneBlue
class node_tokenizer,node_ast,node_transforms,node_measurement,node_solver,node_geometry toneAmber
class node_commands,node_canvas,node_android,node_androidview,node_ssr toneMint
class node_streams,node_theme toneRose
class node_user,node_llm toneIndigo
```

## Components

### Application APIs

- [Mount API](https://github.com/aemgh/spatialmarkdown/blob/main/src/app/mount.ts): `src/app/mount.ts`
- [App coordinator](https://github.com/aemgh/spatialmarkdown/blob/main/src/app/create-app.ts): `src/app/create-app.ts`
- [Layout pipeline](https://github.com/aemgh/spatialmarkdown/blob/main/src/pipeline.ts): `src/pipeline.ts`

### Parsing and Layout

- [FSM tokenizer](https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/tokenizer/state-machine.ts): `src/parser/tokenizer/state-machine.ts`
- [AST builder](https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/ast/builder.ts): `src/parser/ast/builder.ts`
- [AST transforms](https://github.com/aemgh/spatialmarkdown/blob/main/src/parser/transforms/auto-paragraph.ts): `src/parser/transforms/auto-paragraph.ts`
- [Text measurement](https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/measurement/measurement-context.ts): `src/engine/measurement/measurement-context.ts`
- [Constraint solver](https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/constraints/solver.ts): `src/engine/constraints/solver.ts`
- [Geometry calculator](https://github.com/aemgh/spatialmarkdown/blob/main/src/engine/geometry/calculator.ts): `src/engine/geometry/calculator.ts`

### Rendering Runtimes

- [Command builder](https://github.com/aemgh/spatialmarkdown/blob/main/src/renderer/command-builder.ts): `src/renderer/command-builder.ts`
- [Canvas renderer](https://github.com/aemgh/spatialmarkdown/blob/main/src/renderer/canvas/canvas-renderer.ts): `src/renderer/canvas/canvas-renderer.ts`
- [Android runtime](https://github.com/aemgh/spatialmarkdown/blob/main/android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngine.kt): `android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngine.kt`
- [Compose view](https://github.com/aemgh/spatialmarkdown/blob/main/android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngineView.kt): `android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngineView.kt`
- [Server rendering](https://github.com/aemgh/spatialmarkdown/blob/main/src/ssr/index.ts): `src/ssr/index.ts`

### Streams and Themes

- [LLM stream adapters](https://github.com/aemgh/spatialmarkdown/blob/main/src/streams/from-openai.ts): `src/streams/from-openai.ts`
- [Theme extraction](https://github.com/aemgh/spatialmarkdown/blob/main/src/theme/extract-theme.ts): `src/theme/extract-theme.ts`

### Other components

- **Markup author**
- **LLM provider**

## Connections

- Markup author → Mount API: provides markup
- Mount API → App coordinator: creates app (evidence: `src/app/index.ts`)
- App coordinator → Layout pipeline: coordinates (evidence: `src/app/create-app.ts`)
- LLM provider → LLM stream adapters: streams response
- LLM stream adapters → App coordinator: feeds stream
- Markup author → Layout pipeline: feeds markup
- Layout pipeline → FSM tokenizer: tokenizes (evidence: `src/pipeline.ts`)
- Layout pipeline → AST builder: builds AST (evidence: `src/pipeline.ts`)
- Layout pipeline → AST transforms: transforms AST (evidence: `src/pipeline.ts`)
- Layout pipeline → Text measurement: measures text (evidence: `src/pipeline.ts`)
- Layout pipeline → Constraint solver: solves constraints (evidence: `src/pipeline.ts`)
- Layout pipeline → Geometry calculator: calculates geometry (evidence: `src/pipeline.ts`)
- Layout pipeline → Command builder: builds commands (evidence: `src/pipeline.ts`)
- Layout pipeline → Canvas renderer: renders commands
- Layout pipeline → Android runtime: runs in QuickJS
- Android runtime → Compose view: supplies runtime (evidence: `android/spatial-engine/src/main/java/com/spatialmarkdown/engine/core/SpatialEngineView.kt`)
- Markup author → Server rendering: requests static render
- Markup author → Theme extraction: extracts theme