Skip to content

Commit 377679b

Browse files
cubapCopilot
cubap
and
Copilot
authored
Add transcription architecture and diagrams (#501)
* Add transcription architecture and diagrams closes #98 Add ARCHITECTURE.md and DIAGRAMS.md for the simple-transcription component. These docs describe component composition, visual regions, data ownership and truth locations, minimal knowledge boundaries, and core event contracts. DIAGRAMS.md provides mermaid diagrams for composition, data ownership, and event flow to aid integration with TPEN (interfaces/transcription/index.html, components/simple-transcription/index.js, components/projects/project-header.js). * Clarify image ownership and transcription roles Documentation updates to reflect that tpen-simple-transcription uses raw <img> elements (#imgTop, #imgBottom) for image display and manages them via adjustImages()/highlightActiveLine()/resetImagePositions(), rather than using tpen-line-image or tpen-image-fragment. Updated ARCHITECTURE.md to clarify workspace composition, state ownership, and the responsibilities of tpen-transcription-block (line input rendering, primary mutator of TPEN.activeLineIndex via moveToLine(), and emission of navigation events). DIAGRAMS.md was updated to match these changes (diagram nodes for #imgTop/#imgBottom and adjusted event arrows for transcription-block and header). * Update components/simple-transcription/DIAGRAMS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent fee6306 commit 377679b

File tree

2 files changed

+186
-0
lines changed

2 files changed

+186
-0
lines changed

‎components/simple-transcription/ARCHITECTURE.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Transcription Interface Architecture
2+
3+
This document explains the current TPEN transcription interface structure, ownership boundaries, and data/event flow.
4+
5+
## Scope
6+
7+
This describes the interface loaded from:
8+
9+
- interfaces/transcription/index.html
10+
- components/simple-transcription/index.js
11+
- components/projects/project-header.js
12+
13+
## Component Inventory
14+
15+
Top-level composition:
16+
17+
1. tpen-simple-transcription
18+
2. tpen-project-header
19+
3. tpen-transcription-block
20+
4. tpen-workspace-tools
21+
22+
**Note**: `tpen-line-image` and `tpen-image-fragment` are used by `tpen-transcription-interface` (`interfaces/transcription/index.js`), not by `tpen-simple-transcription`. This component handles image display inline via raw `<img>` elements and the `adjustImages()` method.
23+
24+
Header composition:
25+
26+
1. project title display
27+
2. canvas selector (select)
28+
3. tpen-layer-selector
29+
4. tpen-column-selector
30+
5. line indicator
31+
6. navigation controls (home, manage project, profile)
32+
33+
Workspace composition:
34+
35+
1. focused line image viewport (`#imgTop` — raw `<img>` with custom zoom/pan via `adjustImages()`)
36+
2. transcription input workspace (`tpen-transcription-block`)
37+
3. workspace tools launcher/controls (`tpen-workspace-tools`)
38+
4. remaining image fragment panel (`#imgBottom` — raw `<img>` showing the rest of the canvas)
39+
40+
## Visual Regions
41+
42+
The interface is intentionally split into 3 regions:
43+
44+
1. Header: navigation and context controls
45+
2. Workspace: line-focused transcription work area
46+
3. Split-screen tools panel: optional right-pane tools
47+
48+
See the diagram reference in DIAGRAMS.md for detailed flow diagrams.
49+
50+
## Data Truth Locations
51+
52+
The table below defines ownership for key state.
53+
54+
| Data | Source of truth | Primary readers | Mutated by |
55+
| --- | --- | --- | --- |
56+
| Active project graph (layers/pages/columns) | TPEN.activeProject | header, selectors, interface shell | project load/update flows |
57+
| Current page selection | URL query pageID and TPEN.screen.pageInQuery | header, interface, selectors | header canvas selector, page navigation |
58+
| Active line index | TPEN.activeLineIndex | header line indicator, interface, tools | tpen-transcription-block (`moveToLine()`), column selector |
59+
| Interface UI mode (split-screen/tool selection) | tpen-simple-transcription local state | interface shell and tool pane | splitscreen events and UI interactions |
60+
| Annotation page items for column ordering | component-local cached page object | column selector, transcription logic | vault fetch + ordering utility |
61+
62+
## Minimal Knowledge Boundaries
63+
64+
### Page Shell
65+
66+
- Knows which top-level interface element to mount.
67+
- Does not own transcription state.
68+
69+
### Interface Shell (tpen-simple-transcription)
70+
71+
- Owns orchestration state: active page data, active line, split-screen status.
72+
- Coordinates events among header, workspace, and tools.
73+
- Does not implement selector internals or tool internals.
74+
75+
### Header (tpen-project-header)
76+
77+
- Owns navigation controls and contextual display (project title, line indicator).
78+
- Emits navigation changes through URL/event interactions.
79+
- Does not render transcription content.
80+
81+
### Selectors (layer, column, page/canvas)
82+
83+
- Convert user input into selection events.
84+
- Do not manage rendering of line content.
85+
86+
### Workspace Components
87+
88+
- tpen-transcription-block handles line transcription interactions.
89+
- Image display (`#imgTop`, `#imgBottom`) is handled directly by tpen-simple-transcription via `adjustImages()`, `highlightActiveLine()`, and `resetImagePositions()`.
90+
- tpen-workspace-tools handles tool launch and workspace actions.
91+
- These components should not own global routing.
92+
93+
### Transcription Block (tpen-transcription-block)
94+
95+
- Owns line input rendering and text editing.
96+
- Primary mutator of `TPEN.activeLineIndex` via `moveToLine()`.
97+
- Emits line navigation events (`tpen-transcription-previous-line`, `tpen-transcription-next-line`) via `TPEN.eventDispatcher`.
98+
- Does not manage image positioning or split-screen state.
99+
100+
## Event Contracts (Core)
101+
102+
Common orchestration events in the current implementation:
103+
104+
- tpen-layer-changed
105+
- tpen-column-selected
106+
- tpen-transcription-previous-line
107+
- tpen-transcription-next-line
108+
- tpen-active-line-updated
109+
- tools-dismiss
110+
- splitscreen-toggle
111+
112+
## Notes
113+
114+
- Current header implementation includes layer and column selectors plus a canvas selector.
115+
- The standalone tpen-page-selector exists as a reusable component but is not the primary selector in this specific header implementation.

‎components/simple-transcription/DIAGRAMS.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Transcription Interface Diagrams
2+
3+
This file contains diagram-first references for external linking.
4+
5+
## Composition Diagram
6+
7+
```mermaid
8+
flowchart TD
9+
A[interfaces/transcription/index.html] --> B[tpen-simple-transcription]
10+
11+
B --> C[tpen-project-header]
12+
B --> D[Workspace Left Pane]
13+
B --> E[Split-screen Right Pane]
14+
15+
C --> C1[tpen-layer-selector]
16+
C --> C2[tpen-column-selector]
17+
C --> C3[Canvas selector]
18+
C --> C4[Line indicator]
19+
20+
D --> D1["#imgTop (focused line image)"]
21+
D --> D2[tpen-transcription-block]
22+
D --> D3[tpen-workspace-tools]
23+
D --> D4["#imgBottom (remaining canvas)"]
24+
```
25+
26+
## Data Ownership Diagram
27+
28+
```mermaid
29+
flowchart LR
30+
P[TPEN.activeProject] --> H[tpen-project-header]
31+
P --> L[tpen-layer-selector]
32+
P --> C[tpen-column-selector]
33+
P --> S[tpen-simple-transcription]
34+
35+
U[URL pageID and TPEN.screen.pageInQuery] --> H
36+
U --> S
37+
U --> C
38+
39+
A[TPEN.activeLineIndex] --> H
40+
A --> S
41+
42+
SSTATE[Interface local state: split-screen and active tool] --> S
43+
44+
V[vault annotation/page cache] --> C
45+
V --> S
46+
```
47+
48+
## Event Flow Diagram
49+
50+
```mermaid
51+
flowchart TD
52+
L[tpen-layer-selector] -- tpen-layer-changed --> S[tpen-simple-transcription]
53+
C[tpen-column-selector] -- tpen-column-selected --> S
54+
W[tpen-workspace-tools] -- splitscreen-toggle --> S
55+
W -- tools-dismiss --> S
56+
57+
T[tpen-transcription-block] -- tpen-transcription-next-line / previous-line --> S
58+
T -- tpen-transcription-next-line / previous-line --> H[tpen-project-header]
59+
60+
H -- URL pageID updates --> U[Browser URL]
61+
```
62+
63+
## External Link Target
64+
65+
Recommended issue link target:
66+
67+
- components/simple-transcription/ARCHITECTURE.md
68+
69+
Secondary diagram-only link:
70+
71+
- components/simple-transcription/DIAGRAMS.md

0 commit comments

Comments
 (0)