11. Risks and technical debt¶
Last reviewed: 2026-11-03
Known problems, ordered by how much they matter. The ratings are the architecture review's own (2026-11-03): edit them when you know better. Scale: P probability and I impact, each low (L), medium (M) or high (H). The goals Q1 to Q7 are in section 10.
Risk register¶
| ID | Risk | P | I | Goal | Mitigation and status | Source |
|---|---|---|---|---|---|---|
| K1 | Pairing takeover: anyone who knows a paired device's device_uid gets a working token on the next poll, without a code |
M | H | Q1, Q3 | Open decision S1: a new pairing request makes the device pending until the code is entered | open-questions S1 |
| K2 | Unused upload endpoint /api/v1/tracks/upload has no size or rate limit and returns internal errors |
M | M | Q3 | Open decision S4: remove or harden | open-questions S4 |
| K3 | Garmin upload queue full on a long offline trip: 64 KB, then new non-final segments are not stored and the encoder stops for that track | M | H | Q2 | Warning at 75 %; FINAL segments always stored; Wear OS has 16 MiB. Backup recording on Wear OS is an open question (A4) |
track-sync, open-questions A4 |
| K4 | A file that always gets 400 or 413 blocks the upload queue for good | L | M | Q2 | Open decision W11: delete it or move it aside | open-questions W11 |
| K5 | One VM per role (app, worker, database), no failover: a VM or database outage stops the site; a database image change leaves the app about a minute without a database | M | H | Q2 | Realtime jobs fall back to the app VM; nightly encrypted backups; accepted for the beta | DEPLOYMENT, ADR 011 |
| K6 | Track files bucket keeps no versions: a wrong delete or overwrite loses a track file | L | H | Q2 | The nightly track-file backup is the only second copy; kept 30 days | DEPLOYMENT § Backups |
| K7 | Backups depend on one age private key: losing it makes every backup unreadable |
L | H | Q2 | Key in the password manager plus offline, as DEPLOYMENT.md says; restore test script exists (owner runs it) | DEPLOYMENT § Backups |
| K8 | Open-Meteo free plan is not enough at launch: no wind per track, no tides | H | M | Q4 | Buy the paid plan before launch (plan step 7.4) | beta_server_next_steps 7.4 |
| K9 | Engine detection is wrong on other boats (about 70 % against 85 % on the tuned boat) | H | M | Q4 | It is a suggestion the skipper corrects; count corrections to learn the real accuracy | ADR 009 |
| K10 | Deploys and the docs build depend on GitHub Actions. Billing was blocked once after a deploy (2026-10-30, reported by the owner); hand-run deploys are blocked on purpose | M | M | Q3 | Owner keeps the billing in order | AGENTS.md §4 |
| K11 | No uptime monitor or alerting is documented; errors reach Sentry, an outage reaches the owner when someone notices | M | M | Q2 | Add an external uptime check on /up of both hosts |
section 8 |
| K12 | No Content-Security-Policy header is configured (the initializer is the commented Rails default) | L | M | Q3 | Add a policy; the map scripts load from unpkg, which the policy must allow or the scripts move to our own host | content_security_policy.rb |
| K13 | One owner: the system depends on one person's knowledge and accounts | M | H | Q5 | Specs, ADRs, AGENTS.md and this architecture hold the knowledge; credentials are named in one place | credentials |
| K14 | Spec and code drift, and watch parity gaps: the specs stop being the source of truth | M | M | Q5 | mise doccheck gate and drift, parity.md, the Stop hook |
parity, AGENTS.md §0 |
| K15 | Wear OS device_uid changes on reinstall, so the server counts the same watch twice |
H | L | Q4 | Open decision A5: accept | open-questions A5 |
Technical debt¶
| What | Where it is tracked |
|---|---|
| Open product and security decisions (S, W, G, A, D, R rows) | open-questions |
| Deviations between spec and code | Known deviations in each spec file |
| Differences between the watch platforms without a platform reason | parity |
| Work planned but not built | plans |
| The architecture sections that still lack a depth: no response-time target for Q6; no database schema diagram | section 10, data-model |