Skip to content

Commit 0d09fbf

Browse files
sumitakesumitake
committed
docs: improve diagram readability
1 parent ff7f462 commit 0d09fbf

3 files changed

Lines changed: 67 additions & 73 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,16 @@ The intended outcome is an appliance-like encoder that can be deployed on a Rasp
2929
## Architecture
3030

3131
```mermaid
32-
flowchart LR
32+
flowchart TB
3333
subgraph ArchitectureInputs["Source and compatibility inputs"]
34+
direction LR
3435
Camera["RTSP camera"]
3536
ObsScene["Optional OBS scene"]
3637
ObsService["Optional OBS service profile"]
3738
end
3839
3940
subgraph ArchitectureHost["Encoder host"]
41+
direction TB
4042
Systemd["systemd service"]
4143
Supervisor["youtube-autoencoder supervisor"]
4244
Probe["FFprobe source validation"]
@@ -47,6 +49,7 @@ flowchart LR
4749
end
4850
4951
subgraph ArchitectureYouTube["YouTube"]
52+
direction LR
5053
Ingest["Reusable liveStream ingest"]
5154
Api["YouTube Data API v3"]
5255
Broadcast["One marked liveBroadcast and watch page"]
@@ -134,41 +137,34 @@ Every recovery path first preserves ownership and retry state. Media must be fre
134137
```mermaid
135138
stateDiagram-v2
136139
state "Startup or restart" as RecoveryStartup
137-
state "Retry deadline pending" as RecoveryWait
138-
state "Probe camera source" as RecoveryProbe
139-
state "Start and supervise FFmpeg" as RecoveryEncoder
140-
state "Wait for active ingest" as RecoveryIngest
141-
state "Reconcile marked broadcast" as RecoveryReconcile
142-
state "Resume same event" as RecoveryResume
143-
state "Create unlisted generation" as RecoveryCreate
144-
state "Testing, live, and health gates" as RecoveryGates
145-
state "Verified public stream" as RecoveryStable
146-
state "Persist source cooldown" as RecoverySourceBackoff
147-
state "Persist API, quota, or ambiguity cooldown" as RecoveryControlBackoff
148-
state "Prior event terminal or missing" as RecoveryTerminal
140+
state "Managed stream generation" as RecoveryGeneration {
141+
state "Probe source and start FFmpeg" as RecoveryMedia
142+
state "Require fresh active ingest" as RecoveryIngest
143+
state "Reconcile exact ownership markers" as RecoveryReconcile
144+
state "Create and bind unlisted generation" as RecoveryCreate
145+
state "Resume one nonterminal event" as RecoveryManaged
146+
state "Testing, live, and publication gates" as RecoveryGates
147+
state "Verified public stream" as RecoveryStable
148+
state "Public stream with API cooldown" as RecoveryPublicFallback
149+
150+
[*] --> RecoveryMedia
151+
RecoveryMedia --> RecoveryIngest : media progress fresh
152+
RecoveryIngest --> RecoveryReconcile : YouTube ingest active
153+
RecoveryReconcile --> RecoveryManaged : one marked nonterminal event
154+
RecoveryReconcile --> RecoveryCreate : none, terminal, or missing
155+
RecoveryCreate --> RecoveryManaged : insert and bind verified
156+
RecoveryManaged --> RecoveryGates
157+
RecoveryGates --> RecoveryStable : two healthy live observations and privacy readback
158+
RecoveryStable --> RecoveryPublicFallback : API unavailable, media healthy
159+
RecoveryPublicFallback --> RecoveryStable : API recovers
160+
}
161+
state "Persist classified cooldown" as RecoveryBackoff
149162
150163
[*] --> RecoveryStartup
151-
RecoveryStartup --> RecoveryWait : deadline still active
152-
RecoveryWait --> RecoveryStartup : deadline expires or host restarts
153-
RecoveryStartup --> RecoveryProbe : no active deadline
154-
RecoveryProbe --> RecoverySourceBackoff : source unavailable
155-
RecoverySourceBackoff --> RecoveryWait
156-
RecoveryProbe --> RecoveryEncoder : source available
157-
RecoveryEncoder --> RecoveryIngest
158-
RecoveryIngest --> RecoverySourceBackoff : media stops or ingest stays inactive
159-
RecoveryIngest --> RecoveryReconcile : media fresh and ingest active
160-
RecoveryReconcile --> RecoveryResume : one marked nonterminal event
161-
RecoveryReconcile --> RecoveryCreate : no recoverable event
162-
RecoveryReconcile --> RecoveryControlBackoff : API, quota, or ambiguous state
163-
RecoveryCreate --> RecoveryResume : insert and bind verified
164-
RecoveryResume --> RecoveryGates
165-
RecoveryGates --> RecoveryStable : two healthy live observations and privacy readback
166-
RecoveryResume --> RecoverySourceBackoff : camera or FFmpeg interruption
167-
RecoveryGates --> RecoveryControlBackoff : control-plane failure before public verification
168-
RecoveryControlBackoff --> RecoveryWait
169-
RecoveryStable --> RecoveryResume : media path recovers with the same watch URL
170-
RecoveryResume --> RecoveryTerminal : YouTube confirms terminal or missing
171-
RecoveryTerminal --> RecoveryCreate : next generation only
164+
RecoveryStartup --> RecoveryBackoff : retry deadline active
165+
RecoveryBackoff --> RecoveryStartup : deadline expires or host restarts
166+
RecoveryStartup --> RecoveryGeneration : no active deadline
167+
RecoveryGeneration --> RecoveryBackoff : recoverable failure, preserve ownership
172168
```
173169

174170
| Failure | Expected behavior |

‎docs/superpowers/plans/2026-07-10-readme-architecture-diagrams.md‎

Lines changed: 34 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
**Interfaces:**
3030

3131
- Consumes: Component names and ownership boundaries documented in `README.md` and `docs/superpowers/specs/2026-07-10-idempotent-youtube-lifecycle-design.md`.
32-
- Produces: One `flowchart LR` Mermaid block under `## Architecture`; later validation relies on its `ArchitectureInputs`, `ArchitectureHost`, and `ArchitectureYouTube` subgraph IDs.
32+
- Produces: One `flowchart TB` Mermaid block under `## Architecture`; later validation relies on its `ArchitectureInputs`, `ArchitectureHost`, and `ArchitectureYouTube` subgraph IDs.
3333

