Skip to content

Asurion Command Center — Documentation

Real-time NPS-impact command center for support ops. Hackathon MVP with a Part C Databricks data binding slice in flight. This site is the rendered TechDocs surface — read top-down or jump straight to the area you're changing.

For judges

  • Presentation Deck -- 8 slides covering problem, solution, AI innovation, architecture, demo, integrations, what's real, and scale path. Directly pullable into a slide deck.
  • Integration Map -- Every external service integration (12 total) with file-path evidence the AI judge can verify.
  • AI Innovation -- How AI is embedded in Asurion workflows, not bolted on. Maps to "Asurion Innovation with AI" rubric.
  • Technical Evidence -- Test inventory (106 backend + 70 frontend), eval harness, live execution receipts, completeness checklist.

Start here

  • New to the repo? Read architecture.md first. It's the system view (FastAPI + Postgres + Redis + Databricks + Bedrock) and links out to every subsystem doc.
  • Changing the SQL gen / dictionary surface? sql-generator.md and data-dictionary.md own the app.sql_gen package and the dictionary CSVs.
  • Changing the Add Widget Clarifier? widget-builder.md is authoritative for the LangGraph topology, SSE contract, and WidgetSpec schema.
  • Preparing a demo? demo-runbook.md for the live arc, demo-queries.md for the three Databricks-routed metrics, whats-mocked-in-prototype.md for the Q&A defense.
  • Reviewing decisions? adrs/README.md is the index. ADRs are the binding decisions; the PRDs that originally hosted them are linked from each ADR's Source field.

Subsystems

Demo + Q&A

Decisions (ADRs)

  • Index + status table
  • 16 standalone ADRs covering v1 product decisions (ADR-001..010), Part C prototype decisions (ADR-PROTO-001..005), and the proposed v2 production architecture (ADR-V2-001).
  • Edits land in docs/adrs/ only. The PRDs carry "Canonical: see ..." pointers above their copies.

Lessons + open questions

  • Lessons Learned — append-only, four-field format. Read at session start before changing infra, the Clarifier graph, or Bedrock wiring.
  • Open Questions Resolved — what was on the table, who resolved it, and what was decided.

Plans

API spec

The full FastAPI OpenAPI spec is auto-exported to api/openapi.yaml by make export-openapi. Backstage's API entity reads from there. The live spec is always at http://localhost:8000/openapi.json.

Repository-level files

These live at the repo root and aren't rendered as TechDocs pages, but every doc above links into them:

  • prd.md — v1 product spec (scenarios, widgets, KPIs, original ADR set).
  • prd-v2.1.md — v2.1 PRD (supersedes v1 for Part A/B/C topics; adds ADR-PROTO-001..005 + ADR-V2-001).
  • prompts.md — Part C build script (hour-by-hour prompts).
  • CLAUDE.md — development discipline. Always in force.
  • AGENTS.md — agent navigation hub.
  • README.md — quick-start.
  • catalog-info.yaml — Backstage Software Catalog descriptor.
  • mkdocs.yml — TechDocs config that built this site.