# tilitronic/poetry-platform architecture

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

- Interactive diagram: https://gitdiagram.com/tilitronic/poetry-platform
- Repository: https://github.com/tilitronic/poetry-platform

## Overview

This monorepo appears to support a poetry authoring platform: a browser-based studio, an editor engine, phonetic/stress analysis, and visualizers. The principal workflow is authoring text in the studio and passing document changes through the editor engine; analysis workers are present as a separate capability. Source excerpts establish the editor’s tokenization and state handling, but do not establish how the studio wires the editor, workers, or visualizers together. The API and analytics packages are included as distinct backend capabilities; their broader runtime connections are not shown.

Main entry points: [`packages/editor-engine/src/orchestrator/Orchestrator.ts`](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/orchestrator/Orchestrator.ts) (Editor Orchestrator), [`apps/author-studio/src/components/VisualizerContainer/VisualizerContainer.vue`](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/components/VisualizerContainer/VisualizerContainer.vue) (Visualizer Container), [`apps/author-studio/src/workers/bootstrap.ts`](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/bootstrap.ts) (Worker Bootstrap), [`apps/author-studio/src/App.vue`](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/App.vue) (Studio App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Author Studio"]
  node_studio_app["Studio App<br/>[App.vue]"]
  node_studio_routes["Studio Routes<br/>[routes.ts]"]
  node_studio_page["Authoring Page<br/>[IndexPage.vue]"]
  node_text_editor["Text Editor<br/>[OpusTextEditor.vue]"]
  node_visualizer_container["Visualizer Container"]
  node_worker_bootstrap["Worker Bootstrap<br/>[bootstrap.ts]"]
end

subgraph group_editor["Editor Engine"]
  node_orchestrator["Editor Orchestrator<br/>[Orchestrator.ts]"]
  node_editor_view["Editor View<br/>[OpusEditorView.ts]"]
  node_command_bus["Command Bus<br/>[command-bus.ts]"]
  node_poetry_state["Poetry State<br/>[PoetryState.ts]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.ts]"]
  node_formatting["Formatting Filter"]
end

subgraph group_analysis["Text Analysis"]
  node_stress_worker["Stress Worker<br/>[w1-stress.ts]"]
  node_phonetics_worker["Phonetics Worker<br/>[w2-phonetics.ts]"]
  node_phonetics_core["Phonetics Core<br/>[ipa.ts]"]
  node_atlas_loader["Atlas Loader<br/>[load-atlas.ts]"]
end

subgraph group_visualization["Visualization"]
  node_visualizer_2d["Interactive Visualizer<br/>[index.ts]"]
  node_visualizer_ssr["SSR Visualizer<br/>[index.ts]"]
  node_visualizer_3d["3D Visualizer<br/>[index.ts]"]
end

subgraph group_backend["Backend Services"]
  node_api_auth["API Auth<br/>[auth.py]"]
  node_postgres["Postgres Access<br/>[postgres.py]"]
  node_analytics_daemon["Analytics Scheduler<br/>[cron.py]"]
  node_analytics_uow["Analytics Unit Of Work<br/>[uow.py]"]
  node_analytics_calc["Analytics Calculation<br/>[numpy_calc.py]"]
end

node_author(("Author"))

node_author -->|"uses"| node_studio_app
node_studio_app -->|"renders routes"| node_studio_routes
node_studio_routes -->|"routes to"| node_studio_page
node_orchestrator -->|"updates state"| node_poetry_state
node_orchestrator -->|"creates"| node_command_bus
node_orchestrator -->|"tokenizes changes"| node_tokenizer
node_worker_bootstrap -->|"initializes"| node_stress_worker
node_worker_bootstrap -->|"initializes"| node_phonetics_worker
node_phonetics_worker -.->|"loads atlas"| node_atlas_loader
node_visualizer_container -.->|"may use"| node_visualizer_2d
node_visualizer_container -.->|"may use"| node_visualizer_3d
node_analytics_daemon -->|"schedules"| node_analytics_calc

click node_studio_app "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/App.vue"
click node_studio_routes "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/router/routes.ts"
click node_studio_page "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/pages/IndexPage.vue"
click node_text_editor "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/components/OpusTextEditor/OpusTextEditor.vue"
click node_visualizer_container "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/components/VisualizerContainer/VisualizerContainer.vue"
click node_worker_bootstrap "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/bootstrap.ts"
click node_orchestrator "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/orchestrator/Orchestrator.ts"
click node_editor_view "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/view/OpusEditorView.ts"
click node_command_bus "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/orchestrator/command-bus.ts"
click node_poetry_state "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/state/PoetryState.ts"
click node_tokenizer "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/tokenizer/tokenizer.ts"
click node_formatting "https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/view/opusFormattingFilter.ts"
click node_stress_worker "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/w1-stress.ts"
click node_phonetics_worker "https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/w2-phonetics.ts"
click node_phonetics_core "https://github.com/tilitronic/poetry-platform/blob/main/packages/phonetics-core/src/engine/ipa.ts"
click node_atlas_loader "https://github.com/tilitronic/poetry-platform/blob/main/packages/phonetics-core/src/atlas/load-atlas.ts"
click node_visualizer_2d "https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-2d/src/interactive/index.ts"
click node_visualizer_ssr "https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-2d/src/ssr/index.ts"
click node_visualizer_3d "https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-3d/src/index.ts"
click node_api_auth "https://github.com/tilitronic/poetry-platform/blob/main/apps/api-server/app/core/auth.py"
click node_postgres "https://github.com/tilitronic/poetry-platform/blob/main/apps/api-server/app/db/postgres.py"
click node_analytics_daemon "https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/daemon/cron.py"
click node_analytics_uow "https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/db/uow.py"
click node_analytics_calc "https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/core/numpy_calc.py"

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_studio_app,node_studio_routes,node_studio_page,node_text_editor,node_visualizer_container,node_worker_bootstrap toneBlue
class node_orchestrator,node_editor_view,node_command_bus,node_poetry_state,node_tokenizer,node_formatting toneAmber
class node_stress_worker,node_phonetics_worker,node_phonetics_core,node_atlas_loader toneMint
class node_visualizer_2d,node_visualizer_ssr,node_visualizer_3d toneRose
class node_api_auth,node_postgres,node_analytics_daemon,node_analytics_uow,node_analytics_calc,node_author toneIndigo
```

## Components

### Author Studio

- [Studio App](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/App.vue): `apps/author-studio/src/App.vue`
- [Studio Routes](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/router/routes.ts): `apps/author-studio/src/router/routes.ts`
- [Authoring Page](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/pages/IndexPage.vue): `apps/author-studio/src/pages/IndexPage.vue`
- [Text Editor](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/components/OpusTextEditor/OpusTextEditor.vue): `apps/author-studio/src/components/OpusTextEditor/OpusTextEditor.vue`
- [Visualizer Container](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/components/VisualizerContainer/VisualizerContainer.vue): `apps/author-studio/src/components/VisualizerContainer/VisualizerContainer.vue`
- [Worker Bootstrap](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/bootstrap.ts): `apps/author-studio/src/workers/bootstrap.ts`

### Editor Engine

- [Editor Orchestrator](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/orchestrator/Orchestrator.ts): `packages/editor-engine/src/orchestrator/Orchestrator.ts`
- [Editor View](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/view/OpusEditorView.ts): `packages/editor-engine/src/view/OpusEditorView.ts`
- [Command Bus](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/orchestrator/command-bus.ts): `packages/editor-engine/src/orchestrator/command-bus.ts`
- [Poetry State](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/state/PoetryState.ts): `packages/editor-engine/src/state/PoetryState.ts`
- [Tokenizer](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/tokenizer/tokenizer.ts): `packages/editor-engine/src/tokenizer/tokenizer.ts`
- [Formatting Filter](https://github.com/tilitronic/poetry-platform/blob/main/packages/editor-engine/src/view/opusFormattingFilter.ts): `packages/editor-engine/src/view/opusFormattingFilter.ts`

### Text Analysis

- [Stress Worker](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/w1-stress.ts): `apps/author-studio/src/workers/w1-stress.ts`
- [Phonetics Worker](https://github.com/tilitronic/poetry-platform/blob/main/apps/author-studio/src/workers/w2-phonetics.ts): `apps/author-studio/src/workers/w2-phonetics.ts`
- [Phonetics Core](https://github.com/tilitronic/poetry-platform/blob/main/packages/phonetics-core/src/engine/ipa.ts): `packages/phonetics-core/src/engine/ipa.ts`
- [Atlas Loader](https://github.com/tilitronic/poetry-platform/blob/main/packages/phonetics-core/src/atlas/load-atlas.ts): `packages/phonetics-core/src/atlas/load-atlas.ts`

### Visualization

- [Interactive Visualizer](https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-2d/src/interactive/index.ts): `packages/visualizer-2d/src/interactive/index.ts`
- [SSR Visualizer](https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-2d/src/ssr/index.ts): `packages/visualizer-2d/src/ssr/index.ts`
- [3D Visualizer](https://github.com/tilitronic/poetry-platform/blob/main/packages/visualizer-3d/src/index.ts): `packages/visualizer-3d/src/index.ts`

### Backend Services

- [API Auth](https://github.com/tilitronic/poetry-platform/blob/main/apps/api-server/app/core/auth.py): `apps/api-server/app/core/auth.py`
- [Postgres Access](https://github.com/tilitronic/poetry-platform/blob/main/apps/api-server/app/db/postgres.py): `apps/api-server/app/db/postgres.py`
- [Analytics Scheduler](https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/daemon/cron.py): `packages/analytics-pipeline/src/daemon/cron.py`
- [Analytics Unit Of Work](https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/db/uow.py): `packages/analytics-pipeline/src/db/uow.py`
- [Analytics Calculation](https://github.com/tilitronic/poetry-platform/blob/main/packages/analytics-pipeline/src/core/numpy_calc.py): `packages/analytics-pipeline/src/core/numpy_calc.py`

### Other components

- **Author**

## Connections

- Author → Studio App: uses
- Studio App → Studio Routes: renders routes
- Studio Routes → Authoring Page: routes to
- Editor Orchestrator → Poetry State: updates state
- Editor Orchestrator → Command Bus: creates
- Editor Orchestrator → Tokenizer: tokenizes changes
- Worker Bootstrap → Stress Worker: initializes
- Worker Bootstrap → Phonetics Worker: initializes
- Phonetics Worker → Atlas Loader: loads atlas
- Visualizer Container → Interactive Visualizer: may use
- Visualizer Container → 3D Visualizer: may use
- Analytics Scheduler → Analytics Calculation: schedules