3434
- [ ] **Step 1: Verify the three-diagram contract currently fails**
3535

@@ -46,14 +46,16 @@ Expected: nonzero exit because the current README contains no Mermaid blocks.
4646
Keep the existing introductory and ownership paragraphs. Replace only the fenced `text` diagram with:
4747

4848
```mermaid
49-
flowchart LR
49+
flowchart TB
5050
subgraph ArchitectureInputs["Source and compatibility inputs"]
51+
direction LR
5152
Camera["RTSP camera"]
5253
ObsScene["Optional OBS scene"]
5354
ObsService["Optional OBS service profile"]
5455
end
5556
5657
subgraph ArchitectureHost["Encoder host"]
58+
direction TB
5759
Systemd["systemd service"]
5860
Supervisor["youtube-autoencoder supervisor"]
5961
Probe["FFprobe source validation"]
@@ -64,6 +66,7 @@ flowchart LR
6466
end
6567
6668
subgraph ArchitectureYouTube["YouTube"]
69+
direction LR
6770
Ingest["Reusable liveStream ingest"]
6871
Api["YouTube Data API v3"]
6972
Broadcast["One marked liveBroadcast and watch page"]
@@ -143,41 +146,34 @@ Every recovery path first preserves ownership and retry state. Media must be fre
143146
```mermaid
144147
stateDiagram-v2
145148
state "Startup or restart" as RecoveryStartup
146-
state "Retry deadline pending" as RecoveryWait
147-
state "Probe camera source" as RecoveryProbe
148-
state "Start and supervise FFmpeg" as RecoveryEncoder
149-
state "Wait for active ingest" as RecoveryIngest
150-
state "Reconcile marked broadcast" as RecoveryReconcile
151-
state "Resume same event" as RecoveryResume
152-
state "Create unlisted generation" as RecoveryCreate
153-
state "Testing, live, and health gates" as RecoveryGates
154-
state "Verified public stream" as RecoveryStable
155-
state "Persist source cooldown" as RecoverySourceBackoff
156-
state "Persist API, quota, or ambiguity cooldown" as RecoveryControlBackoff
157-
state "Prior event terminal or missing" as RecoveryTerminal
149+
state "Managed stream generation" as RecoveryGeneration {
150+
state "Probe source and start FFmpeg" as RecoveryMedia
151+
state "Require fresh active ingest" as RecoveryIngest
152+
state "Reconcile exact ownership markers" as RecoveryReconcile
153+
state "Create and bind unlisted generation" as RecoveryCreate
154+
state "Resume one nonterminal event" as RecoveryManaged
155+
state "Testing, live, and publication gates" as RecoveryGates
156+
state "Verified public stream" as RecoveryStable
157+
state "Public stream with API cooldown" as RecoveryPublicFallback
158+
159+
[*] --> RecoveryMedia
160+
RecoveryMedia --> RecoveryIngest : media progress fresh
161+
RecoveryIngest --> RecoveryReconcile : YouTube ingest active
162+
RecoveryReconcile --> RecoveryManaged : one marked nonterminal event
163+
RecoveryReconcile --> RecoveryCreate : none, terminal, or missing
164+
RecoveryCreate --> RecoveryManaged : insert and bind verified
165+
RecoveryManaged --> RecoveryGates
166+
RecoveryGates --> RecoveryStable : two healthy live observations and privacy readback
167+
RecoveryStable --> RecoveryPublicFallback : API unavailable, media healthy
168+
RecoveryPublicFallback --> RecoveryStable : API recovers
169+
}
170+
state "Persist classified cooldown" as RecoveryBackoff
158171
159172
[*] --> RecoveryStartup
160-
RecoveryStartup --> RecoveryWait : deadline still active
161-
RecoveryWait --> RecoveryStartup : deadline expires or host restarts
162-
RecoveryStartup --> RecoveryProbe : no active deadline
163-
RecoveryProbe --> RecoverySourceBackoff : source unavailable
164-
RecoverySourceBackoff --> RecoveryWait
165-
RecoveryProbe --> RecoveryEncoder : source available
166-
RecoveryEncoder --> RecoveryIngest
167-
RecoveryIngest --> RecoverySourceBackoff : media stops or ingest stays inactive
168-
RecoveryIngest --> RecoveryReconcile : media fresh and ingest active
169-
RecoveryReconcile --> RecoveryResume : one marked nonterminal event
170-
RecoveryReconcile --> RecoveryCreate : no recoverable event
171-
RecoveryReconcile --> RecoveryControlBackoff : API, quota, or ambiguous state
172-
RecoveryCreate --> RecoveryResume : insert and bind verified
173-
RecoveryResume --> RecoveryGates
174-
RecoveryGates --> RecoveryStable : two healthy live observations and privacy readback
175-
RecoveryResume --> RecoverySourceBackoff : camera or FFmpeg interruption
176-
RecoveryGates --> RecoveryControlBackoff : control-plane failure before public verification
177-
RecoveryControlBackoff --> RecoveryWait
178-
RecoveryStable --> RecoveryResume : media path recovers with the same watch URL
179-
RecoveryResume --> RecoveryTerminal : YouTube confirms terminal or missing
180-
RecoveryTerminal --> RecoveryCreate : next generation only
173+
RecoveryStartup --> RecoveryBackoff : retry deadline active
174+
RecoveryBackoff --> RecoveryStartup : deadline expires or host restarts
175+
RecoveryStartup --> RecoveryGeneration : no active deadline
176+
RecoveryGeneration --> RecoveryBackoff : recoverable failure, preserve ownership
181177
```
182178
````
183179

@@ -188,7 +184,7 @@ Run:
188184
```bash
189185
test "$(rg -c '^```mermaid$' README.md)" -eq 2
190186
test "$(rg -c '^stateDiagram-v2$' README.md)" -eq 1
191-
rg -n 'RecoverySourceBackoff|RecoveryControlBackoff|same watch URL|next generation only' README.md
187+
rg -n 'RecoveryBackoff|RecoveryPublicFallback|preserve ownership|none, terminal, or missing' README.md
192188
! rg -n '^### (Production Lifecycle Diagram|Normal Lifecycle Diagram)$' README.md
193189
git diff --check
194190
```
@@ -277,7 +273,7 @@ Run:
277273

278274
```bash
279275
test "$(rg -c '^```mermaid$' README.md)" -eq 3
280-
test "$(rg -c '^flowchart LR$' README.md)" -eq 1
276+
test "$(rg -c '^flowchart TB$' README.md)" -eq 1
281277
test "$(rg -c '^flowchart TD$' README.md)" -eq 1
282278
test "$(rg -c '^stateDiagram-v2$' README.md)" -eq 1
283279
rg -n 'DeploymentStreamDecision|DeploymentValidationDecision|remote-management recovery' README.md
@@ -312,7 +308,7 @@ Run:
312308

