ISSUE-025 — Production observability and health checks

[shivaram19]

• Functional surgeon view: The team is alerted if the API, DB, or PWA static assets become unhealthy.
• Acceptance criteria:
  1. /api/health returns DB connectivity and disk status.
  2. scripts/deploy.sh health-checks fail loudly.
  3. Structured logging added to critical paths.
• Dependencies: ISSUE-022 recommended.

---

5. Dependency Graph

flowchart TD
    subgraph v0.6
        M1[M1 sync shipped] --> I005[ISSUE-005 offline validation]
        I005 --> I001[ISSUE-001 spaced selector]
        I004[ISSUE-004 source metadata] --> I003[ISSUE-003 500 nursing questions]
        I001 --> I002[ISSUE-002 weak-area links]
        I001 --> I006[ISSUE-006 cache busting]
    end

    subgraph v0.7
        I003 --> I010[ISSUE-010 100+ math/topic]
        I007[ISSUE-007 bulk generate] --> I010
        I004 --> I011[ISSUE-011 verification workflow]
        I008[ISSUE-008 persona templates]
        I009[ISSUE-009 ratings CSV]
    end

    subgraph v0.8
        I001 --> I013[ISSUE-013 capability → selector]
        I005 --> I012[ISSUE-012 math PWA]
        I013 --> I012
        I012 --> I014[ISSUE-014 interleaving]
        I002 --> I015[ISSUE-015 concept adapter]
        I012 --> I016[ISSUE-016 progress dashboard]
    end

    subgraph v0.9
        ADR024[ADR-024 Accepted] --> I017[ISSUE-017 Telegram scaffold]
        I017 --> I018[ISSUE-018 nudge experiment]
        I017 --> I019[ISSUE-019 channel choice]
        I017 --> I020[ISSUE-020 send logs]
        I018 --> I021[ISSUE-021 WhatsApp port]
    end

    subgraph v0.10
        ADR025[ADR-025 Accepted] --> I022[ISSUE-022 SOLID refactor]
        I022 --> I023[ISSUE-023 cleanup]
        I012 --> I024[ISSUE-024 Flutter decision]
        I022 --> I025[ISSUE-025 observability]
    end

Loading

---

6. Live Blockers

Blocker	Why it blocks	Unblocks
ADR-024 Proposed	No Telegram/WhatsApp sender code can be merged without accepted channel/consent architecture.	ISSUE-017, ISSUE-018, ISSUE-019, ISSUE-020, ISSUE-021
ADR-025 Proposed	SOLID refactor cannot delete src/ or move boundaries without accepted strategy.	ISSUE-022, ISSUE-023, ISSUE-025
M1 not manually validated	The spaced selector and math PWA depend on a proven offline-first pattern.	ISSUE-001, ISSUE-012
Nursing bank <500 questions	Adaptive/spaced selection needs enough candidates to be credible.	ISSUE-001, ISSUE-018 (meaningful experiment)
Flutter scope unresolved	Native app work is deferred until PWA retention proves value.	ISSUE-024

---

7. Next Sprint Proposal — v0.6 Sprint 1

Goal: Close the nursing PWA e2e loop so it survives offline and resurfaces weak-area questions.

Order	Issue	Owner	Demo Check
1	ISSUE-005	QA / mobile	Airplane-mode quiz → 24h reconnect → exact 5 rows in DB
2	ISSUE-001	backend + PWA	Daily quiz prefers previously-missed cardiovascular question
3	ISSUE-002	PWA	Result screen links to a concept explanation card
4	ISSUE-006	infra	New app.js deploy auto-invalidates old service-worker cache
Stretch	ISSUE-004	content	Backfill source_url/source_section/verified_at for existing bank

Sprint blocker: If ISSUE-005 fails, do not start ISSUE-001.