Repository navigation
Expand file tree
/
Copy pathviews.c4
More file actions
188 lines (162 loc) · 6.87 KB
/
Copy pathviews.c4
File metadata and controls
188 lines (162 loc) · 6.87 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
// Cuts through the model in model.c4, one per level of the C4 standard:
// https://standards.openhomefoundation.org/architecture/c4-documentation/
//
// C1 and C2 are the required pair. C3 is here because the decisions worth
// knowing about (no datastore, two polling loops, the quota split) live inside
// the single container, and C2 alone would hide them. C4 is covered by dynamic
// views of the three code paths worth following: a request, and each loop.
views {
// Deployed and reachable, but not part of the API. Dimmed everywhere rather
// than hidden, so nobody has to rediscover it.
style element.tag = #scaffolding {
color muted
opacity 30%
}
view index {
title 'C1 — System context'
description '''
Who uses the API and what it depends on. The point of the service is the
fan-in: four project websites want the same livestream status, and only
this service talks to YouTube, so the quota is spent once rather than per
site or per visitor.
'''
include
visitor,
websites,
edge,
webapi,
youtube,
luma,
platform
autoLayout TopBottom
}
view containers of webapi {
title 'C2 — Containers'
description '''
What actually runs: one process, listening on port 3000, with no
datastore beside it. The two YouTube interfaces are drawn separately
because the boundary between them is the design constraint — the feed is
free and polled on a schedule, the Data API is metered and called only
when something changed or is about to.
Nothing reaches the task directly: Cloudflare proxies to a shared load
balancer, which is also the layer that owns request rate limiting.
'''
include
*,
visitor,
websites,
edge,
youtube,
youtube.*,
luma,
platform
autoLayout TopBottom
}
view components of webapi.api {
title 'C3 — Components of the Web API service'
description '''
Inside the process. Two things are worth reading off this view: every
request passes through Bootstrap first, which is where the security
headers and the CORS decision happen; and the HTTP path never reaches
YouTube or Luma — it reads state the polling loops maintain, so a slow or
failing upstream cannot slow down a response.
'''
include
*,
websites,
edge,
youtube,
youtube.*,
luma,
platform
autoLayout TopBottom
}
dynamic view request {
variant sequence
title 'C4 — Serving GET /livestream/:slug'
description '''
The read path once the request is in the process — Cloudflare and the load
balancer sit ahead of the first step; see the C2 view. From here on there is
no I/O at all: the answer is already derived, which is why an unreachable
YouTube shows up as stale state rather than a failed request.
'''
websites -> webapi.api.bootstrap 'GET /livestream/home-assistant'
webapi.api.bootstrap -> webapi.api.bootstrap 'applies helmet headers, matches Origin against CORS_ORIGINS'
webapi.api.bootstrap -> webapi.api.livestreamController 'routes to the handler'
webapi.api.livestreamController -> webapi.api.livestreamService 'getStatus(slug)'
alt {
when 'slug is a configured channel' {
webapi.api.livestreamService -> webapi.api.state 'reads the derived status'
webapi.api.livestreamController <- webapi.api.livestreamService 'channel, status, title, url, startTime, updatedAt'
websites <- webapi.api.bootstrap '200 with the channel status'
}
else 'unknown slug' {
webapi.api.livestreamController <- webapi.api.livestreamService 'NotFoundException'
websites <- webapi.api.bootstrap '404'
}
}
}
dynamic view discovery {
variant sequence
title 'C4 — Discovery sweep, every 5 minutes'
description '''
The only way a newly scheduled or published stream enters the model. Runs
at startup too, so the API is not blank until the first timer fires. In
the steady state it costs nothing: the feed is free, and an unchanged
fingerprint skips the metered call entirely.
'''
webapi.api.livestreamService -> webapi.api.state 'looks up the cached channel ID'
opt 'channel ID not resolved yet' {
webapi.api.livestreamService -> youtube.dataApi 'channels.list?forHandle=…'
webapi.api.livestreamService <- youtube.dataApi 'UC… channel ID'
webapi.api.livestreamService -> webapi.api.state 'caches the ID both ways'
}
webapi.api.livestreamService -> youtube.feeds 'GET videos.xml?channel_id=…'
webapi.api.livestreamService <- youtube.feeds 'channel title and its recent entries'
webapi.api.livestreamService -> webapi.api.state 'stores the display name, so a rebrand needs no deploy'
opt 'feed fingerprint differs from the last sweep' {
webapi.api.livestreamService -> youtube.dataApi 'videos.list(snippet, liveStreamingDetails) for the listed IDs'
webapi.api.livestreamService <- youtube.dataApi 'live / upcoming / ended, per video'
webapi.api.livestreamService -> webapi.api.state 'tracks them, and untracks what videos.list no longer serves'
}
webapi.api.livestreamService -> webapi.api.state 'recomputes the channel; updatedAt moves only if what we serve changed'
}
dynamic view reconcile {
variant sequence
title 'C4 — Reconcile tick, every 10 seconds'
description '''
What actually catches a stream going live or ending, at a cadence
discovery could not afford. It stays affordable by querying only the
streams that are live or start within 15 minutes — so the cost follows how
much is happening, not how many channels are configured.
'''
webapi.api.livestreamService -> webapi.api.state 'drops streams that ended more than 24 hours ago'
webapi.api.livestreamService -> webapi.api.state 'selects streams that are live or start within 15 minutes'
alt {
when 'at least one is active' {
webapi.api.livestreamService -> youtube.dataApi 'videos.list for those IDs only'
webapi.api.livestreamService <- youtube.dataApi 'current live streaming details'
webapi.api.livestreamService -> webapi.api.state 'applies the transitions and recomputes the channel'
}
else 'nothing active' {
webapi.api.livestreamService -> webapi.api.livestreamService 'returns without a request — an idle tick spends no quota'
}
}
}
view delivery {
title 'Delivery — from a published release to a running version'
description '''
Included because the deployed version is not something this repository
sets directly: the release workflow hands the image tag to Terraform
Cloud, which owns the deployment as state.
'''
include
engineer,
github,
ghcr,
terraform,
platform,
webapi
autoLayout LeftRight
}
}