313309
```bash
314310
test "$(rg -c '^```mermaid$' README.md)" -eq 3
315-
test "$(rg -c '^flowchart LR$' README.md)" -eq 1
311+
test "$(rg -c '^flowchart TB$' README.md)" -eq 1
316312
test "$(rg -c '^flowchart TD$' README.md)" -eq 1
317313
test "$(rg -c '^stateDiagram-v2$' README.md)" -eq 1
318314
! git diff origin/main...HEAD -- README.md | rg -i 'rtsp://[^<]|stream[_ -]?key\s*=|refresh[_ -]?token\s*='

‎docs/superpowers/specs/2026-07-10-readme-architecture-diagrams-design.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The README remains an executive and operational entry point. Detailed algorithms
3535

3636
Placement: replace the existing text diagram at the start of `## Architecture`.
3737

38-
Format: Mermaid `flowchart LR` with three visually distinct logical regions:
38+
Format: Mermaid `flowchart TB` with three visually distinct logical regions:
3939

4040
1. Sources and compatibility inputs: RTSP camera, optional OBS scene, and optional OBS service profile.
4141
2. Encoder host: systemd, supervisor, FFprobe, FFmpeg, API helper, durable state and locks, and OAuth files.
@@ -69,6 +69,8 @@ Format: Mermaid `stateDiagram-v2` focused on recovery decisions:
6969

7070
The state machine may name the testing/live/public gates only where necessary to show recovery destinations. It will not become the omitted normal-production lifecycle diagram.
7171

72+
For README readability, healthy progression is grouped inside one managed-generation composite state. Classified failures share one transition into the durable cooldown state; the existing failure table remains authoritative for the per-failure behavior.
73+
7274
### 3. Provisioning And Deployment Flow
7375

7476
Placement: at the start of `## Installation`, before command-level installation instructions.

0 commit comments

Comments
 (0)