docs+tests: architecture diagrams, E2E integration tests, webhook persistence update

[thedgarg31]

Summary

This PR covers two deliverables assigned to Daksh (Phase 4), plus a README update for the GitHub webhook persistence fix from PR #41.

---

What was added

Task 1 — E2E Integration Tests (three-module flow)

New test file: \ ests/test_e2e_three_module_flow.py\ — 25 tests across 4 classes verifying the complete Goals → Signals → Recommendations pipeline.

TestGitHubWebhookParsing (5 tests)

• Webhook parses \pr_merged, \pr_reviewed, \commit_pushed\ events correctly
• Unknown event types return 200 gracefully (no crash)
• Non-merged PRs are silently ignored

TestGitHubSignalIngestion (4 tests)

• GitHub \pr_merged\ signal is persisted to Supabase \�ctivity_signals\ table
• Stored signal is queryable via \GET /api/v1/signals/\
• Queryable by \source=github_webhook\ filter
• Fetchable by UUID via \GET /api/v1/signals/{id}\

TestThreeModuleFlow (7 tests) — the core E2E flow

• GitHub signal surfaces in \GET /api/v1/recommendations/{user_id}\ — full three-module trace verified
• Goal at
  eality-emulation\ → recommendation advances to \concurrent-engineering\
• Each of all 6 SMILE phases advances exactly one step forward
• Goal at \perpetual-wisdom\ (final phase) handled gracefully — no crash
• Recommendation schema matches the \Recommendation\ Pydantic model exactly
• Recommendations sorted by priority descending
• No cross-module data leak (user A's signals don't appear in user B's recommendations)

TestPipelineThreeModuleFlow (5 tests) — the \POST /run\ endpoint

• Pipeline always returns exactly 3 cards
• All cards are valid \Recommendation\ objects
• Guaranteed 3 cards even with zero goals and zero signals (cold-start fallback)
• Pipeline references real goal UUID in \source_goals\
• Cards sorted priority descending

TestFeedbackLoop (4 tests)

• Accept feedback stored in
  ecommendation_feedback\ table
• Dismiss feedback stored correctly
• Requires JWT auth (401 without token)
• Cross-user feedback rejected (403)

---

Task 2 — Architecture Diagrams + README

New Section 2: System Architecture added to \README.md\ — did not exist before this PR.

Diagrams added:

Diagram	What it shows
High-level data flow	FastAPI → 3 modules → store.py → 6 Supabase tables
Database relationships	\goal_id\ FK on \�ctivity_signals, \
ecommendation_feedback\ schema
Goals → Recommendations	\score_goal()\ trace, \source_goals\ traceability
Signals → Recommendations	3 ingestion paths: GitHub webhook / manual POST / external (Boardy)
LangGraph pipeline	All 7 nodes (fetch/classify/reason/validate/enrich/fallback/finalise) with branching
Three-tier fallback	LLM → deterministic → cold-start, when each fires
Feedback loop	accept/dismiss → \
ecommendation_feedback\ → future re-ranking
End-to-end trace	Complete flow from user login to recommendation card

Other README updates:

• API Reference: added \POST /by-goal/{goal_id}\ endpoint
• API Reference: updated GitHub Auth table with
  epo_db\ explanation
• Database Schema: added \20260625000000_activity_signals_goal_fk.sql\ migration
• Webhook section: updated to show signals now actually persist to Supabase (PR feat: resolve GitHub webhook user_id — replace default_user with repo-mapped identity #41 fix)
• End-to-end trace: shows \ rack-repo\ →
  epo_db\ → \user_id\ resolution flow

New doc: \docs/boardy-integration-plan.md\ — integration guide for Boardy as first external data source (webhook URL, shared secret auth, event schema mapping, checklist).

---

Type

• Docs / reports
• Feature (new E2E test suite)

Checklist

• \make lint\ exits 0 (ruff + mypy clean)
• \make test\ exits 0 — 197 passed, 0 failed
• Tests added for changed behaviour (\ est_e2e_three_module_flow.py)
• No .env\ secrets committed
• PR targets \staging\

Tests passing

\
tests/test_e2e_three_module_flow.py — 25 tests (new)
tests/test_recommendations.py — 25 tests
tests/test_activity_signals.py — 23 tests
tests/test_goal_crud.py — 9 tests
tests/test_scoring.py — 48 tests
tests/test_smile.py — 19 tests
tests/test_rate_limit.py — 18 tests
tests/test_github_auth.py — 3 tests
tests/test_webhooks.py — 6 tests
tests/test_smoke.py — 3 tests
─────────────────────────────────────
TOTAL: 197 passed, 0 failed
\\

Daily report reference

Branch: \daksh-25-june-work\ — June 25, 2026