{ "version": "1.8.0", "slug": "veterinary-insurance-claims-case-acceptance-desk", "title": "ClaimTail — The Veterinary Insurance Claims & Case-Acceptance Acceleration Desk", "vertical": "Healthcare / revenue cycle", "seed": { "s": "veterinary-insurance-claims-case-acceptance-desk", "t": "ClaimTail — The Veterinary Insurance Claims & Case-Acceptance Acceleration Desk", "v": "Healthcare / revenue cycle", "r": "Medium", "m": "M" }, "product": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "project_name": "ClaimTail", "project_type": "insurer-fluent claims-processing workflow application", "vertical": "Healthcare / revenue cycle", "audience": "practice managers, hospital administrators, and RCM leads at veterinary hospitals", "geography": "US, ministerial claims-processing scope first (verified against New York DFS guidance); state-by-state adjuster/TPA licensing review gated before each new state activates", "scale_expectation": "3-22 practice logos in year one; per-claim volume tied to each practice's insured-client share; high artifact fidelity", "core_workflows": [ "Visit intake & medical-record/invoice extraction", "Insurer rule library & completeness-checklist matching", "Claim packet assembly & claims-reviewer release", "Submission, status tracking & EOB reconciliation" ], "discovery": { "one_line_purpose": "On ClaimTail, practice managers stop chasing insurance paperwork and start shipping claims. A visit's medical-record export and itemized invoice are extracted at intake, checked against that insurer's completeness checklist in deterministic code, and every Claim Submission Pack releases with a claims-reviewer signature and a full audit trail.", "primary_users": [ "practice managers, hospital administrators, and RCM leads at veterinary hospitals", "Claims reviewer / DVM or credentialed-technician (clinical sign-off)", "Pet owner (policyholder, read-only status link)" ], "jobs_to_be_done": [ "Get every insured client's claim submitted within 24 hours without a front-desk staffer rebuilding it from the chart", "Catch claims pending past an insurer's normal processing window before the client complains", "Hand a client a fast, accurate benefit estimate before they decide on a costly treatment plan" ], "value_prop": "ClaimTail turns a scattered, multi-insurer claims-paperwork burden into a submitted, tracked, reconciled claim per visit — reviewer-released, audit-ready, with the practice always the commercial party and the insurer always the one deciding coverage.", "competitors": [ "Trupanion's single-insurer Vet Portal, which still requires the clinic to set it up and run it", "General veterinary PMS platforms that store policy fields but never assemble or submit a claim", "The front-desk staffer with ten free minutes, which is where this work lives today" ], "differentiation": "Done-for-you claim packets, not a portal: a maintained, insurer-by-insurer completeness-checklist library, a claims-reviewer signature on every submission, DVM/credentialed-technician sign-off on clinical appeal language, and an EOB-reconciliation trail — never a guess at coverage or payment.", "positioning_statement": "For practice managers and hospital administrators at veterinary hospitals who inherited the informal job of 'whoever has ten free minutes' filing insurance claims, ClaimTail is the done-for-you claims-processing desk that turns every insured client's visit into a submitted, tracked, and reconciled claim within 24 hours — unlike Trupanion's single-insurer Vet Portal, which covers one carrier and still requires clinic staff to operate it, or general PMS platforms, which store policy fields but never submit a claim." }, "assumptions": [ { "id": "veterinary-insurance-claims-case-acceptance-desk-a1", "statement": "Practices will pay a flat per-claim fee for a reviewer-released, audit-traceable submission over doing it in-house.", "confidence": "medium", "impact_if_wrong": "severe", "revisit_trigger": "First 5 design-partner sales calls — reject if willingness-to-pay signal is absent." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-a2", "statement": "A practice's medical-record export and itemized invoice contain enough structured data to extract a complete claim without a direct PMS integration at launch.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First real customer onboarding cycle." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-a3", "statement": "Insured clients will sign a claims authorization naming ClaimTail as processing agent, modeled on the Trupanion Express assignment-of-benefits pattern.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First client-facing pilot rollout." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-a4", "statement": "Ministerial claims-processing does not trigger adjuster/TPA licensure outside the New York guidance reviewed this run.", "confidence": "low", "impact_if_wrong": "severe", "revisit_trigger": "Counsel review before each new state activates." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-a5", "statement": "Single-tenant per practice is not required for the first cohort — logical isolation with row-level auth is acceptable.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "Any prospect with a hard single-tenant SOC/ISO clause." } ], "unknowns": [ { "id": "veterinary-insurance-claims-case-acceptance-desk-u1", "question": "Which specific claims reviewer and clinical sign-off contact will practices use at launch?", "blocks": "Any commercial claim; client-facing delivery.", "resolution_path": "Named reviewer + engagement letter on file before commercial engagement." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-u2", "question": "Which insurers and states are in scope for launch?", "blocks": "Rule-library build order; licensing-boundary review scope.", "resolution_path": "Owner confirms launch insurer list (top 4-5 by claim volume) and launch states in the owner-action pack." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-u3", "question": "What is the actual willingness-to-pay per claim?", "blocks": "Pricing hypothesis; unit economics.", "resolution_path": "5 design-partner discovery calls with an explicit pricing conversation." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-u4", "question": "Which PMS export formats must this integrate with day-one?", "blocks": "Architecture module boundaries; extraction-prompt design.", "resolution_path": "Design-partner tech-inventory questionnaire (ezyVet, Shepherd, Digitail, Covetrus Pulse, Cornerstone)." }, { "id": "veterinary-insurance-claims-case-acceptance-desk-u5", "question": "Is there a data-residency or on-prem constraint from any design partner?", "blocks": "Deployment topology; hosting/region choice.", "resolution_path": "Vendor-diligence questionnaire from first prospect." } ], "expert_panel": [ { "role": "Product Strategy", "key_concern": "Is the ICP narrow enough to earn a first design-partner cohort?", "recommendation": "Constrain the ICP to independent/small-group specialty and emergency veterinary hospitals for launch; broaden only after 5 signed design partners.", "dissent": "May under-price total addressable market and slow fundraising narrative." }, { "role": "Software Architecture", "key_concern": "Are we defaulting to microservices/serverless without justification?", "recommendation": "Single deployable modular monolith with a documented seam for the highest-volume module.", "dissent": "May feel unsophisticated to enterprise reviewers who expect a service-mesh diagram." }, { "role": "Frontend / UX", "key_concern": "Is the evidence spine visible and trustable in every workflow?", "recommendation": "Every artifact view must render claim → evidence → reviewer signature in one glance.", "dissent": "Adds vertical density that non-domain reviewers may call cluttered." }, { "role": "Backend / Data", "key_concern": "Is the audit trail append-only and reconstructable?", "recommendation": "Event-sourced audit log for all state transitions; snapshots for read models.", "dissent": "Higher write-path complexity than plain CRUD; discipline required on schema evolution." }, { "role": "AI / ML", "key_concern": "Are AI outputs grounded, cited, and reviewer-gated?", "recommendation": "Retrieval-first with source citations, structured output validation, and human-in-the-loop for external delivery.", "dissent": "Slower than open-ended chat; may frustrate prospects expecting 'agentic magic'." }, { "role": "Security", "key_concern": "Is the STRIDE surface documented and mitigated?", "recommendation": "Threat model per module, per-tenant isolation with row-level auth, secrets in managed KMS, dependency scanning in CI.", "dissent": "Overhead in early prototype; some controls can wait until first paying customer." }, { "role": "Privacy / Compliance", "key_concern": "Is the compliance target realistic for year-one team size?", "recommendation": "SOC 2 Type I in year one with mapped controls for downstream Type II; defer heavier frameworks until required by a real contract.", "dissent": "May lock out enterprise buyers requiring HITRUST/ISO on day one." }, { "role": "DevOps / Reliability", "key_concern": "Is the ops model boring enough to run without a dedicated SRE?", "recommendation": "Single production region + managed database + Vercel/Cloud edge; SLO published as availability + p95 latency only.", "dissent": "Single region concentrates risk during regional outages." }, { "role": "Data / Analytics", "key_concern": "Are the leading indicators wired before launch?", "recommendation": "Instrument activation, artifact-completion, and reviewer-signoff events; ship dashboards before first design partner.", "dissent": "Analytics scope-creep can steal weeks from core product." }, { "role": "Accessibility", "key_concern": "Does the workflow meet WCAG 2.2 AA for every screen a reviewer uses?", "recommendation": "Enforce keyboard-only walkthrough for every workflow; add axe-core to CI on the reviewer surfaces.", "dissent": "Density-heavy vertical UIs are hard to ship AA-clean quickly." }, { "role": "SEO / Content", "key_concern": "Is the microsite claim honest and gated on evidence?", "recommendation": "Regulator-fluent topical-authority content only; no fake reviews, no LocalBusiness identity schema until owner-facts close.", "dissent": "Slower content velocity than a generic SaaS blog." }, { "role": "Executive Sponsor", "key_concern": "Is there a written kill criterion?", "recommendation": "Kill/pivot decision at 90 days if no design-partner LOI or if reviewer-signoff cycle exceeds 5 business days.", "dissent": "Founders often resist naming kill criteria in writing." } ], "strategy": { "business_model": "B2B flat per-claim fee + per-location monthly retainer, never hourly", "revenue_streams": [ "Claim Submission Pack (per-claim fee)", "Denial-Appeal Service (per-appeal fee)", "Eligibility & Monitoring Retainer (per-location monthly)" ], "moat": [ "Maintained insurer-by-insurer completeness-checklist library", "PMS export/integration familiarity", "Portfolio-wide claim-status tracking + EOB-reconciliation audit trail" ], "gtm": [ "Founder-led design-partner cohort (5-10 practices)", "Specialty/emergency-hospital outbound + veterinary trade-association presence", "Free Unclaimed Revenue Scan lead magnet" ], "pricing_hypothesis": "Launch at $12/claim (low end of the $12-18 band); validate willingness-to-pay before any tier increase.", "kill_criteria": [ "No signed design-partner LOI in 4 weeks", "Claims-reviewer sign-off cycle exceeds 24 hours after Phase 1", "No paid conversion by week 20", "A state's adjuster/TPA statute is confirmed to sweep in ministerial claims-processing" ] }, "security": { "stride": [ { "threat": "Spoofing", "scenario": "Attacker attempts to impersonate a reviewer to sign off on a fabricated artifact.", "mitigation": "SSO with MFA; reviewer signatures bound to a cryptographic session claim, not a form field." }, { "threat": "Tampering", "scenario": "Historical evidence entries edited after the fact to hide a bad claim.", "mitigation": "Append-only audit log; hash-chained artifact snapshots; diff view on every reviewer surface." }, { "threat": "Repudiation", "scenario": "Reviewer denies signing off on a delivered artifact.", "mitigation": "Signed attestations with server-side timestamp + reviewer identity; export bundle includes signature manifest." }, { "threat": "Information Disclosure", "scenario": "Cross-tenant leak of Regulated-record, PII, Internal-audit data through shared indices, logs, or prompts.", "mitigation": "Tenant-scoped row-level auth; PII scrubbing in logs; retrieval indices partitioned per tenant." }, { "threat": "Denial of Service", "scenario": "Runaway AI job or export exhausts shared workers.", "mitigation": "Per-tenant concurrency + budget caps; circuit breaker on model calls; degrade-gracefully queue." }, { "threat": "Elevation of Privilege", "scenario": "Standard user acquires reviewer or admin capability via a workflow shortcut.", "mitigation": "Roles stored in a separate table; capability checks server-side; no client-only role checks." } ], "privacy_posture": "Data-minimization by default; per-tenant isolation; DPA + BAA templates on file; DSAR runbook published.", "compliance_targets": [ "the completeness checklist 3-year record retention", "SOC 2 Type II", "ISO 27001 (year two)" ], "data_classifications": [ "Regulated-record", "PII", "Internal-audit" ] }, "devops": { "ci_cd": "PR → typecheck + unit + snapshot tests → preview deploy → main auto-deploys to a single production region; migrations gated on review.", "environments": [ "local", "preview (per-PR)", "staging (shared)", "production (single region + multi-AZ)" ], "observability": [ "Structured logs with tenant + request IDs", "RED metrics per workflow", "Error tracking with source maps", "Model-call spans with cost + latency", "Weekly SLO review" ], "testing_pyramid": [ "Unit tests on derivation + validation modules", "Component tests on reviewer surfaces", "Contract tests on integrations", "End-to-end smoke test on the intake→signoff→delivery path" ], "accessibility_tests": [ "axe-core in CI on reviewer surfaces", "Keyboard-only walkthrough per workflow", "Prefers-reduced-motion honored" ], "performance_budget": "p95 workflow latency published per module; artifact-generation cold-path under 30s or shown as background job." }, "accessibility_i18n_ethics": { "wcag_target": "AA", "locales": [ "en-US" ], "rtl_support": false, "ethical_risks": [ "Claim packet submitted without claims-reviewer review", "Cross-insurer completeness-rule confusion (one insurer's checklist applied to another's claim)", "Insurer-facing or client-facing errors attributed to AI without a human signature" ], "ethical_guardrails": [ "Claims-reviewer sign-off required before every submission", "Per-insurer rule-set isolation (each InsurerRuleSet versioned and scoped to its own carrier)", "AI-usage disclosure available on request; no AI-generated field ships without a source quote" ] }, "governance": { "ownership": [ { "area": "Product + roadmap", "owner": "Executive Sponsor" }, { "area": "Architecture + platform", "owner": "Engineering Lead" }, { "area": "Evidence + reviewer workflow", "owner": "Named licensed reviewer" }, { "area": "Compliance + privacy", "owner": "Compliance Lead" }, { "area": "Design system", "owner": "Design Lead" }, { "area": "SEO + content", "owner": "Content Lead" } ], "docs_required": [ "ADR log (checked in)", "Owner-action ledger", "Evidence register", "STRIDE threat model", "Runbook: incident, restore, breach notification", "Reviewer playbook + signature policy" ], "naming_conventions": [ "kebab-case slugs for blueprints and routes", "camelCase for TypeScript identifiers", "SCREAMING_SNAKE_CASE for environment variables", "Verb-first action names (e.g., generate-blueprint-docs)" ], "change_control": "ADR-per-major-decision; migrations require review; production deploys gated on green CI + owner-action ledger check." }, "risk_register": [ { "id": "veterinary-insurance-claims-case-acceptance-desk-r1", "risk": "A state's adjuster/TPA statute sweeps in ministerial claims-processing more broadly than the New York framework relied on", "likelihood": "medium", "impact": "severe", "mitigation": "Counsel review before each new state activates; ministerial-only scope enforced structurally", "contingency": "Pause onboarding in that state; retroactive review of any claims already processed there", "owner": "legal" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-r2", "risk": "AI extraction hallucinates a field not present in the source chart/invoice", "likelihood": "medium", "impact": "high", "mitigation": "Retrieval-grounded extraction + structured output validation + 100% claims-reviewer review in first 90 days", "contingency": "Reviewer-triggered correction; claim held until re-verified against source", "owner": "engineering" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-r3", "risk": "Cross-practice data leak", "likelihood": "low", "impact": "severe", "mitigation": "Row-level auth + per-practice retrieval indices + log-scrubbing", "contingency": "Breach-notification runbook; forced credential rotation; scoped practice kill switch", "owner": "engineering" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-r4", "risk": "Design-partner practice churns before signing a paid engagement", "likelihood": "medium", "impact": "high", "mitigation": "Weekly working-session cadence during pilot; the free Unclaimed Revenue Scan de-risks first commitment", "contingency": "Structured exit interview; write learnings into ICP + pricing hypothesis", "owner": "owner" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-r5", "risk": "Reviewer bottleneck as claim volume grows faster than reviewer capacity", "likelihood": "high", "impact": "high", "mitigation": "Pilot cap (5 practices in month 1); part-time contractor reviewer added around month 7 per financial model", "contingency": "Pause new-logo onboarding until reviewer capacity catches up", "owner": "ops" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-r6", "risk": "Insurer submission-format change breaks the rule library mid-cycle", "likelihood": "medium", "impact": "high", "mitigation": "Versioned rule library + standing rule-watch SOP", "contingency": "Freeze new submissions for that insurer until rule library is updated and re-validated", "owner": "engineering" } ], "roadmap": [ { "phase": "Phase 0 — Discovery + design-partner LOI", "weeks": "Weeks 1-4", "outcomes": [ "3-5 design-partner LOIs", "Evidence pack from each partner", "Written ICP + pricing hypothesis" ], "exit_criteria": [ "≥3 LOIs signed", "Owner-action ledger populated per partner", "Reviewer identity confirmed" ], "kill_criteria": [ "<2 LOIs after 4 weeks", "No willingness-to-pay signal above cost baseline" ] }, { "phase": "Phase 1 — Thin vertical slice", "weeks": "Weeks 5-10", "outcomes": [ "Intake → evidence → reviewer signoff → delivery working end-to-end for one workflow", "Audit trail wired", "Instrumentation live" ], "exit_criteria": [ "1 real artifact delivered + reviewer-signed", "p95 workflow latency published" ], "kill_criteria": [ "Reviewer signoff cycle >5 business days", "Evidence pack cannot be reconstructed on demand" ] }, { "phase": "Phase 2 — Design-partner cohort", "weeks": "Weeks 11-20", "outcomes": [ "3 partners in weekly production use", "First paid conversion", "SOC 2 Type I scoping" ], "exit_criteria": [ "≥1 paid contract", "NPS or equivalent trust signal captured", "Postmortem cadence in place" ], "kill_criteria": [ "No paid conversion by week 20", "Compliance framework demand exceeds team capacity without contract offset" ] }, { "phase": "Phase 3 — Commercial launch", "weeks": "Weeks 21-36", "outcomes": [ "Public commercial launch of at least one microsite as 'ready'", "SOC 2 Type I completed", "Owner-action ledger closed for launched blueprints" ], "exit_criteria": [ "Zero blocking owner actions for launched blueprints", "Publicly indexable microsite with WebPage+FAQPage schema only" ], "kill_criteria": [ "Public launch not defensible against a plausible regulator inquiry" ] } ], "metrics": { "north_star": "Released Claim Submission Packs per week, per logo, with zero re-issues for defects of our making", "leading": [ "Design-partner LOIs signed", "Intake → artifact cycle time", "Reviewer signoff cycle time", "Evidence coverage per artifact", "Owner-action ledger closure rate" ], "lagging": [ "Paid contracts signed", "Net revenue retention (post first cohort)", "Regulator or auditor objection count (target: 0)", "Retraction count on delivered artifacts (target: 0)" ], "guardrails": [ "Model spend per tenant per week", "PII in logs (target: 0)", "Cross-tenant access attempts (target: 0)", "p95 workflow latency ceiling" ] }, "executive_review": { "consensus": "Ship a thin, evidence-linked, reviewer-gated vertical slice for ClaimTail. Prefer a boring, single-region modular monolith. Do not launch commercially until owner-action facts close and at least one reviewer-signed artifact is delivered.", "dissent": "Executive Sponsor and Privacy/Compliance disagree on launch tempo — Privacy recommends waiting for SOC 2 Type II mapping before any public commercial claim.", "go_no_go": "conditional-go", "top_3_risks": [ "Regulator-facing claim proves incorrect", "AI hallucination in a delivered artifact", "Cross-tenant data leak" ], "first_10_steps": [ "Confirm the named licensed reviewer + engagement letter on file", "Populate owner-action ledger with entity, jurisdiction, contact inbox, privacy inbox", "Open 5 design-partner discovery calls with explicit pricing conversation", "Write ICP + kill/pivot criteria in the plan file", "Stand up the evidence-linked intake → artifact → reviewer signoff loop", "Wire append-only audit log + hash-chained snapshots", "Add row-level auth + tenant-scoped retrieval indices", "Instrument activation, artifact-completion, and reviewer-signoff events", "Publish the microsite with WebPage+FAQPage schema only and noindex until owner-facts close", "Schedule the 90-day kill/pivot review with executive sponsor" ] } }, "project_site": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "app_name": "ClaimTail Desk", "archetype": "filing-dossier", "archetype_label": "claims processing desk", "reader_role": "Practice Manager", "one_sentence_app": "ClaimTail Desk is a claims processing desk for practice managers who need every insured client's visit tied to a submitted, insurer-complete claim before the client asks 'did anyone ever file this?'", "homepage_sequence": [ "scene", "workflow", "instrument", "offer", "proof", "qualification", "objections" ], "hero": { "frame_label": "Healthcare / revenue cycle · claims processing desk", "eyebrow": "Practice Manager / insured-client visit invoice", "interface_title": "ClaimTail release desk", "primary_panel_title": "Visit #4821 · Healthy Paws claim · confidence 96%", "primary_panel_body": "Open claim run: extract the chart and invoice fields, match the insurer's completeness checklist, then stage the Claim Submission Pack for claims-reviewer release.", "side_panel_title": "Before this ships", "side_panel_items": [ "Claims authorization on file", "Completeness checklist satisfied", "Tracked status link staged" ], "status_metric": "REVIEW", "status_label": "claims-reviewer gate active" }, "language": { "problem_heading": "The Practice Manager moment", "mechanism_heading": "Inside the ClaimTail Desk", "proof_heading": "Why this claim doesn't stall", "offer_heading": "What leaves the room", "objection_heading": "The hard questions", "qualification_heading": "Who should not use this", "cta_close": "Open a claim run from your most recent insured-client visit — released by a real claims reviewer, escalated to a DVM or credentialed technician when clinical language is involved." }, "modules": [ { "name": "Visit intake", "job": "Turns a forwarded medical-record export and invoice into a named claim run with an insurer match, extracted fields, and a missing-field list.", "artifact": "triage record" }, { "name": "Insurer rule library", "job": "Holds every covered insurer's completeness checklist, required attachments, and submission format — with the source guidance behind each.", "artifact": "completeness checklist" }, { "name": "Claim Submission Pack", "job": "Packages the extracted claim, the completeness check, and the submission confirmation into the record a practice or client can check any time.", "artifact": "release package" } ], "checkpoints": [ { "label": "Completeness-checklist field", "pass": "extracted with source quote", "fail": "flagged or shipped as explicit gap" }, { "label": "claim extraction", "pass": "confidence-scored, reviewer-confirmed below threshold", "fail": "blocked before assembly" }, { "label": "Claim Submission Pack", "pass": "claims reviewer releases (clinical sign-off on appeals)", "fail": "stays draft" } ], "signature_scene": "You're a Practice Manager. It's the morning after an insured client's visit generated a $2,400 invoice. Someone needs to know — today — whether the claim packet is complete enough to submit, and the only evidence is an invoice that says 'recheck, meds sent home.' This page is built like the claims desk that person needed before the client started asking questions." }, "ddd": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "project_name": "ClaimTail", "business_understanding": { "summary": "ClaimTail — On ClaimTail, practice managers stop chasing insurance paperwork and start shipping claims. A visit's medical-record export and invoice are extracted at intake, checked against a maintained insurer completeness checklist, and every Claim Submission Pack releases with a claims-reviewer signature and a full audit trail.", "customer_profile": "practice managers, hospital administrators, and RCM leads at independent or small-group (1-5 location) veterinary hospitals with meaningful insured-client volume and no dedicated claims-processing staff", "customer_pain": "Insured-client invoices missing the fields a specific insurer's claim form needs; claims never submitted or submitted incomplete; claims sitting past a normal processing window nobody is tracking; no fast way to tell a client what their insurance will likely cover before a costly treatment plan.", "paid_outcome": "A submitted, tracked, and reconciled Claim Submission Pack per insured-client visit, reviewer-released, with DVM/credentialed-technician sign-off on any clinical appeal language — reconstructable on demand, defensible if a client disputes the outcome.", "value_creation": "AI compresses medical-record and invoice extraction, insurer-format matching, and packet drafting; deterministic code owns every completeness check and days-pending calculation; humans own claims-reviewer release, clinical sign-off, and anything that touches coverage judgment; the platform binds them with an append-only audit trail and per-practice isolation.", "why_ai_native": "The extract-check-assemble-track loop is only economical with a bounded AI layer feeding deterministic completeness rules. A pure-manual service cannot hit $12-18 per-claim pricing; a pure-automated tool cannot chase insurers, hold the release gate, or absorb the judgment calls that keep a claim from bouncing back for more documentation.", "operational_risks": [ "Claims-reviewer bottleneck as practice count grows faster than reviewer capacity", "Prompt injection via invoice/chart content", "Cross-practice retrieval leak", "Insurer submission-format drift breaking the completeness checklist mid-cycle", "Silent delivery failure on a claim pending past its normal window" ], "assumptions": [ "Practices will pay a flat per-claim fee for a reviewer-released, audit-traceable submission over doing it in-house.", "A practice's medical-record export and itemized invoice contain enough structured data to extract a complete claim without a direct PMS integration at launch.", "Insured clients will sign a claims authorization naming ClaimTail as processing agent.", "Ministerial claims-processing does not trigger adjuster/TPA licensure outside the New York guidance reviewed this run.", "Single-tenant per practice is not required for the first cohort — logical isolation with row-level auth is acceptable." ], "validation_questions": [ "Which claims reviewer and clinical sign-off contact will practices use at launch?", "Which insurers and states are in scope for launch?", "What is the actual willingness-to-pay per claim?", "Which PMS export formats must this integrate with day-one?", "Is there a data-residency or on-prem constraint from any design partner?" ] }, "domain_discovery": { "actors": [ { "actor": "Practice manager / hospital administrator", "role": "practice managers, hospital administrators, and RCM leads at veterinary hospitals", "goals": [ "Get every insured claim submitted on time", "Reduce front-desk time lost to claims paperwork" ], "decisions": [ "Submit visit intake", "Accept or revise a flagged extraction", "Approve escalated exceptions" ], "pain_points": [ "Scattered claims paperwork across email and PMS exports", "Manual re-typing into insurer forms", "Claims-reviewer bottleneck at high volume" ] }, { "actor": "Claims reviewer", "role": "Signs and takes accountability for every submitted Claim Submission Pack", "goals": [ "Sign only what's defensible against the insurer's completeness checklist", "Keep the audit trail intact" ], "decisions": [ "Approve or return a packet for correction", "Route ambiguous claims to the exception queue" ], "pain_points": [ "Volume spikes around insured-client visit surges", "Insurer format changes invalidating in-flight claims" ] }, { "actor": "DVM / credentialed veterinary technician", "role": "Signs off on any clinical medical-necessity language in a denial appeal", "goals": [ "Ensure appeal language never overstates the chart", "Protect the practice's clinical credibility with the insurer" ], "decisions": [ "Approve or edit appeal language", "Decline to sign off, sending the appeal back" ], "pain_points": [ "Time pressure when an appeal deadline is close" ] }, { "actor": "Pet owner (policyholder)", "role": "Signs the claims authorization; receives the tracked status link", "goals": [ "Get reimbursed quickly and know the claim's status without calling the practice" ], "decisions": [ "Sign or decline the claims authorization" ], "pain_points": [ "No visibility into whether a claim was ever submitted" ] }, { "actor": "Insurer (external)", "role": "Owns the coverage decision and payment authorization at all times", "goals": [ "Receive a complete, correctly-formatted claim" ], "decisions": [ "Approve, deny, or request more documentation" ], "pain_points": [ "Incomplete submissions requiring back-and-forth" ] } ], "glossary": [ { "term": "claim run", "definition": "One insured-client visit's claim, from intake through submission — the unit of work ClaimTail turns into a Claim Submission Pack.", "used_by": "Practice manager, Claims reviewer", "context": "Claims Intake", "example": "\"Open a claim run for the dental visit at Location 2\"", "notes": "Do not confuse with 'engagement' in Billing (contract term)." }, { "term": "completeness checklist", "definition": "The deterministic, insurer-specific list of required fields/attachments a Claim Submission Pack must satisfy before release.", "used_by": "Claims reviewer, AI Orchestrator", "context": "Insurer Rule Library", "example": "\"Healthy Paws' completeness checklist requires an itemized diagnosis code\"", "notes": "Never the same as a generic intake checklist — it is insurer-specific and versioned." } ], "decisions": [ { "decision": "Accept claim intake", "who": "Claims Intake context (rule + reviewer override)", "inputs": [ "Practice identity", "Medical-record export", "Itemized invoice" ], "rule": "Reject if invoice below claimable-visit threshold or claims authorization missing", "output": "ClaimIntakeReceived event", "risk": "Accepting an out-of-scope claim wastes extraction and reviewer time." }, { "decision": "Approve a Claim Submission Pack for submission", "who": "Claims Review context (claims reviewer)", "inputs": [ "Assembled ClaimPacket", "Completeness checklist result", "Source chart/invoice data" ], "rule": "Reject if any completeness_checklist item is open", "output": "ClaimPacketApproved event", "risk": "Approving an incomplete packet risks an insurer bounce-back." } ], "events": [ { "event": "claimIntakeReceived", "meaning": "A visit's claim is now committed to the extraction pipeline", "trigger": "Practice manager or front desk submits a claim intake", "downstream": [ "Extraction begins", "AI Orchestrator scheduled" ] }, { "event": "claimSubmitted", "meaning": "The packet has left ClaimTail and is now with the insurer", "trigger": "Claims reviewer approves and submits", "downstream": [ "Status tracking begins", "Client notified" ] } ] }, "subdomains": [ { "name": "Claims Fulfillment (extraction + assembly + submission)", "type": "core", "description": "The end-to-end path from visit intake to claims-reviewer-released, submitted Claim Submission Pack, with every field cited.", "reason": "This is what practices pay for and what a client's status link shows.", "business_value": "Direct revenue and client trust.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "high", "risks": [ "Hallucinated field", "Reviewer bottleneck", "Un-reconstructable audit trail" ], "validation_questions": [ "Can the reviewer release in <24 hours?" ] }, { "name": "Insurer Rule Library (completeness checklists)", "type": "supporting", "description": "Maintained, versioned, insurer-by-insurer submission-format and completeness rules.", "reason": "Without it, extraction has no target to check against.", "business_value": "Durable moat as insurer count grows.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Insurer format drift", "Stale rule versions" ], "validation_questions": [ "How often do insurers change submission formats?" ] }, { "name": "Exception Handling (coverage disputes, clinical judgment)", "type": "supporting", "description": "Routes coverage disputes and pre-existing-condition questions to human triage instead of the automated pipeline.", "reason": "Keeps ClaimTail structurally ministerial.", "business_value": "Regulatory-boundary protection.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "high", "risks": [ "Misclassified exception proceeding through automation" ], "validation_questions": [ "What share of claims route to exceptions at scale?" ] }, { "name": "Billing & Revenue", "type": "generic", "description": "Per-claim invoicing and retainer billing.", "reason": "Not a differentiator.", "business_value": "Necessary but not core.", "recommendation": "buy", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Billing errors" ], "validation_questions": [] } ], "core_domain_analysis": { "primary_core": "Service Fulfillment (evidence-linked drafting + review)", "secondary_cores": [ "AI Orchestration (bounded agents + retrieval)", "Quality Assurance (reviewer signoff + retraction)" ], "supporting_may_become_core": [ "Knowledge Base & Retrieval (as vertical corpora accumulate)", "Compliance & Governance (as regulator interactions increase)" ], "generic_do_not_distract": [ "Billing & Revenue", "Identity & Access" ], "rationale": "The paid outcome (reviewer-signed, evidence-linked artifact) lives in Fulfillment, but its defensibility depends on AI Orchestration + QA behaving correctly. Treat all three as core; do not dilute engineering time on generic subdomains." }, "bounded_contexts": [ { "name": "Service Fulfillment", "purpose": "Turn accepted service events into reviewer-signed Claim Submission Packs.", "subdomain": "Service Fulfillment (core)", "type": "core", "owned_language": [ "service event", "field evidence", "Claim Submission Pack", "Draft", "Escalation", "Signoff" ], "owns": [ "service event lifecycle", "Draft state", "Evidence links", "Delivery packet composition" ], "does_not_own": [ "Reviewer identity", "Billing", "Public claim decision" ], "primary_actors": [ "Customer operator", "AI Orchestrator", "credentialed-technician reviewer" ], "entities": [ "service event", "Draft", "Claim Submission Pack", "Delivery" ], "value_objects": [ "Confidence score", "Evidence citation", "Delivery address" ], "aggregates": [ "ServiceEventAggregate", "ClaimPacketAggregate" ], "domain_services": [ "Draft composer", "Delivery adapter" ], "application_services": [ "OpenServiceEvent", "RequestDraft", "AttachEvidence", "RequestSignoff", "DeliverClaimPacket" ], "commands": [ "OpenIntake", "AttachEvidence", "RequestDraft", "SubmitForSignoff", "DeliverArtifact" ], "domain_events": [ "ServiceEventAccepted", "EvidenceCollected", "DraftReady", "ArtifactSigned", "ArtifactDelivered" ], "policies": [ "Auto-request signoff when evidence coverage complete", "Auto-block delivery until signoff received" ], "specifications": [ "EvidenceCoverageSpec", "DeliverabilitySpec" ], "invariants": [ "A Claim Submission Pack cannot be delivered without a valid Reviewer signoff", "Every claim in a delivered artifact cites at least one evidence item" ], "ai_agents": [ "Drafter Agent" ], "human_roles": [ "Customer operator", "credentialed-technician reviewer" ], "data_owned": [ "service event", "Draft", "Claim Submission Pack", "Delivery" ], "inputs": [ "Intake payload", "Uploaded evidence", "Retrieval hits" ], "outputs": [ "Signed artifact packet", "Delivery confirmation" ], "external_integrations": [ "Vendor invoice inboxes", "HVAC work-order / CMMS platforms" ], "risks": [ "Un-cited claim slips into delivery", "Delivery adapter fails silently" ], "interfaces": [ "→ Quality Assurance (RequestSignoff)", "→ Client Delivery (ArtifactDelivered)", "← AI Orchestration (DraftProduced)" ] }, { "name": "AI Orchestration", "purpose": "Run bounded AI agents that draft, validate, cite, and escalate.", "subdomain": "AI Orchestration (core)", "type": "core", "owned_language": [ "Prompt version", "Confidence score", "Escalation", "Retrieval hit" ], "owns": [ "Prompt registry", "Agent run log", "Confidence thresholds" ], "does_not_own": [ "Evidence sourcing", "Reviewer signature", "Business decisions" ], "primary_actors": [ "AI Orchestrator", "Ops (prompt owner)" ], "entities": [ "AgentRun", "PromptVersion", "RetrievalHit" ], "value_objects": [ "Confidence score", "Token budget", "Model cost" ], "aggregates": [ "AgentRunAggregate", "PromptRegistryAggregate" ], "domain_services": [ "Retrieval router", "Output validator", "Escalation router" ], "application_services": [ "StartAgentRun", "ValidateOutput", "PublishPromptVersion" ], "commands": [ "StartAgentRun", "PublishPromptVersion", "SetConfidenceThreshold" ], "domain_events": [ "DraftProduced", "EscalationRaised", "PromptVersionPublished" ], "policies": [ "Escalate on confidence < threshold", "Never call model with cross-tenant retrieval context", "Reject output failing structured-output validator" ], "specifications": [ "GroundedOutputSpec", "TokenBudgetSpec" ], "invariants": [ "No AI output leaves this context without passing OutputValidator", "Prompt versions are immutable once published" ], "ai_agents": [ "Drafter Agent", "Classifier Agent", "Evaluator Agent" ], "human_roles": [ "Prompt owner (Ops)" ], "data_owned": [ "Prompt registry", "Agent run logs", "Confidence thresholds" ], "inputs": [ "Intake context", "Retrieval hits", "Prompt version" ], "outputs": [ "Draft payload", "Escalation event", "Run trace" ], "external_integrations": [ "OpenAI / Anthropic API", "Retrieval index" ], "risks": [ "Prompt injection via customer input", "Retrieval leakage across tenants", "Silent hallucination" ], "interfaces": [ "→ Service Fulfillment (DraftProduced)", "→ Quality Assurance (EscalationRaised)", "← Knowledge Base (RetrievalHit)" ] }, { "name": "Quality Assurance", "purpose": "Reviewer workflow, signature capture, retraction workflow, audit-log snapshots.", "subdomain": "Quality Assurance (core)", "type": "core", "owned_language": [ "Signoff", "Retraction", "Reviewer session" ], "owns": [ "Signature log", "Reviewer queue", "Retraction workflow" ], "does_not_own": [ "Claim Submission Pack content", "Public release decision" ], "primary_actors": [ "credentialed-technician reviewer", "Legal" ], "entities": [ "Signoff", "Retraction", "ReviewerSession" ], "value_objects": [ "Signature manifest", "Retraction reason" ], "aggregates": [ "SignoffAggregate", "RetractionAggregate" ], "domain_services": [ "Signature service", "Retraction service" ], "application_services": [ "ApproveArtifact", "RejectArtifact", "FileRetraction" ], "commands": [ "ApproveArtifact", "RejectArtifact", "FileRetraction" ], "domain_events": [ "ArtifactSigned", "ArtifactRejected", "RetractionFiled" ], "policies": [ "Only the release analyst or clinical reviewer may sign", "Retraction requires legal co-signer" ], "specifications": [ "ReviewerAuthoritySpec", "RetractionPreconditionsSpec" ], "invariants": [ "A signature is bound to a live authenticated session, not a form field", "Signed artifacts are immutable; corrections go through Retraction" ], "ai_agents": [], "human_roles": [ "credentialed-technician reviewer", "Legal" ], "data_owned": [ "Signatures", "Retractions", "Reviewer sessions" ], "inputs": [ "Draft ready", "Escalation payload" ], "outputs": [ "Signoff event", "Retraction event" ], "external_integrations": [ "IdP (Okta / Google)" ], "risks": [ "Signature spoofing", "Repudiation" ], "interfaces": [ "→ Service Fulfillment (ArtifactSigned)", "→ Compliance & Governance (RetractionFiled)" ] }, { "name": "Compliance & Governance", "purpose": "Own the release decision, owner-action ledger, DSAR + retraction runbooks.", "subdomain": "Compliance & Governance (supporting)", "type": "supporting", "owned_language": [ "Owner action", "Release decision", "DSAR" ], "owns": [ "Owner-action ledger", "Release-decision policy", "DSAR queue" ], "does_not_own": [ "Claim Submission Pack content", "Reviewer identity" ], "primary_actors": [ "Business owner", "Legal", "credentialed-technician reviewer" ], "entities": [ "OwnerAction", "ReleaseDecision", "DSARRequest" ], "value_objects": [ "Blocker reason", "Jurisdiction" ], "aggregates": [ "OwnerActionLedgerAggregate", "ReleaseDecisionAggregate" ], "domain_services": [ "Release-decision engine", "DSAR fulfillment service" ], "application_services": [ "ResolveOwnerAction", "RecomputeReleaseDecision", "ProcessDSAR" ], "commands": [ "ResolveOwnerAction", "RaiseOwnerAction", "ProcessDSAR" ], "domain_events": [ "OwnerActionResolved", "ReleaseDecisionChanged", "DSARFulfilled" ], "policies": [ "Block public release while any owner action open", "DSAR SLA 30 days" ], "specifications": [ "ReleaseReadinessSpec", "DSARSpec" ], "invariants": [ "Release cannot flip to 'ready' with open blocking owner actions", "Every DSAR is auditable end-to-end" ], "ai_agents": [], "human_roles": [ "Business owner", "Legal" ], "data_owned": [ "Owner-action ledger", "Release decisions", "DSAR queue" ], "inputs": [ "Owner input", "Legal review outcome" ], "outputs": [ "Release-decision event", "DSAR confirmation" ], "external_integrations": [ "Email inbox" ], "risks": [ "Public release while blocker open" ], "interfaces": [ "← Service Fulfillment", "← Quality Assurance (RetractionFiled)" ] }, { "name": "Sales & Intake", "purpose": "Lead → qualified engagement → accepted intake.", "subdomain": "Sales & Intake (supporting)", "type": "supporting", "owned_language": [ "Lead", "Engagement", "Scope statement" ], "owns": [ "Lead pipeline", "Engagement letter", "Scope statement" ], "does_not_own": [ "Fulfillment", "Billing" ], "primary_actors": [ "Owner", "Customer" ], "entities": [ "Lead", "Engagement" ], "value_objects": [ "Scope statement", "Pricing offer" ], "aggregates": [ "EngagementAggregate" ], "domain_services": [ "Scope-fit evaluator" ], "application_services": [ "QualifyLead", "AcceptEngagement" ], "commands": [ "QualifyLead", "AcceptEngagement" ], "domain_events": [ "EngagementAccepted" ], "policies": [ "Reject out-of-ICP engagement", "Engagement letter required before intake" ], "specifications": [ "ScopeFitSpec" ], "invariants": [ "Cannot open an intake without an accepted engagement" ], "ai_agents": [ "Qualifier Copilot (assist only)" ], "human_roles": [ "Owner", "Sales lead" ], "data_owned": [ "Leads", "Engagements" ], "inputs": [ "Lead form", "Discovery notes" ], "outputs": [ "Accepted engagement event" ], "external_integrations": [ "CRM", "Email inbox" ], "risks": [ "Accepting out-of-scope engagement" ], "interfaces": [ "→ Client Onboarding", "→ Service Fulfillment (intake enablement)" ] }, { "name": "Client Onboarding & Profile", "purpose": "Provision tenant, capture reviewer identity, import evidence pack.", "subdomain": "Client Onboarding & Profile (supporting)", "type": "supporting", "owned_language": [ "Tenant", "Reviewer identity", "Evidence pack" ], "owns": [ "Tenant provisioning", "Reviewer identity record", "Evidence pack import" ], "does_not_own": [ "Signature capture", "Delivery" ], "primary_actors": [ "Onboarding lead", "Customer admin" ], "entities": [ "Tenant", "ReviewerIdentity", "EvidencePackImport" ], "value_objects": [ "Contact matrix", "Jurisdiction set" ], "aggregates": [ "TenantAggregate" ], "domain_services": [ "Tenant provisioner" ], "application_services": [ "ProvisionTenant", "RegisterReviewer", "ImportEvidencePack" ], "commands": [ "ProvisionTenant", "RegisterReviewer", "ImportEvidencePack" ], "domain_events": [ "TenantProvisioned", "ReviewerRegistered" ], "policies": [ "No fulfillment starts until a Reviewer is registered per tenant" ], "specifications": [ "ReviewerCredentialSpec" ], "invariants": [ "Every tenant has at least one named reviewer with a valid credential on file" ], "ai_agents": [], "human_roles": [ "Onboarding lead" ], "data_owned": [ "Tenants", "Reviewer identities", "Evidence pack imports" ], "inputs": [ "Engagement", "Customer-supplied evidence pack" ], "outputs": [ "Provisioned tenant" ], "external_integrations": [ "IdP", "Google Drive / S3" ], "risks": [ "Reviewer credential expired" ], "interfaces": [ "→ Service Fulfillment" ] }, { "name": "Client Delivery & Success", "purpose": "Deliver signed artifacts, own the customer surface, drive renewal.", "subdomain": "Client Delivery & Success (supporting)", "type": "supporting", "owned_language": [ "Delivery", "Revision request", "Renewal signal" ], "owns": [ "Customer portal", "Delivery log", "Revision workflow" ], "does_not_own": [ "Signed content", "Billing" ], "primary_actors": [ "Customer operator", "Success lead" ], "entities": [ "DeliveryReceipt", "RevisionRequest" ], "value_objects": [ "Delivery method", "NPS signal" ], "aggregates": [ "DeliveryAggregate" ], "domain_services": [ "Delivery adapter" ], "application_services": [ "ConfirmDelivery", "RecordRevisionRequest" ], "commands": [ "ConfirmDelivery", "RecordRevisionRequest" ], "domain_events": [ "DeliveryConfirmed", "RevisionRequested" ], "policies": [ "Alert customer within 1h of any delivery failure" ], "specifications": [ "DeliveryAcknowledgmentSpec" ], "invariants": [ "Every DeliveryConfirmed has a linked Signoff" ], "ai_agents": [ "Success Copilot (assist only)" ], "human_roles": [ "Success lead" ], "data_owned": [ "Deliveries", "Revision requests" ], "inputs": [ "Signed artifact", "Customer feedback" ], "outputs": [ "Delivery confirmation", "Revision request" ], "external_integrations": [ "Email", "Customer portal" ], "risks": [ "Silent delivery failure" ], "interfaces": [ "← Service Fulfillment", "→ Billing" ] }, { "name": "Knowledge Base & Retrieval", "purpose": "Own per-tenant retrieval indices, source-of-truth documents, prompt library refs.", "subdomain": "Knowledge Base & Retrieval (supporting)", "type": "supporting", "owned_language": [ "Source document", "Retrieval index", "Chunk" ], "owns": [ "Source docs", "Retrieval indices", "Chunk metadata" ], "does_not_own": [ "Prompt versions", "Model calls" ], "primary_actors": [ "Knowledge ops" ], "entities": [ "SourceDoc", "IndexShard" ], "value_objects": [ "Chunk", "SourceCitation" ], "aggregates": [ "SourceDocAggregate", "IndexShardAggregate" ], "domain_services": [ "Ingestion pipeline", "Reindex service" ], "application_services": [ "IngestDoc", "Reindex", "PurgeSource" ], "commands": [ "IngestDoc", "Reindex", "PurgeSource" ], "domain_events": [ "DocIngested", "IndexRebuilt" ], "policies": [ "Retrieval indices partitioned per tenant", "Purge cascades to indices within SLA" ], "specifications": [ "TenantIsolationSpec" ], "invariants": [ "A retrieval call is always scoped to a single tenant partition" ], "ai_agents": [], "human_roles": [ "Knowledge ops" ], "data_owned": [ "Source docs", "Indices" ], "inputs": [ "Uploaded docs", "External source pulls" ], "outputs": [ "Retrieval hits with citations" ], "external_integrations": [ "Blob storage", "Search API" ], "risks": [ "Cross-tenant retrieval leak", "Stale index" ], "interfaces": [ "→ AI Orchestration" ] }, { "name": "Billing & Revenue", "purpose": "Invoicing, subscription management, dunning, revenue reporting.", "subdomain": "Billing (generic)", "type": "generic", "owned_language": [ "Invoice", "Subscription", "Usage record" ], "owns": [ "Invoices", "Subscriptions", "Usage records" ], "does_not_own": [ "Fulfillment", "Signoff" ], "primary_actors": [ "Finance", "Customer admin" ], "entities": [ "Subscription", "Invoice", "UsageRecord" ], "value_objects": [ "Line item", "Tax jurisdiction" ], "aggregates": [ "SubscriptionAggregate" ], "domain_services": [ "Billing adapter" ], "application_services": [ "ChargeSubscription", "RecordUsage" ], "commands": [ "ChargeSubscription", "RecordUsage" ], "domain_events": [ "InvoicePaid", "SubscriptionCanceled" ], "policies": [ "Meter artifact delivery for usage pricing" ], "specifications": [ "ChargeabilitySpec" ], "invariants": [ "No charge without a delivered artifact when priced per artifact" ], "ai_agents": [], "human_roles": [ "Finance" ], "data_owned": [ "Subscriptions", "Invoices" ], "inputs": [ "Delivery events" ], "outputs": [ "Invoice records" ], "external_integrations": [ "Stripe" ], "risks": [ "Tax jurisdictional errors" ], "interfaces": [ "← Client Delivery" ] }, { "name": "Identity & Access", "purpose": "SSO, MFA, RBAC, session management.", "subdomain": "Identity (generic)", "type": "generic", "owned_language": [ "User", "Role", "Session" ], "owns": [ "Users", "Roles table", "Sessions" ], "does_not_own": [ "Business capability decisions" ], "primary_actors": [ "Platform admin", "User" ], "entities": [ "User", "RoleAssignment", "Session" ], "value_objects": [ "Role", "Claim" ], "aggregates": [ "UserAggregate" ], "domain_services": [ "Auth service" ], "application_services": [ "SignIn", "AssignRole" ], "commands": [ "SignIn", "AssignRole" ], "domain_events": [ "UserSignedIn", "RoleAssigned" ], "policies": [ "Roles in a dedicated table, checked server-side" ], "specifications": [ "RoleAuthoritySpec" ], "invariants": [ "No role check runs client-only" ], "ai_agents": [], "human_roles": [ "Platform admin" ], "data_owned": [ "Users", "Roles", "Sessions" ], "inputs": [ "Auth events" ], "outputs": [ "Sessions" ], "external_integrations": [ "IdP (Google / Okta)" ], "risks": [ "Role escalation" ], "interfaces": [ "→ every other context" ] }, { "name": "Analytics & Reporting", "purpose": "Operational + business metrics, outcome reports.", "subdomain": "Analytics (supporting)", "type": "supporting", "owned_language": [ "Metric", "Dashboard", "Outcome report" ], "owns": [ "Metric definitions", "Dashboards" ], "does_not_own": [ "Raw write models" ], "primary_actors": [ "Ops lead", "Owner" ], "entities": [ "MetricDefinition", "Dashboard" ], "value_objects": [ "Window", "Target" ], "aggregates": [ "MetricDefinitionAggregate" ], "domain_services": [ "Rollup service" ], "application_services": [ "PublishMetric", "PublishDashboard" ], "commands": [ "PublishMetric", "PublishDashboard" ], "domain_events": [ "DashboardPublished" ], "policies": [ "North-star must be wired before Phase 2 launch" ], "specifications": [ "MetricDefinedSpec" ], "invariants": [ "Metrics have a definition, a target, and an owner" ], "ai_agents": [], "human_roles": [ "Ops lead" ], "data_owned": [ "Metric definitions", "Read-model rollups" ], "inputs": [ "Domain events (as read-only consumer)" ], "outputs": [ "Dashboards", "Outcome reports" ], "external_integrations": [ "BI tool" ], "risks": [ "Vanity metrics dominating" ], "interfaces": [ "← every context (read-only)" ] } ], "context_map": [ { "upstream": "Claims Intake", "downstream": "Extraction & Normalization", "pattern": "customer-supplier", "business_reason": "Extraction cannot start without a logged, hashed intake.", "data_exchanged": [ "ClaimIntake record" ], "events_exchanged": [ "ClaimIntakeReceived" ], "contract_type": "Published language (ClaimIntake record)", "failure_risks": [ "Silent format mismatch" ], "acl_notes": "Extraction consumes only fields it needs; no direct DB coupling.", "ownership_boundary": "Intake owns the raw-document lifecycle." }, { "upstream": "Extraction & Normalization", "downstream": "Insurer Rule Library", "pattern": "conformist", "business_reason": "Extraction defers to the insurer's own completeness definition.", "data_exchanged": [ "ExtractedClaimData", "InsurerRuleSet" ], "events_exchanged": [ "InsurerRuleLibraryUpdated" ], "contract_type": "Published language (InsurerRuleSet)", "failure_risks": [ "Stale rule version used" ], "acl_notes": "Rule library is the upstream source of truth; extraction never overrides it.", "ownership_boundary": "Insurer Rule Library owns completeness-checklist definitions." }, { "upstream": "Packet Assembly", "downstream": "Claims Review", "pattern": "customer-supplier", "business_reason": "No packet reaches submission without reviewer sign-off.", "data_exchanged": [ "ClaimPacket" ], "events_exchanged": [ "ClaimPacketAssembled", "ClaimPacketApproved" ], "contract_type": "Published language (ClaimPacket)", "failure_risks": [ "Packet submitted without review" ], "acl_notes": "Review context enforces the invariant structurally.", "ownership_boundary": "Claims Review owns the ReviewDecision lifecycle." }, { "upstream": "Claims Review", "downstream": "Clinical Sign-off", "pattern": "customer-supplier", "business_reason": "Clinical appeal language cannot file without DVM/credentialed-technician approval.", "data_exchanged": [ "AppealDraft" ], "events_exchanged": [ "AppealClinicalSignoffCompleted" ], "contract_type": "Published language (ClinicalSignoff)", "failure_risks": [ "Appeal filed without sign-off" ], "acl_notes": "Clinical Sign-off is a hard gate, not advisory.", "ownership_boundary": "Clinical Sign-off owns clinical-language approval." }, { "upstream": "Submission & Tracking", "downstream": "Reconciliation", "pattern": "customer-supplier", "business_reason": "Reconciliation needs a submitted, resolved claim to match against.", "data_exchanged": [ "SubmittedClaim", "EOB" ], "events_exchanged": [ "ClaimResolved", "EOBReconciled" ], "contract_type": "Published language (EOBReconciliation)", "failure_risks": [ "Payment matched to wrong invoice" ], "acl_notes": "Reconciliation reads only resolved claims.", "ownership_boundary": "Reconciliation owns the AR-ledger match." }, { "upstream": "Claims Review + Submission & Tracking", "downstream": "Exception Handling", "pattern": "customer-supplier", "business_reason": "Coverage disputes and pre-existing-condition questions must exit the automated pipeline.", "data_exchanged": [ "ExceptionCase" ], "events_exchanged": [ "ExceptionEscalated" ], "contract_type": "Published language (ExceptionCase)", "failure_risks": [ "Exception silently auto-resolved" ], "acl_notes": "Only a claims reviewer may re-route an ExceptionCase.", "ownership_boundary": "Exception Handling owns human-triage routing." }, { "upstream": "Claims Review + Clinical Sign-off + Submission & Tracking", "downstream": "Learning Loop", "pattern": "customer-supplier", "business_reason": "Every correction and format change should improve the rule library.", "data_exchanged": [ "ReviewerCorrection", "FormatChangeSignal" ], "events_exchanged": [ "InsurerRuleLibraryUpdated" ], "contract_type": "Published language (RuleLibraryRevision)", "failure_risks": [ "Correction pattern never fed back" ], "acl_notes": "Learning Loop writes only versioned revisions, never live rules directly.", "ownership_boundary": "Learning Loop owns revision proposals; Insurer Rule Library owns publication." } ], "external_integrations": [ { "system": "Vendor invoice inboxes", "risk": "Schema drift; silent field rename; rate limits", "internal_model": "field evidence record or chase notification", "acl_strategy": "Adapter in External Integrations context translates external schema → internal domain term; upstream schema never leaks past the adapter.", "owner_context": "External Integrations", "data_in": [ "External record" ], "data_out": [ "Ack or receipt" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure; dead-letter with owner-visible alert.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash (no PII in logs)." }, { "system": "HVAC work-order / CMMS platforms", "risk": "Schema drift; silent field rename; rate limits", "internal_model": "field evidence record or notification", "acl_strategy": "Adapter in External Integrations context translates external schema → internal domain term; upstream schema never leaks past the adapter.", "owner_context": "External Integrations", "data_in": [ "External record" ], "data_out": [ "Ack or receipt" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure; dead-letter with owner-visible alert.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash (no PII in logs)." }, { "system": "Customer AP / document portals", "risk": "Schema drift; silent field rename; rate limits", "internal_model": "field evidence record or notification", "acl_strategy": "Adapter in External Integrations context translates external schema → internal domain term; upstream schema never leaks past the adapter.", "owner_context": "External Integrations", "data_in": [ "External record" ], "data_out": [ "Ack or receipt" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure; dead-letter with owner-visible alert.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash (no PII in logs)." }, { "system": "OpenAI / Anthropic API", "risk": "Prompt-injection surface; token cost blowout; provider outage", "internal_model": "Draft payload with confidence score + validated schema", "acl_strategy": "OutputValidator + prompt-injection scrubber + per-tenant retrieval scope inside AI Orchestration.", "owner_context": "AI Orchestration", "data_in": [ "Prompt + retrieval context" ], "data_out": [ "Draft + confidence" ], "trigger": "api", "failure_strategy": "Exponential backoff with jitter; circuit breaker on repeated failure; dead-letter with owner-visible alert.", "audit_need": "Every call logged with tenant, request id, cost, and payload hash (no PII in logs)." } ], "event_storm": [ { "seq": 1, "command": "SubmitClaimIntake", "event": "ClaimIntakeReceived", "actor": "Practice manager / front desk", "context": "Claims Intake", "aggregate": "ClaimCase", "policy": "Reject duplicate intake for the same visit", "downstream": "Extraction begins", "risk": "Duplicate or malformed intake" }, { "seq": 2, "command": "ExtractClaimData", "event": "ClaimDataExtracted", "actor": "AI Orchestrator", "context": "Extraction & Normalization", "aggregate": "ClaimCase", "policy": "Route fields below confidence threshold to reviewer", "downstream": "Rule check", "risk": "Hallucinated field without source quote" }, { "seq": 3, "command": "CheckCompleteness", "event": "ClaimFieldFlaggedLowConfidence", "actor": "Rule engine (deterministic)", "context": "Insurer Rule Library", "aggregate": "ClaimPacket", "policy": "Block assembly on any open completeness flag", "downstream": "Assembly or reviewer triage", "risk": "Stale insurer rule version" }, { "seq": 4, "command": "AssemblePacket", "event": "ClaimPacketAssembled", "actor": "AI Orchestrator", "context": "Packet Assembly", "aggregate": "ClaimPacket", "policy": "Flag any missing required field rather than guess", "downstream": "Claims-reviewer review", "risk": "Assembly proceeds with an unresolved gap" }, { "seq": 5, "command": "ReviewPacket", "event": "ClaimPacketReviewed", "actor": "Claims reviewer", "context": "Claims Review", "aggregate": "ClaimPacket", "policy": "100% review in first 90 days", "downstream": "Approval or correction", "risk": "Reviewer bottleneck delays submission past 24h" }, { "seq": 6, "command": "ApprovePacket", "event": "ClaimPacketApproved", "actor": "Claims reviewer", "context": "Claims Review", "aggregate": "ClaimCase", "policy": "No submission without an approved ReviewDecision", "downstream": "Submission", "risk": "Approval bypass" }, { "seq": 7, "command": "SubmitClaim", "event": "ClaimSubmitted", "actor": "Claims reviewer", "context": "Submission & Tracking", "aggregate": "ClaimCase", "policy": "Requires an active ClaimsAuthorization on file", "downstream": "Status tracking", "risk": "Expired or missing authorization" }, { "seq": 8, "command": "MonitorClaimStatus", "event": "ClaimStatusUpdated", "actor": "AI (status monitor)", "context": "Submission & Tracking", "aggregate": "ClaimCase", "policy": "Flag claims pending beyond the insurer's typical window", "downstream": "Proactive follow-up or appeal", "risk": "Silent delivery failure" }, { "seq": 9, "command": "RequestAppealSignoff", "event": "AppealClinicalSignoffCompleted", "actor": "DVM / credentialed technician", "context": "Clinical Sign-off", "aggregate": "AppealCase", "policy": "Clinical language cannot file without this event", "downstream": "Appeal filing", "risk": "Overstated clinical claim" }, { "seq": 10, "command": "SubmitAppeal", "event": "AppealFiled", "actor": "Claims reviewer", "context": "Submission & Tracking", "aggregate": "AppealCase", "policy": "Requires ClinicalSignoff if clinical language present", "downstream": "Resolution", "risk": "Filed without required sign-off" }, { "seq": 11, "command": "ReconcileEOB", "event": "EOBReconciled", "actor": "AI (reconciliation)", "context": "Reconciliation", "aggregate": "EOBReconciliation", "policy": "Cannot close a ClaimCase without a reconciled or written-off EOB", "downstream": "Claim closed", "risk": "Payment matched to the wrong invoice" }, { "seq": 12, "command": "EscalateException", "event": "ExceptionEscalated", "actor": "Claims reviewer", "context": "Exception Handling", "aggregate": "ExceptionCase", "policy": "Only a claims reviewer may re-route an exception", "downstream": "Practice-level escalation", "risk": "Misclassified exception auto-resolves" }, { "seq": 13, "command": "UpdateRuleLibrary", "event": "InsurerRuleLibraryUpdated", "actor": "Claims operations lead", "context": "Learning Loop", "aggregate": "InsurerRuleSet", "policy": "Freeze new submissions for that insurer until re-validated", "downstream": "Extraction & Packet Assembly resume", "risk": "Rule published without validation against a real claim" } ], "critical_path": [ "ClaimIntakeReceived → ClaimDataExtracted → ClaimPacketAssembled → ClaimPacketApproved → ClaimSubmitted → EOBReconciled" ], "exception_flows": [ "DraftProduced with low confidence → EscalationRaised → reviewer manual draft → ArtifactSigned", "DeliverArtifact blocked by open owner action → DeliveryBlocked → owner resolves → retry", "DeliveryFailed at adapter → customer alert within 1h → Success ticket → retry with backoff" ], "escalation_flows": [ "AI Orchestration escalates to Reviewer", "Reviewer escalates ambiguous artifact to Legal", "Success lead escalates silent delivery failure to Owner", "Owner escalates regulator inquiry to external counsel" ], "retry_flows": [ "External API failure → exponential backoff with jitter, then dead-letter with owner-visible alert", "Model timeout → retry once, then EscalationRaised", "Delivery adapter failure → retry with backoff, then customer alert" ], "manual_override_flows": [ "Reviewer may override AI classification and re-route", "Owner may force-block a delivery via Compliance ledger", "Ops may pull a prompt version at any time (feature flag)" ], "commands": [ { "name": "SubmitClaimIntake", "issued_by": "Practice manager / front desk", "preconditions": [ "Practice onboarded", "Claims authorization on file" ], "aggregate": "ClaimCase", "success_event": "ClaimIntakeReceived", "failure_event": "IntakeRejected", "authorization": "Practice member with Operator role", "validation": "Medical-record export + invoice present; no duplicate open intake for the visit", "audit": "Command + payload hash logged with practice + user" }, { "name": "ExtractClaimData", "issued_by": "AI Orchestrator", "preconditions": [ "Intake received" ], "aggregate": "ClaimCase", "success_event": "ClaimDataExtracted", "failure_event": "ExtractionFailed", "authorization": "System", "validation": "Every extracted field carries a source quote and confidence score", "audit": "AgentRun logged with prompt version + confidence scores" }, { "name": "AssemblePacket", "issued_by": "AI Orchestrator", "preconditions": [ "Completeness check run" ], "aggregate": "ClaimPacket", "success_event": "ClaimPacketAssembled", "failure_event": "AssemblyBlocked", "authorization": "System", "validation": "No field marked present without a source quote", "audit": "Packet records InsurerRuleSet version used" }, { "name": "ReviewPacket", "issued_by": "Claims reviewer", "preconditions": [ "Packet assembled" ], "aggregate": "ClaimPacket", "success_event": "ClaimPacketReviewed", "failure_event": "ClaimPacketReturnedForCorrection", "authorization": "Registered claims reviewer", "validation": "Checklist item-by-item confirmation against source data", "audit": "Reviewer ID + checklist result logged" }, { "name": "SubmitClaim", "issued_by": "Claims reviewer", "preconditions": [ "Packet approved", "Claims authorization active" ], "aggregate": "ClaimCase", "success_event": "ClaimSubmitted", "failure_event": "SubmissionBlocked", "authorization": "Registered claims reviewer", "validation": "Authorization not expired/revoked", "audit": "Submission timestamp + reviewer ID logged" }, { "name": "RequestAppealSignoff", "issued_by": "Claims reviewer", "preconditions": [ "Appeal drafted", "Contains clinical language" ], "aggregate": "AppealCase", "success_event": "AppealClinicalSignoffCompleted", "failure_event": "SignoffDeclined", "authorization": "DVM or credentialed veterinary technician", "validation": "Clinical language matches verbatim chart facts only", "audit": "Clinician review timestamp logged" }, { "name": "ReconcileEOB", "issued_by": "AI (reconciliation)", "preconditions": [ "Claim resolved" ], "aggregate": "EOBReconciliation", "success_event": "EOBReconciled", "failure_event": "ReconciliationMismatch", "authorization": "System", "validation": "Payment amount matched to invoice line items", "audit": "Reconciliation record logged to practice AR ledger" } ], "policies": [ { "name": "Route low-confidence field to reviewer triage", "trigger": "ClaimDataExtracted", "condition": "Any field confidence < 0.70", "action": "Route to reviewer triage before assembly", "context": "Extraction & Normalization", "ai_involvement": "author", "human_approval": false }, { "name": "Draft appeal on denial-for-incompleteness", "trigger": "ClaimDeniedForIncompleteness", "condition": "Denial reason cites missing documentation", "action": "Enqueue appeal drafting grounded in existing chart data", "context": "Packet Assembly", "ai_involvement": "author", "human_approval": false }, { "name": "Escalate pending-past-window claims", "trigger": "ClaimStatusUpdated", "condition": "Days pending exceeds insurer's typical window", "action": "Open a proactive follow-up inquiry with the insurer", "context": "Submission & Tracking", "ai_involvement": "assist", "human_approval": false }, { "name": "Block submission on open completeness flag", "trigger": "ClaimPacketAssembled", "condition": "Any completeness_checklist item open", "action": "Reject transition to ReadyForSubmission", "context": "Packet Assembly", "ai_involvement": "none", "human_approval": false }, { "name": "Freeze insurer on format-change signal", "trigger": "InsurerRuleLibraryUpdated", "condition": "Rule version bump for an insurer with in-flight claims", "action": "Pause new submissions for that insurer until re-validated", "context": "Learning Loop", "ai_involvement": "assist", "human_approval": true } ], "aggregates": [ { "name": "ClaimCase", "root": "ClaimCase", "context": "Claims Fulfillment", "purpose": "Guard intake, authorization, review, submission, and resolution state transitions for one insured-client-visit claim.", "entities": [ "ClaimCase", "ClaimPacket", "ClaimsAuthorization" ], "value_objects": [ "ConfidenceScore", "SourceQuote", "DaysPending" ], "invariants": [ "Cannot transition to Submitted without an approved ReviewDecision and an active ClaimsAuthorization", "Cannot close without a reconciled or explicitly written-off EOBReconciliation" ], "commands": [ "SubmitClaimIntake", "ExtractClaimData", "SubmitClaim" ], "events": [ "ClaimIntakeReceived", "ClaimDataExtracted", "ClaimSubmitted", "ClaimResolved" ], "repository": "ClaimCaseRepository", "transaction_boundary": "single ClaimCase per transaction" }, { "name": "ClaimPacket", "root": "ClaimPacket", "context": "Packet Assembly", "purpose": "The assembled submission bundle for one ClaimCase.", "entities": [ "ClaimPacket", "CompletenessChecklistItem" ], "value_objects": [ "FieldValue", "SourceQuote" ], "invariants": [ "Cannot mark ReadyForSubmission while any completeness_checklist item is open" ], "commands": [ "AssemblePacket", "ReviewPacket" ], "events": [ "ClaimPacketAssembled", "ClaimPacketApproved" ], "repository": "ClaimPacketRepository", "transaction_boundary": "single ClaimPacket per transaction" }, { "name": "InsurerRuleSet", "root": "InsurerRuleSet", "context": "Insurer Rule Library", "purpose": "Versioned, per-insurer completeness rules.", "entities": [ "InsurerRuleSet" ], "value_objects": [ "RuleVersion" ], "invariants": [ "Every ClaimPacket records which InsurerRuleSet version it was assembled against" ], "commands": [ "UpdateRuleLibrary" ], "events": [ "InsurerRuleLibraryUpdated" ], "repository": "InsurerRuleSetRepository", "transaction_boundary": "single InsurerRuleSet per transaction" }, { "name": "ClaimsAuthorization", "root": "ClaimsAuthorization", "context": "Claims Fulfillment", "purpose": "The pet owner's signed processing-agent authorization.", "entities": [ "ClaimsAuthorization" ], "value_objects": [ "AuthorizationStatus" ], "invariants": [ "Exactly one active authorization per client per claim; expired or revoked authorizations block new submissions" ], "commands": [ "SubmitClaim" ], "events": [ "ClaimSubmitted" ], "repository": "ClaimsAuthorizationRepository", "transaction_boundary": "single ClaimsAuthorization per transaction" }, { "name": "AppealCase", "root": "AppealCase", "context": "Clinical Sign-off", "purpose": "One per denial or additional-documentation request.", "entities": [ "AppealCase", "ClinicalSignoff" ], "value_objects": [ "AppealLanguageDraft" ], "invariants": [ "Cannot reach Filed status while containing clinical medical-necessity language without a recorded ClinicalSignoff" ], "commands": [ "RequestAppealSignoff" ], "events": [ "AppealClinicalSignoffCompleted", "AppealFiled" ], "repository": "AppealCaseRepository", "transaction_boundary": "single AppealCase per transaction" }, { "name": "EOBReconciliation", "root": "EOBReconciliation", "context": "Reconciliation", "purpose": "The resolution record tying an insurer's payment to the practice's invoice.", "entities": [ "EOBReconciliation" ], "value_objects": [ "ReconciledAmount" ], "invariants": [ "Cannot close a ClaimCase without a reconciled or explicitly-written-off EOBReconciliation" ], "commands": [ "ReconcileEOB" ], "events": [ "EOBReconciled" ], "repository": "EOBReconciliationRepository", "transaction_boundary": "single EOBReconciliation per transaction" }, { "name": "ExceptionCase", "root": "ExceptionCase", "context": "Exception Handling", "purpose": "A claim routed to human triage.", "entities": [ "ExceptionCase" ], "value_objects": [ "ExceptionReason" ], "invariants": [ "Cannot auto-resolve back into the automated pipeline; only a claims reviewer can re-route it" ], "commands": [ "EscalateException" ], "events": [ "ExceptionEscalated" ], "repository": "ExceptionCaseRepository", "transaction_boundary": "single ExceptionCase per transaction" }, { "name": "PracticeAccount", "root": "PracticeAccount", "context": "Claims Intake", "purpose": "The onboarded practice tenant and its intake/notification preferences.", "entities": [ "PracticeAccount" ], "value_objects": [ "ClaimableVisitThreshold" ], "invariants": [ "A ClaimCase cannot be created for a practice without an active PracticeAccount" ], "commands": [ "SubmitClaimIntake" ], "events": [ "ClaimIntakeReceived" ], "repository": "PracticeAccountRepository", "transaction_boundary": "single PracticeAccount per transaction" } ], "invariants": [ { "invariant": "A ClaimCase cannot transition to Submitted without an approved ReviewDecision and an active ClaimsAuthorization.", "context": "Claims Fulfillment ↔ Claims Review", "aggregate": "ClaimCase", "why": "No claim ever leaves without both human release and client consent on file.", "enforcement": "Aggregate command handler rejects SubmitClaim without both references" }, { "invariant": "A ClaimPacket cannot be marked ReadyForSubmission while any completeness_checklist item is open.", "context": "Packet Assembly", "aggregate": "ClaimPacket", "why": "Prevents claims from being submitted incomplete and bouncing back.", "enforcement": "Deterministic completeness-check gate on the assembly command handler" }, { "invariant": "An AppealCase containing clinical medical-necessity language cannot reach Filed status without a recorded ClinicalSignoff.", "context": "Clinical Sign-off", "aggregate": "AppealCase", "why": "Protects the practice's clinical credibility; keeps ClaimTail out of clinical judgment.", "enforcement": "Command handler blocks SubmitAppeal without a ClinicalSignoff reference when clinical language is flagged" }, { "invariant": "No ClaimCase, ClaimPacket, or AppealCase state transition that constitutes a coverage determination or payment authorization is ever performed by ClaimTail.", "context": "cross-cutting", "aggregate": "all", "why": "Keeps ClaimTail structurally on the ministerial side of the adjuster/TPA licensing line.", "enforcement": "No 'coverage decision' state exists anywhere in the domain model" }, { "invariant": "Every ClaimPacket records which InsurerRuleSet version it was assembled against.", "context": "Packet Assembly ↔ Insurer Rule Library", "aggregate": "ClaimPacket", "why": "Audit-trail requirement; supports reconstruction if an insurer disputes the submission.", "enforcement": "Assembly command handler requires a rule-version reference" }, { "invariant": "A ClaimCase cannot close without a reconciled or explicitly written-off EOBReconciliation.", "context": "Reconciliation", "aggregate": "ClaimCase / EOBReconciliation", "why": "Prevents claims from silently disappearing before resolution is recorded.", "enforcement": "Close command handler requires an EOBReconciliation reference" }, { "invariant": "An ExceptionCase cannot auto-resolve back into the automated pipeline.", "context": "Exception Handling", "aggregate": "ExceptionCase", "why": "Coverage disputes and pre-existing-condition judgment always require human triage.", "enforcement": "Only a claims-reviewer-issued command may transition an ExceptionCase" }, { "invariant": "Exactly one active ClaimsAuthorization exists per client per claim.", "context": "Claims Fulfillment", "aggregate": "ClaimsAuthorization", "why": "Prevents submission under an expired or ambiguous authorization.", "enforcement": "Aggregate enforces single-active-authorization constraint" }, { "invariant": "100% of Claim Submission Packs are reviewed by a claims reviewer in the first 90 days regardless of AI confidence score.", "context": "Claims Review", "aggregate": "ClaimPacket", "why": "No packet has yet earned spot-check-only trust.", "enforcement": "Policy gate on ReviewPacket, time-boxed to 90 days post-launch per insurer" } ], "ai_agents": [ { "name": "Extraction Agent", "context": "Extraction & Normalization", "responsibility": "Extract diagnosis, procedures, itemized charges, and dates from the medical-record export and invoice into the canonical claim schema.", "inputs": [ "Medical-record export", "Itemized invoice" ], "outputs": [ "Structured field values", "Source quotes", "Confidence scores" ], "tools": [ "Retrieval API", "Structured-output validator" ], "forbidden_actions": [ "Infer a field not explicitly present in the source text", "Access another practice's data", "Emit output without a source quote per field" ], "memory_scope": "Per-run only; no cross-run memory; prompt-injection scrubber on all practice inputs.", "retrieval_sources": [ "Practice-scoped knowledge base", "Insurer Rule Library (read-only per-insurer)" ], "validations": [ "Structured-output schema", "Source-quote-per-field rule", "PII-scrub rule on prompt inputs" ], "confidence_scoring": "Model-reported logprobs + source-quote coverage combined into a bounded [0..1] score per field.", "escalation_triggers": [ "Score < 0.70", "Ambiguous insurer match", "Missing source quote on any claimed field" ], "human_approval": true, "failure_modes": [ "Prompt injection via invoice/chart content", "Hallucinated field without source", "Cross-practice retrieval leak" ], "audit_logs": [ "Prompt version", "Retrieval hits (ids only)", "Cost + latency", "Validator verdict" ], "metrics": [ "Extraction acceptance rate", "Escalation rate", "Cost per claim", "p95 latency" ], "versioning": "Prompt versions immutable; published via PromptRegistryAggregate; rollout via feature flag." }, { "name": "Assembly & Drafting Agent", "context": "Packet Assembly", "responsibility": "Assemble the claim packet against the applicable InsurerRuleSet and draft appeal language grounded in extracted chart data.", "inputs": [ "ExtractedClaimData", "InsurerRuleSet" ], "outputs": [ "ClaimPacket draft", "Completeness checklist pass/fail", "AppealDraft (conditional)" ], "tools": [ "Retrieval API", "Structured-output validator", "PDF templating" ], "forbidden_actions": [ "Mark a field present without a source_quote", "Characterize a diagnosis or treatment rationale beyond what's verbatim in the chart", "Compute days-pending or window-remaining figures (deterministic code only)" ], "memory_scope": "Per-run only; no cross-run memory; prompt-injection scrubber on all practice inputs.", "retrieval_sources": [ "Practice-scoped knowledge base", "Insurer Rule Library (read-only per-insurer)" ], "validations": [ "Structured-output schema", "Source-quote-per-field rule", "PII-scrub rule on prompt inputs" ], "confidence_scoring": "Model-reported logprobs + source-quote coverage combined into a bounded [0..1] score per field.", "escalation_triggers": [ "Score < 0.70", "Ambiguous insurer match", "Missing source quote on any claimed field" ], "human_approval": true, "failure_modes": [ "Prompt injection via invoice/chart content", "Hallucinated field without source", "Cross-practice retrieval leak" ], "audit_logs": [ "Prompt version", "Retrieval hits (ids only)", "Cost + latency", "Validator verdict" ], "metrics": [ "Extraction acceptance rate", "Escalation rate", "Cost per claim", "p95 latency" ], "versioning": "Prompt versions immutable; published via PromptRegistryAggregate; rollout via feature flag." }, { "name": "Status Monitor Agent", "context": "Submission & Tracking", "responsibility": "Monitor claim status and flag claims pending beyond the insurer's typical processing window.", "inputs": [ "SubmittedClaim records", "Insurer typical-window benchmarks" ], "outputs": [ "ClaimStatusUpdated events", "Follow-up flags" ], "tools": [ "Status tracker API" ], "forbidden_actions": [ "Contact the insurer without a logged follow-up record", "Suppress a pending-past-window flag" ], "memory_scope": "Per-run only; no cross-run memory; prompt-injection scrubber on all practice inputs.", "retrieval_sources": [ "Practice-scoped knowledge base", "Insurer Rule Library (read-only per-insurer)" ], "validations": [ "Structured-output schema", "Source-quote-per-field rule", "PII-scrub rule on prompt inputs" ], "confidence_scoring": "Model-reported logprobs + source-quote coverage combined into a bounded [0..1] score per field.", "escalation_triggers": [ "Score < 0.70", "Ambiguous insurer match", "Missing source quote on any claimed field" ], "human_approval": true, "failure_modes": [ "Prompt injection via invoice/chart content", "Hallucinated field without source", "Cross-practice retrieval leak" ], "audit_logs": [ "Prompt version", "Retrieval hits (ids only)", "Cost + latency", "Validator verdict" ], "metrics": [ "Extraction acceptance rate", "Escalation rate", "Cost per claim", "p95 latency" ], "versioning": "Prompt versions immutable; published via PromptRegistryAggregate; rollout via feature flag." } ], "prompt_chain_map": [ "Intake → Classifier (route + insurer category) → Drafter (cite + draft) → OutputValidator → Reviewer (approve or escalate)", "Retraction analysis → Evaluator (assist only) → Legal + Reviewer co-sign" ], "rag_map": [ "Per-tenant knowledge base partition → retrieval router → tenant-scoped hits → Drafter", "Public regulator sources (read-only cache) → shared retrieval → Drafter (cited)" ], "ai_evaluation": [ "Golden dataset of past reviewer-accepted artifacts per vertical", "Regression thresholds on acceptance rate + citation coverage", "Every prompt release requires a passing Evaluator run" ], "hallucination_controls": [ "Retrieval-first (no free-form generation without citation)", "Structured-output validator enforces citation-per-claim", "Confidence-scored escalation", "Reviewer gate on all outbound artifacts" ], "human_in_the_loop_plan": [ "Reviewer signoff on every outbound artifact", "Legal co-sign on retractions", "Owner approval on public-release readiness", "Ops sign-off on prompt-version rollout" ], "ai_audit_plan": [ "Every AgentRun logged with prompt version, retrieval hit ids, cost, latency, validator verdict", "13-month rolling retention on run logs", "PII scrubbed from log payloads" ], "prompt_versioning": "Prompt versions immutable once published; rolled out via feature flag; every rollout paired with an Evaluator run.", "human_roles": [ { "role": "Claims reviewer", "responsibilities": [ "Approve / return every Claim Submission Pack before submission", "Sign every submitted claim" ], "contexts": [ "Claims Review", "Claims Fulfillment" ], "decisions_owned": [ "Approval", "Return-for-correction", "Exception routing" ], "ai_support": [ "Cited extractions", "Confidence-ranked fields" ], "approval_authority": "Full packet release", "escalation_authority": "Escalate to practice manager", "quality_metrics": [ "Cycle time to release", "Rejection-for-incompleteness rate" ], "workload_risks": [ "Single-reviewer bottleneck at volume" ] }, { "role": "DVM / credentialed veterinary technician", "responsibilities": [ "Review and sign off on clinical medical-necessity appeal language" ], "contexts": [ "Clinical Sign-off" ], "decisions_owned": [ "Clinical-language approval or rejection" ], "ai_support": [ "Chart-grounded draft language" ], "approval_authority": "Clinical-language sign-off only", "escalation_authority": "Decline and return for redraft", "quality_metrics": [ "Sign-off cycle time", "Overturned-appeal rate" ], "workload_risks": [ "Delay when unavailable near an appeal deadline" ] }, { "role": "Practice manager / hospital administrator", "responsibilities": [ "Resolve exception-queue escalations", "Confirm practice-level facts (thresholds, insurer list)" ], "contexts": [ "Exception Handling", "Claims Intake" ], "decisions_owned": [ "Coverage-dispute guidance to ClaimTail", "Practice onboarding facts" ], "ai_support": [ "Exception summaries" ], "approval_authority": "Practice-level policy decisions", "escalation_authority": "Final internal escalation point", "quality_metrics": [ "Exception resolution time" ], "workload_risks": [ "Delayed response stalling an exception claim" ] } ], "human_review_checkpoints": [ "AI draft → reviewer approval", "Public release → owner acceptance", "Retraction → legal + reviewer co-sign", "Prompt rollout → ops + evaluator" ], "escalation_matrix": [ "AI → Reviewer → Legal → Owner → External counsel", "Success → Owner → External counsel (regulator inquiries)" ], "manual_override_rules": [ "Any manual override captured as an explicit override event with actor + reason", "No override may bypass a reviewer signoff invariant" ], "separation_of_duties": [ "Drafter Agent cannot sign; Reviewer cannot draft on behalf of AI without an override event; Legal cannot silently retract" ], "quality_control_workflow": [ "Weekly reviewer calibration meeting", "Monthly evaluator regression report", "Quarterly retraction-rate review with owner + legal" ], "data_objects": [ { "name": "service event", "meaning": "Unit of work brought in by customer", "owner_context": "Service Fulfillment", "writers": [ "Service Fulfillment" ], "readers": [ "QA", "Analytics" ], "source_of_truth": "Service Fulfillment DB", "retention": "3 years + 6 months (the completeness checklist retention + buffer)", "privacy": "confidential", "audit": true }, { "name": "field evidence", "meaning": "Cited fact backing a claim", "owner_context": "Service Fulfillment", "writers": [ "Service Fulfillment" ], "readers": [ "QA", "Analytics" ], "source_of_truth": "Service Fulfillment DB + Knowledge Base pointers", "retention": "3 years + 6 months", "privacy": "confidential", "audit": true }, { "name": "Claim Submission Pack", "meaning": "Reviewer-signed deliverable", "owner_context": "Service Fulfillment", "writers": [ "Service Fulfillment" ], "readers": [ "QA", "Client Delivery", "Analytics" ], "source_of_truth": "Service Fulfillment DB (immutable after signoff)", "retention": "3 years + 6 months (mirrors the the completeness checklist 3-year duty + buffer)", "privacy": "regulated", "audit": true }, { "name": "Signoff", "meaning": "Reviewer signature manifest", "owner_context": "Quality Assurance", "writers": [ "Quality Assurance" ], "readers": [ "Service Fulfillment", "Analytics" ], "source_of_truth": "QA DB (append-only)", "retention": "3 years + 6 months", "privacy": "confidential", "audit": true }, { "name": "OwnerActionLedger", "meaning": "Blocker facts per tenant", "owner_context": "Compliance & Governance", "writers": [ "Compliance & Governance" ], "readers": [ "Service Fulfillment (release decision)", "Analytics" ], "source_of_truth": "Compliance DB", "retention": "3 years + 6 months", "privacy": "internal", "audit": true }, { "name": "AgentRun", "meaning": "Trace of one AI orchestrator run", "owner_context": "AI Orchestration", "writers": [ "AI Orchestration" ], "readers": [ "Analytics", "QA (on escalation)" ], "source_of_truth": "AI Orchestration DB", "retention": "13 months (rolling)", "privacy": "internal", "audit": true }, { "name": "Tenant", "meaning": "Customer organization + reviewers", "owner_context": "Client Onboarding & Profile", "writers": [ "Client Onboarding & Profile" ], "readers": [ "all contexts" ], "source_of_truth": "Onboarding DB", "retention": "Life of contract + 3.5 years", "privacy": "confidential", "audit": true }, { "name": "Subscription + Invoice", "meaning": "Commercial relationship + charges", "owner_context": "Billing & Revenue", "writers": [ "Billing" ], "readers": [ "Analytics" ], "source_of_truth": "Billing provider (Stripe)", "retention": "As required by tax law", "privacy": "confidential", "audit": true }, { "name": "User + Role", "meaning": "Identity + authorization", "owner_context": "Identity & Access", "writers": [ "Identity & Access" ], "readers": [ "all contexts" ], "source_of_truth": "Identity DB", "retention": "Life of account + 2 years", "privacy": "confidential", "audit": true } ], "read_models": [ "OperatorDashboard read model (per tenant): open intakes, in-review, delivered this week", "ReviewerQueue read model: cases awaiting reviewer with confidence + escalation reason", "ComplianceLedger read model: open owner actions + release-decision", "AnalyticsRollup read model: metric definitions rolled up daily" ], "reporting_models": [ "Outcome report per customer: artifacts delivered, cycle time, acceptance rate, retractions", "Ops report: AI cost per artifact, escalation rate, reviewer load" ], "data_duplication_notes": [ "Reviewer identity is stored in Onboarding, referenced by QA — QA does not own it", "OwnerActionLedger duplicates minimal facts into read models for Fulfillment consumption" ], "data_retention": [ "Artifacts + evidence + signoffs: 3 years + 6 months (mirrors the the completeness checklist 3-year duty + buffer)", "AgentRun logs: 13 months rolling", "Users + sessions: life of account + 2 years" ], "data_quality_risks": [ "Silent schema drift from external systems", "Stale retrieval indices after source-doc updates", "Missing retraction cross-links after legacy import" ], "use_cases": [ { "name": "Deliver a claims-reviewer-signed Claim Submission Pack", "actor": "Customer operator + Reviewer", "context": "Service Fulfillment + Quality Assurance + AI Orchestration", "goal": "Produce and submit a claims-reviewer-signed Claim Submission Pack", "preconditions": [ "Tenant provisioned", "Reviewer registered", "Engagement accepted" ], "main_flow": [ "Operator opens service event", "Evidence attached / retrieved", "AI Orchestrator drafts with citations", "Reviewer approves", "Delivery adapter delivers", "Success lead confirms delivery" ], "alternative_flows": [ "Confidence below threshold → EscalationRaised → reviewer drafts manually", "Blocking owner action open → DeliveryBlocked → surfaced to owner", "Delivery failure → alert customer within 1h" ], "business_rules": [ "Every claim must cite evidence", "Only registered reviewer may sign" ], "ai_role": "Draft + validate + score confidence", "human_role": "Sign; escalate; retract", "commands": [ "OpenIntake", "AttachEvidence", "StartAgentRun", "ApproveArtifact", "DeliverClaimPacket" ], "events": [ "ServiceEventAccepted", "EvidenceCollected", "DraftProduced", "ArtifactSigned", "ArtifactDelivered" ], "aggregates": [ "ServiceEventAggregate", "AgentRunAggregate", "SignoffAggregate", "ClaimPacketAggregate" ], "success": "Claim Submission Pack submitted + claims-reviewer signed + audit trail complete", "failure_handling": "EscalationRaised → reviewer queue; DeliveryFailed → customer alert + Success ticket", "audit": "Full command → event chain with actor + timestamp per step" }, { "name": "Retract a delivered artifact", "actor": "Legal + credentialed-technician reviewer", "context": "Quality Assurance + Compliance & Governance", "goal": "Formally withdraw / correct a delivered artifact", "preconditions": [ "Artifact previously delivered", "Material finding documented" ], "main_flow": [ "Finding documented", "Legal + Reviewer co-sign retraction", "Customer notified", "Audit-log append" ], "alternative_flows": [ "Reviewer disagrees → escalate to owner", "Regulator inquiry incoming → run in parallel with legal-response workflow" ], "business_rules": [ "Retraction requires Legal + Reviewer co-sign" ], "ai_role": "Surface prior similar cases (assist only)", "human_role": "Co-sign + notify", "commands": [ "FileRetraction" ], "events": [ "RetractionFiled" ], "aggregates": [ "RetractionAggregate", "OwnerActionLedgerAggregate" ], "success": "Retraction filed + customer notified + audit trail updated", "failure_handling": "Rejection path emits RetractionRejected + escalates to owner", "audit": "Full retraction packet archived, immutable" }, { "name": "Resolve an owner action and flip release decision", "actor": "Business owner", "context": "Compliance & Governance", "goal": "Close a blocking owner action and recompute release readiness", "preconditions": [ "Owner action open" ], "main_flow": [ "Owner supplies fact", "Ledger updated", "ReleaseDecision recomputed", "Downstream contexts notified" ], "alternative_flows": [ "Fact rejected → OwnerActionRejected", "Legal review required → route to legal" ], "business_rules": [ "Release cannot flip to ready with any blocking action open" ], "ai_role": "Blocker digest", "human_role": "Supply fact + accept release", "commands": [ "ResolveOwnerAction" ], "events": [ "OwnerActionResolved", "ReleaseDecisionChanged" ], "aggregates": [ "OwnerActionLedgerAggregate" ], "success": "Release decision flips or stays with clear reason", "failure_handling": "OwnerActionRejected + retry loop", "audit": "Actor + before/after + timestamp" } ], "architecture": { "style": "modular-monolith-event-driven", "why": "Single team + single regulated vertical per blueprint + strong consistency requirements around signoff / delivery / release-decision favor a monolith. Event-driven internals give us the audit-friendly append-only log without the operational cost of microservices.", "rejected_alternatives": [ "Microservices — no independent scaling or team boundary justifies distributed cost yet.", "Serverless-workflow-only — reviewer signoff and audit invariants are easier to keep correct in a monolith.", "No-code / low-code — cannot enforce OutputValidator, prompt versioning, or per-tenant retrieval isolation with fidelity." ], "backend_modules": [ "Service Fulfillment", "AI Orchestration", "Quality Assurance", "Compliance & Governance", "Sales & Intake", "Client Onboarding & Profile", "Client Delivery & Success", "Knowledge Base & Retrieval", "Analytics & Reporting" ], "frontend_modules": [ "Operator dashboard", "Reviewer console", "Client portal", "Owner console", "Ops (prompt registry) console" ], "api_boundaries": [ "/intake/*", "/artifacts/*", "/reviewer/*", "/compliance/*", "/knowledge/*", "/admin/*" ], "database_strategy": "One managed Postgres; schema-per-context; cross-context reads via published projections; RLS on protected tables.", "event_bus": "In-process event dispatcher backed by an outbox table (transactional publish); upgrade path to a real broker if throughput demands.", "queue": "Background job queue (managed) for AI runs, delivery adapters, and reindex jobs.", "workflow_engine": "None initially — orchestrate via domain events + policies; add a workflow engine if orchestrations exceed 5 sequential steps.", "ai_orchestration": "AI Orchestration context owns bounded agents; OutputValidator + prompt registry + tenant-scoped retrieval; retries with backoff.", "rag_layer": "Per-tenant partitioned retrieval indices in a managed vector DB; ingestion pipeline in Knowledge Base context.", "file_storage": "Managed blob storage with per-tenant prefixes + signed URLs; artifacts hashed on write.", "authn_authz": "IdP (Google / Okta) for authn; RBAC via dedicated roles table with server-side checks + RLS.", "admin_dashboard": "Ops-facing admin for tenants, users, feature flags, prompt versions.", "client_portal": "Customer-facing portal: submit intake, see status, receive artifacts.", "operator_dashboard": "Internal: intake queue, reviewer queue, escalation queue, delivery health.", "observability": "Structured logs with tenant + request ids; RED metrics per workflow; error tracking with source maps; model-call spans with cost + latency; SLO review weekly.", "audit_logging": "Append-only audit log for all state transitions; hash-chained snapshots on signed artifacts.", "deployment": "Single production region + multi-AZ managed DB; per-PR preview deploys; migrations gated on review." }, "module_structure": { "tree": "/src\n /contexts\n /sales-intake\n /domain\n /application\n /infrastructure\n /interfaces\n /client-onboarding\n /domain\n /application\n /infrastructure\n /interfaces\n /service-fulfillment\n /domain\n /application\n /infrastructure\n /interfaces\n /ai-orchestration\n /domain\n /application\n /infrastructure\n /interfaces\n /quality-assurance\n /domain\n /application\n /infrastructure\n /interfaces\n /compliance-governance\n /domain\n /application\n /infrastructure\n /interfaces\n /client-delivery\n /domain\n /application\n /infrastructure\n /interfaces\n /knowledge-base\n /domain\n /application\n /infrastructure\n /interfaces\n /analytics\n /domain\n /application\n /infrastructure\n /interfaces\n /shared\n /kernel # tiny — Ids, Money, Tenant, Actor\n /events # published-language event contracts\n /auth # session + role primitives\n /observability # logging, metrics, tracing\n /config", "modules": [ { "name": "service-fulfillment", "purpose": "ServiceEvent → Claim Submission Pack lifecycle", "owned_domain": [ "ServiceEvent", "Draft", "Claim Submission Pack", "Delivery" ], "application_services": [ "OpenIntake", "AttachEvidence", "SubmitForSignoff", "DeliverClaimPacket" ], "infra_adapters": [ "Delivery adapter", "Outbox publisher" ], "public_interfaces": [ "/intake/*", "/artifacts/*" ], "forbidden_deps": [ "billing infra", "identity provider internals" ] }, { "name": "ai-orchestration", "purpose": "Bounded AI agents", "owned_domain": [ "AgentRun", "PromptVersion" ], "application_services": [ "StartAgentRun", "PublishPromptVersion" ], "infra_adapters": [ "OpenAI/Anthropic client", "Retrieval router" ], "public_interfaces": [ "internal" ], "forbidden_deps": [ "cross-tenant retrieval", "direct delivery" ] }, { "name": "quality-assurance", "purpose": "Signoff + retraction", "owned_domain": [ "Signoff", "Retraction" ], "application_services": [ "ApproveArtifact", "FileRetraction" ], "infra_adapters": [ "Signature service" ], "public_interfaces": [ "/reviewer/*" ], "forbidden_deps": [ "draft content mutation" ] }, { "name": "compliance-governance", "purpose": "Owner-action ledger + release decision", "owned_domain": [ "OwnerActionLedger", "ReleaseDecision", "DSARRequest" ], "application_services": [ "ResolveOwnerAction", "ProcessDSAR" ], "infra_adapters": [ "Email adapter" ], "public_interfaces": [ "/compliance/*" ], "forbidden_deps": [ "draft content" ] } ], "dependency_rules": [ "Domain layer must not depend on infrastructure.", "Application layer may depend on domain.", "Infrastructure implements ports defined by application/domain.", "Interfaces call application services.", "Shared kernel must remain small (Ids, Money, Tenant, Actor).", "Contexts communicate through published events or explicit application APIs — never via direct database access to another context." ] }, "security_governance": { "controls": [ { "risk": "Prompt injection via customer input", "context": "AI Orchestration", "impact": "high", "control": "Input scrubber + OutputValidator + tenant-scoped retrieval", "audit": "AgentRun trace" }, { "risk": "Cross-tenant retrieval leak", "context": "Knowledge Base", "impact": "severe", "control": "Per-tenant index partitions + TenantIsolationSpec enforced at router", "audit": "Retrieval call log" }, { "risk": "Signature spoofing", "context": "Quality Assurance", "impact": "severe", "control": "Signature bound to authenticated session; server-side validation", "audit": "Signature manifest" }, { "risk": "Premature public claim", "context": "Compliance & Governance", "impact": "high", "control": "ReleaseReadinessSpec on OwnerActionLedger", "audit": "Release-decision log" }, { "risk": "Privilege escalation", "context": "Identity & Access", "impact": "high", "control": "Roles in dedicated table + server-side checks + RLS", "audit": "Role assignment log" }, { "risk": "Silent delivery failure", "context": "Client Delivery & Success", "impact": "medium", "control": "Adapter receipt required; alert customer within 1h on failure", "audit": "Delivery receipt archive" } ], "ai_governance": [ "Every prompt version has a named owner + evaluator run + rollout flag", "AI outputs marked as suggestions until reviewer signoff", "Model + prompt inventory maintained in Ops console" ], "prompt_injection_defense": [ "Strip / neutralize instruction-like patterns in customer inputs before prompt assembly", "Never concatenate raw customer input into a system prompt", "OutputValidator rejects outputs that reference forbidden actions" ], "sensitive_data_handling": [ "PII scrubbed from logs", "Regulated data classes never sent to external model providers unless BAA/DPA covers it", "Per-tenant blob storage prefixes + signed URLs" ], "access_control_matrix": [ { "role": "Customer operator", "context": "Service Fulfillment", "capabilities": [ "OpenIntake", "AttachEvidence", "View own artifacts" ] }, { "role": "credentialed-technician reviewer", "context": "Quality Assurance", "capabilities": [ "ApproveArtifact", "RejectArtifact", "Co-sign retraction" ] }, { "role": "Business owner", "context": "Compliance & Governance", "capabilities": [ "ResolveOwnerAction", "Set release decision" ] }, { "role": "Legal", "context": "Quality Assurance + Compliance", "capabilities": [ "Co-sign retraction", "Handle DSAR" ] }, { "role": "Ops", "context": "AI Orchestration", "capabilities": [ "PublishPromptVersion", "Set confidence threshold" ] }, { "role": "Platform admin", "context": "Identity & Access", "capabilities": [ "Provision users", "Assign roles" ] } ], "audit_log_requirements": [ "Append-only", "Actor + tenant + timestamp + command + before/after hash", "PII scrubbed", "Exportable per tenant on request (DSAR support)" ] }, "observability": { "metrics": [ { "metric": "Reviewer-signed artifacts / week / tenant", "type": "business", "context": "Service Fulfillment", "why": "North star: repeatable value delivery", "target": "≥ contracted cadence", "alert_threshold": "< 80% of contracted cadence" }, { "metric": "AI draft acceptance rate", "type": "ai-quality", "context": "AI Orchestration", "why": "Signals grounding + prompt fit", "target": "≥ 70% by Phase 2", "alert_threshold": "< 50% weekly" }, { "metric": "Escalation rate", "type": "ai-quality", "context": "AI Orchestration", "why": "Guardrails firing correctly", "target": "5-15%", "alert_threshold": "> 30% weekly" }, { "metric": "Cycle time to signoff (p50 + p95)", "type": "operational", "context": "Quality Assurance", "why": "Reviewer throughput", "target": "p95 ≤ 5 business days", "alert_threshold": "> 5 business days" }, { "metric": "Signoff-to-retraction ratio", "type": "risk", "context": "Quality Assurance", "why": "Correctness signal", "target": "< 1%", "alert_threshold": "any retraction week-over-week" }, { "metric": "Delivery failure rate", "type": "reliability", "context": "Client Delivery & Success", "why": "Customer-facing reliability", "target": "< 0.5%", "alert_threshold": "> 1% daily" }, { "metric": "Owner-action open count", "type": "business", "context": "Compliance & Governance", "why": "Public-release readiness", "target": "0 for launched blueprints", "alert_threshold": "any blocker aging > 30 days" }, { "metric": "Model cost per artifact", "type": "financial", "context": "AI Orchestration", "why": "Margin control", "target": "≤ target per pricing model", "alert_threshold": "> 1.5× target" }, { "metric": "Cross-tenant retrieval violation attempts", "type": "risk", "context": "Knowledge Base", "why": "Security invariant", "target": "0", "alert_threshold": "any > 0" }, { "metric": "First-artifact time per tenant", "type": "customer", "context": "Client Onboarding & Profile", "why": "Activation", "target": "≤ 2 weeks", "alert_threshold": "> 4 weeks" } ], "dashboards": [ "Operator dashboard", "Reviewer queue", "Delivery health", "AI cost + escalation", "Compliance blockers" ], "audit_reports": [ "Per-tenant audit-log export", "Signature manifest export" ], "quality_review_reports": [ "Reviewer calibration report", "Escalation-outcome report" ], "ai_evaluation_reports": [ "Evaluator regression report", "Prompt-rollout diff" ], "client_outcome_reports": [ "Artifacts delivered", "Cycle time", "Retraction rate" ] }, "testing_strategy": { "tests": [ { "type": "Domain unit", "validates": "Aggregate invariants", "context": "all core contexts", "example": "ClaimPacketAggregate rejects deliver without signoff" }, { "type": "Aggregate invariant", "validates": "Consistency boundaries", "context": "Service Fulfillment / QA", "example": "Signed artifact is immutable" }, { "type": "Policy", "validates": "Reactive rules", "context": "AI Orchestration", "example": "Escalates below confidence threshold" }, { "type": "Specification", "validates": "Reusable rules", "context": "Compliance", "example": "ReleaseReadinessSpec blocks 'ready' with open owner actions" }, { "type": "Application use-case", "validates": "End-to-end command flow", "context": "Fulfillment + QA", "example": "Deliver signed artifact happy path" }, { "type": "Integration", "validates": "Adapter behavior", "context": "External Integrations", "example": "Stripe subscription webhook translates correctly" }, { "type": "Contract", "validates": "Published-language event schemas", "context": "cross-context", "example": "DraftProduced payload matches consumer expectations" }, { "type": "AI prompt eval", "validates": "Prompt quality vs golden dataset", "context": "AI Orchestration", "example": "Drafter accepts ≥ 40% in shadow mode" }, { "type": "RAG retrieval", "validates": "Tenant isolation + coverage", "context": "Knowledge Base", "example": "Cross-tenant lookup returns zero rows" }, { "type": "Golden dataset", "validates": "AI regression", "context": "AI Orchestration", "example": "No regression on past accepted artifacts" }, { "type": "Human review simulation", "validates": "Escalation UX", "context": "QA", "example": "Reviewer can complete signoff in ≤ 5 clicks" }, { "type": "End-to-end", "validates": "Critical path", "context": "all", "example": "Intake → signoff → delivery in staging" }, { "type": "Security", "validates": "Auth + RLS + injection defense", "context": "Identity + AI Orchestration", "example": "Prompt-injection payload is neutralized" }, { "type": "Regression", "validates": "No drift on prior fixes", "context": "all", "example": "Prior retraction bug does not reappear" } ], "critical_domain_rules": [ "No delivery without signoff", "No AI output without OutputValidator pass", "No retrieval outside tenant partition", "No public-release flip with open blockers" ], "ai_eval_dataset": [ "50 past reviewer-accepted artifacts per vertical (redacted)", "20 rejected drafts (ground truth for escalation)", "10 injection-payload cases" ], "regression_plan": "Every PR runs domain + policy + spec unit tests. Every prompt release runs Evaluator with regression gate. Weekly critical-path smoke test in staging.", "contract_testing_plan": "Published-language event schemas versioned in /shared/events; consumer tests run in CI against schema-version compatibility.", "manual_qa_checklist": [ "Signoff flow: signature captured + timestamp + hash", "Retraction flow: co-sign captured + customer notified", "Delivery flow: receipt archived", "DSAR flow: export completes end-to-end" ] }, "mvp_roadmap": [ { "phase": "Phase 0 — Manual workflow with instrumented capture", "goal": "Deliver one artifact end-to-end manually, capture every step as a domain event.", "features": [ "Manual intake form", "Evidence upload", "Human draft", "Reviewer signoff via signed form" ], "contexts": [ "Sales & Intake", "Service Fulfillment", "Quality Assurance" ], "ai_needs": [], "human_workflows": [ "Reviewer signoff" ], "data_needs": [ "service event", "field evidence", "Claim Submission Pack" ], "integrations": [ "Email" ], "risks": [ "Un-audited manual step" ], "exit_criteria": [ "1 real artifact delivered + reviewer-signed" ] }, { "phase": "Phase 1 — AI-assisted drafting for internal use only", "goal": "Introduce Drafter Agent with reviewer gate; no customer-facing AI language.", "features": [ "Drafter Agent (internal)", "OutputValidator", "Escalation route" ], "contexts": [ "AI Orchestration", "Service Fulfillment" ], "ai_needs": [ "Drafter, Classifier" ], "human_workflows": [ "Escalation review" ], "data_needs": [ "AgentRun", "PromptVersion" ], "integrations": [ "OpenAI / Anthropic" ], "risks": [ "Prompt injection", "Grounding drift" ], "exit_criteria": [ "AI draft acceptance rate ≥ 40% in shadow mode" ] }, { "phase": "Phase 2 — Operator dashboard + owner-action ledger", "goal": "Make the workflow legible + governable for the owner.", "features": [ "Operator dashboard", "Owner-action ledger", "Release-decision engine" ], "contexts": [ "Compliance & Governance" ], "ai_needs": [], "human_workflows": [ "Owner action resolution" ], "data_needs": [ "OwnerActionLedger" ], "integrations": [ "IdP" ], "risks": [ "Ungoverned public claims" ], "exit_criteria": [ "Release decisions computed from ledger" ] }, { "phase": "Phase 3 — Client delivery portal", "goal": "Give customers a portal to see status + receive artifacts.", "features": [ "Client portal", "Delivery adapter", "Revision workflow" ], "contexts": [ "Client Delivery & Success" ], "ai_needs": [], "human_workflows": [ "Success cadence" ], "data_needs": [ "Delivery" ], "integrations": [ "Email" ], "risks": [ "Silent delivery failure" ], "exit_criteria": [ "Delivery-failure alert within 1h" ] }, { "phase": "Phase 4 — Automated QA + reporting", "goal": "Wire metrics, retraction runbook, and evaluator agent.", "features": [ "Evaluator Agent", "Retraction workflow", "Dashboards" ], "contexts": [ "Analytics & Reporting", "Quality Assurance" ], "ai_needs": [ "Evaluator" ], "human_workflows": [ "Retraction co-sign" ], "data_needs": [ "Retraction" ], "integrations": [], "risks": [ "Vanity metrics" ], "exit_criteria": [ "North-star + guardrail metrics live" ] }, { "phase": "Phase 5 — Scale + optimization", "goal": "Reduce cost per artifact, increase reviewer throughput.", "features": [ "Prompt versioning UI", "Cost budgeting", "Multi-reviewer queue" ], "contexts": [ "AI Orchestration", "Quality Assurance" ], "ai_needs": [ "Cost meter" ], "human_workflows": [ "Multi-reviewer routing" ], "data_needs": [], "integrations": [], "risks": [ "Regression on rollout" ], "exit_criteria": [ "Model cost per artifact ≤ target" ] } ], "scaling_roadmap": [ { "stage": "≤ 5 tenants", "trigger": "Design-partner cohort", "architecture_change": "Single-region modular monolith + managed DB", "operational_change": "Founder-led ops; weekly working session", "risk": "Single-owner queue" }, { "stage": "5-25 tenants", "trigger": "First paid conversions", "architecture_change": "Extract heaviest module (AI Orchestration) behind an internal queue; keep monolith", "operational_change": "Named on-call rotation; SOC 2 Type I scoping", "risk": "Reviewer bottleneck" }, { "stage": "25-100 tenants", "trigger": "Multi-reviewer demand", "architecture_change": "Split AI Orchestration into its own service if throughput/isolation demands it; per-tenant retrieval sharding", "operational_change": "Dedicated success + prompt-ops roles", "risk": "Prompt version drift" }, { "stage": "100+ tenants", "trigger": "Enterprise + regulated segments", "architecture_change": "Regional deployments; per-region data residency; segregated compliance environments", "operational_change": "Dedicated SRE + compliance team; SOC 2 Type II + framework additions", "risk": "Compliance framework demand exceeds team capacity" } ], "risk_register": [ { "risk": "A state's adjuster/TPA statute sweeps in ministerial claims-processing more broadly than New York guidance", "likelihood": "medium", "impact": "severe", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Counsel review before each new state activates", "owner": "legal", "context": "Compliance & Governance" }, { "risk": "AI hallucination in a delivered claim packet", "likelihood": "medium", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Retrieval-first pipeline + structured output validation + claims-reviewer gate", "owner": "engineering", "context": "AI Orchestration" }, { "risk": "Cross-practice data leak", "likelihood": "low", "impact": "severe", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Row-level auth + per-practice retrieval indices + log-scrubbing", "owner": "engineering", "context": "Knowledge Base" }, { "risk": "Claims-reviewer bottleneck as onboarding outpaces reviewer capacity", "likelihood": "high", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Pilot cap + contractor reviewer added by month 7 per financial model", "owner": "ops", "context": "Claims Review" } ], "adrs": [ { "id": "ADR-001", "decision": "Architecture style", "status": "accepted", "context": "Single team, single regulated vertical per blueprint, evidence-linked workflow.", "options": [ "Modular monolith", "Microservices", "Serverless workflow", "No-code first" ], "chosen": "Modular monolith with event-driven internals", "business_reason": "Ship a defensible vertical slice with one team; avoid distributed-systems cost until scale forces it.", "technical_reason": "Deterministic transactions across aggregates; simpler ops; one deployable.", "tradeoffs": [ "May feel unsophisticated to enterprise reviewers", "Refactor cost if we later split" ], "risks": [ "Module boundaries erode without discipline" ], "revisit_trigger": "Any single module needs independent scaling or team boundary." }, { "id": "ADR-002", "decision": "Bounded context boundaries", "status": "accepted", "context": "Domain analysis above; distinct language groups for Fulfillment, AI Orchestration, QA, Compliance.", "options": [ "Contexts as above", "One big 'app' context", "Contexts split by UI page" ], "chosen": "Contexts as above (domain-derived)", "business_reason": "Protects the reviewer signoff invariant + owner-action ledger + evidence spine as first-class boundaries.", "technical_reason": "Aggregates align to consistency boundaries; ACLs contain external mess.", "tradeoffs": [ "More code organization discipline" ], "risks": [ "Team tries to bypass ACL for speed" ], "revisit_trigger": "New subdomain emerges (e.g., self-serve marketplace)." }, { "id": "ADR-003", "decision": "Database ownership", "status": "accepted", "context": "Modular monolith with shared Postgres; per-context schemas.", "options": [ "One shared schema", "Schema per context", "DB per context" ], "chosen": "Schema per context in shared Postgres, cross-context reads only via published projections.", "business_reason": "Keeps operational cost low; enforces boundaries without paying multi-DB tax.", "technical_reason": "RLS + schema separation gives ownership clarity.", "tradeoffs": [ "Discipline required to avoid cross-schema joins" ], "risks": [ "Bypass joins for speed" ], "revisit_trigger": "A context needs independent scaling or residency." }, { "id": "ADR-004", "decision": "AI orchestration strategy", "status": "accepted", "context": "Retrieval-first with structured-output validation + human gate.", "options": [ "Open-ended chat", "Retrieval-first + validated", "Autonomous multi-agent" ], "chosen": "Retrieval-first + structured validation + reviewer gate", "business_reason": "Grounding + defensibility are the paid outcome.", "technical_reason": "OutputValidator gives a hard boundary before drafts leave AI Orchestration.", "tradeoffs": [ "Slower than agentic chat" ], "risks": [ "Prompt version regression" ], "revisit_trigger": "Evaluator shows a step-function accuracy gain from a new pattern." }, { "id": "ADR-005", "decision": "Human review strategy", "status": "accepted", "context": "Regulated vertical; brand + legal risk on wrong outputs.", "options": [ "No human review (fully automated)", "Sampling review", "Every-artifact review" ], "chosen": "Every-artifact review by named licensed reviewer", "business_reason": "Signoff is the trust primitive.", "technical_reason": "Signature bound to session; append-only log.", "tradeoffs": [ "Reviewer throughput becomes the bottleneck" ], "risks": [ "Reviewer burnout" ], "revisit_trigger": "Sustained low retraction rate + regulator acceptance." }, { "id": "ADR-006", "decision": "Integration strategy", "status": "accepted", "context": "External systems: Vendor invoice inboxes, HVAC work-order / CMMS platforms, Customer AP / document portals, ...", "options": [ "Direct API coupling", "Anti-corruption layer per system", "Middleware bus (Zapier/n8n)" ], "chosen": "Anti-corruption layer per system, owned by External Integrations context", "business_reason": "External schemas must never leak into the core.", "technical_reason": "Adapters translate + validate; upstream break contained.", "tradeoffs": [ "More code than direct coupling" ], "risks": [ "Adapter lag on upstream change" ], "revisit_trigger": "External system stability changes materially." }, { "id": "ADR-007", "decision": "Modular monolith vs microservices", "status": "accepted", "context": "Same as ADR-001.", "options": [ "Monolith", "Microservices" ], "chosen": "Monolith", "business_reason": "Team size and scale do not justify microservices cost.", "technical_reason": "Distributed transactions across signoff/delivery would be a nightmare early.", "tradeoffs": [ "Refactor cost later" ], "risks": [ "Cultural expectation drift" ], "revisit_trigger": "See ADR-001." }, { "id": "ADR-008", "decision": "Build vs buy for generic subdomains", "status": "accepted", "context": "Billing, Identity, IdP, email.", "options": [ "Build all", "Buy generics" ], "chosen": "Buy generics (Stripe, IdP, transactional email)", "business_reason": "Do not spend core-domain hours on solved categories.", "technical_reason": "Standard SDKs + well-documented failure modes.", "tradeoffs": [ "Vendor risk" ], "risks": [ "Vendor lock-in" ], "revisit_trigger": "Cost or reliability materially degrades." } ], "self_audit": { "scores": [ { "category": "Domain accuracy", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Ubiquitous language quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Subdomain classification quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Bounded context clarity", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Core domain focus", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Context map quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Aggregate design quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Invariant quality", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "AI-agent responsibility design", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Human review safety", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Data ownership clarity", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Integration protection", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Implementation feasibility", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Scalability", "score": 7, "weakness": "Single-region; single-reviewer bottleneck; monolith split not planned.", "improvement": "Add per-tenant AI queue + multi-reviewer routing at Phase 2." }, { "category": "Security and compliance", "score": 7, "weakness": "High-trust vertical needs Type II mapping and per-regime controls earlier.", "improvement": "Map controls at Phase 1; commit to Type II by Phase 3." }, { "category": "Testing strategy", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." }, { "category": "Operational realism", "score": 7, "weakness": "Founder-led ops assumed through Phase 2; brittle to key-person absence.", "improvement": "Document runbooks; cross-train success + prompt-ops role by Phase 2." }, { "category": "MVP practicality", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain the current standard; re-audit after the first pilots land real data." } ], "weakest_parts": [ "Scalability plan assumes single reviewer per tenant through Phase 2", "Operational realism depends on founder-led ops", "Compliance framework depth for Type II" ], "biggest_assumptions": [ "The target audience will pay for evidence-linked, human-reviewed outputs over unverified AI generation.", "The workflow can be reconstructed from an owner-supplied evidence pack within one week per design partner.", "The vertical tolerates AI-assisted drafts when human review is explicit and audit-traceable." ], "highest_risk_decisions": [ "Modular monolith (ADR-001)", "Every-artifact reviewer signoff (ADR-005)", "Anti-corruption layer per external system (ADR-006)" ], "needs_domain_expert": [ "DVM or credentialed veterinary technician to validate release-gate ergonomics", "Veterinary-insurance-claims SME on invoice-field and chart-evidence taxonomy" ], "needs_legal": [ "Retraction workflow language", "DSAR SLA + regulator-response runbook", "Public-claim policy for microsite content" ], "needs_prototype": [ "Drafter Agent accuracy on 20-case golden dataset", "Reviewer signoff UX end-to-end in ≤ 5 minutes per artifact", "Per-tenant retrieval isolation test" ], "validate_before_prod": [ "Named licensed reviewer + engagement letter on file", "Owner-action ledger populated per launch tenant", "OutputValidator false-negative rate acceptable", "Delivery failure alert path tested" ] }, "final_recommendations": [ "Ship a modular-monolith, evidence-linked, reviewer-gated vertical slice for ClaimTail. Preserve the invariant that no Claim Submission Pack leaves the system without a signed human release — analyst on green/yellow, the insurer credentialed-technician reviewer on red. Do not launch commercially until owner-action facts close and at least one human-released Claim Submission Pack is delivered.", "Do NOT default to microservices. Extract a module only when a specific pressure demands it.", "Do NOT allow AI outputs to leave AI Orchestration without OutputValidator pass and citation coverage.", "Do NOT ship any public claim on the ClaimTail microsite while owner actions are open.", "Do NOT store roles on user/profile tables; use a dedicated roles table with server-side checks + RLS.", "DO wire the north-star + guardrail metrics before Phase 2 launch.", "DO capture every state transition as an append-only domain event; the audit trail is the product." ], "extensions": { "service_business_reality_check": { "is_service_business": true, "paid_outcome_clear": true, "workflow_present": true, "ai_native_fit_score": 8, "red_flags": [] }, "ai_native_fit": { "score": 8, "why": "Evidence-linked drafting + confidence-scored escalation is only economical with bounded AI orchestration. Pure-manual = uneconomic; pure-automated = undefensible.", "disqualifiers": [ "High-trust vertical: cannot ship without licensed reviewer signoff" ] }, "domain_evidence_register": [ { "claim": "ClaimTail paid outcome is a reviewer-signed artifact", "evidence_type": "primary", "source": "Business Understanding + subdomain 'Service Fulfillment'", "strength": "strong", "gaps": "Confirm with 3 design-partner interviews" }, { "claim": "Reviewer signoff is legally / commercially required for defensibility", "evidence_type": "primary", "source": "Vertical shape + regulator archetype", "strength": "strong", "gaps": "Vertical-specific attestation standard citation" }, { "claim": "AI drafting materially reduces cycle time vs. pure manual", "evidence_type": "assumed", "source": "Category benchmark", "strength": "medium", "gaps": "Measure on internal golden dataset" }, { "claim": "Customer will supply structured intake within SLA", "evidence_type": "assumed", "source": "Prospect conversations (unverified)", "strength": "weak", "gaps": "Run 5 intake dry-runs with design partners" }, { "claim": "Per-tenant retrieval isolation prevents cross-tenant leakage", "evidence_type": "primary", "source": "Architecture (Knowledge Base context)", "strength": "strong", "gaps": "Add automated cross-tenant lookup test" }, { "claim": "Owner-action ledger blocks premature public release", "evidence_type": "primary", "source": "Compliance & Governance context invariants", "strength": "strong", "gaps": "None" }, { "claim": "Model + prompt versioning enables reproducible outputs", "evidence_type": "primary", "source": "AI Orchestration context", "strength": "strong", "gaps": "Evaluator regression thresholds not yet baselined" }, { "claim": "Cycle-time reduction supports premium pricing", "evidence_type": "assumed", "source": "Pricing hypothesis", "strength": "medium", "gaps": "Test with 3 pricing conversations" } ], "assumption_register": [ { "assumption": "The target audience will pay for evidence-linked, human-reviewed outputs over unverified AI generation.", "impact_if_wrong": "high", "how_to_validate": "Design-partner interview + measurement", "blocking": true }, { "assumption": "The workflow can be reconstructed from an owner-supplied evidence pack within one week per design partner.", "impact_if_wrong": "high", "how_to_validate": "Design-partner interview + measurement", "blocking": true }, { "assumption": "The vertical tolerates AI-assisted drafts when human review is explicit and audit-traceable.", "impact_if_wrong": "high", "how_to_validate": "Design-partner interview + measurement", "blocking": false }, { "assumption": "Single-tenant per customer is not required for the first cohort — logical isolation with row-level auth is acceptable.", "impact_if_wrong": "medium", "how_to_validate": "Instrument metric + review after Phase 1", "blocking": false }, { "assumption": "Manifest-backed blueprint reflects real customer workflow, not a synthetic scenario.", "impact_if_wrong": "medium", "how_to_validate": "Instrument metric + review after Phase 1", "blocking": false }, { "assumption": "A licensed reviewer can be sourced and retained for this vertical", "impact_if_wrong": "severe", "how_to_validate": "Recruit + sign engagement letter before commercial launch", "blocking": true }, { "assumption": "External systems expose stable APIs with predictable failure modes", "impact_if_wrong": "medium", "how_to_validate": "Adapter contract tests + failure-injection", "blocking": false } ], "language_conflict_map": [ { "term": "Engagement", "meaning_a": "A signed billing contract", "context_a": "Billing & Revenue", "meaning_b": "An accepted unit of intake work", "context_b": "Sales & Intake", "resolution": "Billing owns 'Engagement'; Fulfillment uses vertical-specific intake noun." }, { "term": "Approval", "meaning_a": "Customer accepts a delivered draft", "context_a": "Client Delivery", "meaning_b": "Reviewer signs an artifact", "context_b": "Quality Assurance", "resolution": "QA uses 'Signoff'; Delivery uses 'Customer approval'." }, { "term": "Confidence", "meaning_a": "Model-assigned probability", "context_a": "AI Orchestration", "meaning_b": "Human legal/clinical confidence", "context_b": "Quality Assurance", "resolution": "Never conflate; always qualify (model_confidence vs reviewer_confidence)." } ], "build_buy_integrate": [ { "subdomain": "Service Fulfillment (evidence-linked drafting + review)", "decision": "build", "reason": "This is what customers pay for and what regulators inspect." }, { "subdomain": "AI Orchestration (bounded agents + retrieval)", "decision": "build", "reason": "The AI-native competitive edge lives here; misuse here creates every high-severity risk." }, { "subdomain": "Quality Assurance (reviewer signoff + retraction)", "decision": "build", "reason": "Signoff is the trust primitive of the whole business." }, { "subdomain": "Sales & Intake", "decision": "build", "reason": "Feeds Fulfillment; not the differentiator, but if broken, nothing else runs." }, { "subdomain": "Client Onboarding & Profile", "decision": "build", "reason": "One-time high-touch step per customer." }, { "subdomain": "Client Delivery & Success", "decision": "build", "reason": "Customer-visible surface; drives retention." }, { "subdomain": "Compliance & Governance", "decision": "build", "reason": "Cross-cuts every context; owns 'can we publicly claim this?'." }, { "subdomain": "Billing & Revenue", "decision": "buy", "reason": "Solved category; do not build." }, { "subdomain": "Identity & Access", "decision": "integrate", "reason": "Solved category." }, { "subdomain": "Knowledge Base & Retrieval", "decision": "build", "reason": "Feeds AI Orchestration; poor retrieval = poor drafts." }, { "subdomain": "Analytics & Reporting", "decision": "build", "reason": "Drives every operational decision." }, { "subdomain": "External Integrations (Anti-Corruption Layer)", "decision": "build", "reason": "External schemas must never leak into the core." } ], "core_protection_strategy": [ "Core contexts (Service Fulfillment, AI Orchestration, Quality Assurance) staffed before any generic subdomain work.", "Any change to a core aggregate requires a paired ADR + invariant test.", "Generic subdomains (Billing, Identity) are bought or integrated; never built in-house without a killer reason.", "Prompt-version rollout to core agents gated on Evaluator regression run.", "No feature flag may bypass the reviewer-signoff invariant." ], "boundary_stress_tests": [ { "scenario": "Customer requests changes to a delivered artifact", "contexts_touched": [ "Client Delivery", "Service Fulfillment", "Quality Assurance" ], "breaks_if": "Revision creates a new draft without re-triggering signoff", "verdict": "holds" }, { "scenario": "Reviewer identity changes mid-engagement", "contexts_touched": [ "Client Onboarding", "Quality Assurance" ], "breaks_if": "QA cached reviewer identity locally", "verdict": "adjust" }, { "scenario": "the insurer finalizes a rule change touching the completeness checklist scope", "contexts_touched": [ "Compliance & Governance", "Knowledge Base" ], "breaks_if": "Retrieval index not reindexed within SLA", "verdict": "holds" }, { "scenario": "Owner marks an action resolved that is actually not", "contexts_touched": [ "Compliance & Governance" ], "breaks_if": "No re-verification step before release-decision flips", "verdict": "adjust" }, { "scenario": "AI produces high-confidence draft with wrong citation", "contexts_touched": [ "AI Orchestration", "Quality Assurance" ], "breaks_if": "OutputValidator does not check citation-to-claim linkage", "verdict": "holds" } ], "unresolved_ownership": [ { "concept": "Reviewer engagement letter", "candidates": [ "Client Onboarding", "Quality Assurance" ], "recommendation": "Own in Client Onboarding; QA references by id." }, { "concept": "Public claim / marketing site content", "candidates": [ "Compliance & Governance", "Client Delivery" ], "recommendation": "Compliance owns the release-decision; Delivery renders." }, { "concept": "Model + prompt cost attribution", "candidates": [ "AI Orchestration", "Billing & Revenue" ], "recommendation": "AI Orchestration owns raw run cost; Billing consumes rolled-up projections." } ], "published_language_contracts": [ { "producer": "Sales & Intake", "consumer": "Service Fulfillment", "contract": "EngagementAccepted", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Service Fulfillment", "consumer": "Quality Assurance", "contract": "DraftReady, ArtifactSigned", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "AI Orchestration", "consumer": "Service Fulfillment", "contract": "DraftProduced, EscalationRaised", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Knowledge Base & Retrieval", "consumer": "AI Orchestration", "contract": "DocIngested, IndexRebuilt", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Client Onboarding & Profile", "consumer": "Service Fulfillment", "contract": "TenantProvisioned, ReviewerRegistered", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Service Fulfillment", "consumer": "Client Delivery & Success", "contract": "ArtifactDelivered, DeliveryConfirmed", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Quality Assurance", "consumer": "Compliance & Governance", "contract": "RetractionFiled", "versioning": "SemVer on event schema; consumer contract tests in CI." }, { "producer": "Client Delivery & Success", "consumer": "Billing & Revenue", "contract": "DeliveryConfirmed", "versioning": "SemVer on event schema; consumer contract tests in CI." } ], "shared_kernel_warnings": [ "Shared kernel must remain small: Ids, Money, Tenant, Actor. Adding a domain concept here couples every context.", "Never share aggregates across contexts via shared kernel — publish an event or expose an application service.", "Any addition to /shared requires 2-context approval to prevent silent coupling." ], "aggregate_stress_tests": [ { "aggregate": "ServiceEventAggregate", "scenario": "Concurrent command on ServiceEventAggregate", "invariant_at_risk": "Every claim in a delivered artifact cites evidence", "verdict": "holds" }, { "aggregate": "ClaimPacketAggregate", "scenario": "Concurrent command on ClaimPacketAggregate", "invariant_at_risk": "A Claim Submission Pack cannot be delivered without a valid Signoff", "verdict": "holds" }, { "aggregate": "SignoffAggregate", "scenario": "Concurrent command on SignoffAggregate", "invariant_at_risk": "Signature bound to a live authenticated session, not a form field", "verdict": "holds" }, { "aggregate": "RetractionAggregate", "scenario": "Concurrent command on RetractionAggregate", "invariant_at_risk": "A retraction requires Legal + Reviewer co-signature", "verdict": "holds" }, { "aggregate": "AgentRunAggregate", "scenario": "Concurrent command on AgentRunAggregate", "invariant_at_risk": "No output emitted without OutputValidator pass", "verdict": "holds" } ], "agent_stress_tests": [ { "agent": "Drafter Agent", "scenario": "Malformed / adversarial input to Drafter Agent", "failure_mode": "Prompt injection", "guardrail": "Structured-output schema", "verdict": "holds" }, { "agent": "Classifier Agent", "scenario": "Malformed / adversarial input to Classifier Agent", "failure_mode": "Wrong route → wrong reviewer", "guardrail": "Structured-output schema", "verdict": "holds" }, { "agent": "Evaluator Agent", "scenario": "Malformed / adversarial input to Evaluator Agent", "failure_mode": "Overfit to golden dataset", "guardrail": "Regression thresholds", "verdict": "holds" } ], "regulated_domain_handling": [ { "regime": "the insurer veterinary insurance claims ER&R (the insurer-specific completeness checklist) with the ministerial-vs-discretionary claims-processing boundary", "applies_because": "Ministerial claims-processing records are reconstructable on demand; recurring-exception reports go to the insurer (always customer-submitted).", "controls": [ "Cited rule provision per claim", "credentialed-technician reviewer release on red packs" ], "evidence_required": [ "rule-to-record map", "Pack release records + tracker rows" ] } ], "unit_economics": { "price_model": "Flat per-claim fee ($12-$18) + per-location monthly Eligibility & Monitoring Retainer", "unit_of_value": "Released veterinary-insurance-claims-case-acceptance-desk Claim Submission Pack", "gross_margin_pct": 61, "cost_drivers": [ "Reviewer hours per artifact", "AI model + retrieval cost", "External API + delivery cost", "Support + success" ], "breakeven_note": "Breakeven depends on analyst throughput and extraction acceptance rate; target analyst minutes per green pack ≤12 by day 90 and ≥40% straight-through extraction by month 6." }, "margin_leakage_map": [ { "leakage": "Reviewer over-editing AI drafts", "cause": "Low AI acceptance rate", "impact": "high", "mitigation": "Evaluator regression + prompt-owner accountability" }, { "leakage": "External API retries without backoff", "cause": "Poor adapter design", "impact": "medium", "mitigation": "Exponential backoff + circuit breaker" }, { "leakage": "Cross-tenant retrieval scan cost", "cause": "Missing partitioning", "impact": "high", "mitigation": "Per-tenant index partitions" }, { "leakage": "Silent delivery failure absorbing support time", "cause": "No adapter receipts", "impact": "medium", "mitigation": "Adapter receipts + 1h SLA alert" } ], "slop_findings": [ { "pattern": "generic 'dashboard'-only value prop", "status": "clean", "note": "Value prop is reviewer-signed artifact, not a dashboard." }, { "pattern": "AI-as-magic", "status": "clean", "note": "AI is bounded to drafting + validation; humans own signoff." }, { "pattern": "blockchain", "status": "clean", "note": "No blockchain-as-hype in derivation." }, { "pattern": "agent-first (agents replace humans)", "status": "clean", "note": "Every agent has forbidden actions + human escalation." }, { "pattern": "microservices by default", "status": "clean", "note": "ADR-001 chose modular monolith." }, { "pattern": "everything-is-core", "status": "clean", "note": "Generic subdomains explicitly marked buy/integrate." } ], "drift_checks": [ { "stage": "Business Truth Discovery", "status": "pass", "findings": [] }, { "stage": "Ubiquitous Language", "status": "pass", "findings": [] }, { "stage": "Strategic Subdomains", "status": "pass", "findings": [] }, { "stage": "Bounded Contexts", "status": "pass", "findings": [] }, { "stage": "Context Mapping", "status": "pass", "findings": [] }, { "stage": "Event Storming", "status": "pass", "findings": [] }, { "stage": "Commands/Events/Policies", "status": "pass", "findings": [] }, { "stage": "Tactical Model", "status": "pass", "findings": [] }, { "stage": "AI-Native Ops", "status": "pass", "findings": [] }, { "stage": "Human-in-the-Loop", "status": "pass", "findings": [] }, { "stage": "Evidence + Compliance", "status": "pass", "findings": [] }, { "stage": "Data Ownership", "status": "pass", "findings": [] }, { "stage": "Integration", "status": "pass", "findings": [] }, { "stage": "Application Use Cases", "status": "pass", "findings": [] }, { "stage": "Outcome Economics", "status": "pass", "findings": [] }, { "stage": "Technical Architecture", "status": "pass", "findings": [] }, { "stage": "Security + Governance", "status": "pass", "findings": [] }, { "stage": "Testing", "status": "pass", "findings": [] }, { "stage": "MVP Roadmap", "status": "pass", "findings": [] }, { "stage": "Scaling", "status": "pass", "findings": [] }, { "stage": "Risk", "status": "pass", "findings": [] }, { "stage": "ADRs", "status": "pass", "findings": [] }, { "stage": "Foundry Package", "status": "pass", "findings": [] }, { "stage": "Contradiction Scan", "status": "pass", "findings": [] }, { "stage": "Self-Audit", "status": "pass", "findings": [] } ], "gates": [ { "id": "domain", "title": "Domain Clarity", "passed": true, "checks": [ { "name": "Paid outcome present", "ok": true, "evidence": "business_understanding.paid_outcome" }, { "name": "≥3 actors identified", "ok": true, "evidence": "5 actors" } ] }, { "id": "core", "title": "Core Domain", "passed": true, "checks": [ { "name": "At least one core subdomain", "ok": true, "evidence": "Service Fulfillment (evidence-linked drafting + review), AI Orchestration (bounded agents + retrieval), Quality Assurance (reviewer signoff + retraction)" } ] }, { "id": "boundary", "title": "Boundary", "passed": true, "checks": [ { "name": "≥4 bounded contexts", "ok": true, "evidence": "11 contexts" }, { "name": "Every context has owned language", "ok": true, "evidence": "all populated" } ] }, { "id": "invariant", "title": "Invariant", "passed": true, "checks": [ { "name": "≥4 business invariants", "ok": true, "evidence": "9 invariants" } ] }, { "id": "ai-safety", "title": "AI Safety", "passed": true, "checks": [ { "name": "Every agent has forbidden actions", "ok": true, "evidence": "yes" }, { "name": "Every agent has escalation triggers", "ok": true, "evidence": "yes" } ] }, { "id": "buildability", "title": "Buildability", "passed": true, "checks": [ { "name": "MVP roadmap ≥2 phases", "ok": true, "evidence": "6 phases" } ] }, { "id": "anti-slop", "title": "Anti-Slop", "passed": true, "checks": [ { "name": "No slop patterns", "ok": true, "evidence": "slop_findings all clean/warn" }, { "name": "No failing contradictions", "ok": true, "evidence": "8 findings" } ] } ], "contradiction_scan": [ { "id": "INV-AGG-SignoffAggregate + RetractionAggregate", "severity": "warn", "message": "Invariant references aggregate 'SignoffAggregate + RetractionAggregate' not defined", "refs": [ "SignoffAggregate + RetractionAggregate" ] }, { "id": "INV-AGG-IndexShardAggregate", "severity": "warn", "message": "Invariant references aggregate 'IndexShardAggregate' not defined", "refs": [ "IndexShardAggregate" ] }, { "id": "INV-AGG-UserAggregate", "severity": "warn", "message": "Invariant references aggregate 'UserAggregate' not defined", "refs": [ "UserAggregate" ] }, { "id": "CMD-EVT-OpenIntake-IntakeRejected", "severity": "info", "message": "Command OpenIntake references event 'IntakeRejected' not present in domain_events", "refs": [ "OpenIntake", "IntakeRejected" ] }, { "id": "CMD-EVT-AttachEvidence-EvidenceRejected", "severity": "info", "message": "Command AttachEvidence references event 'EvidenceRejected' not present in domain_events", "refs": [ "AttachEvidence", "EvidenceRejected" ] }, { "id": "CMD-EVT-DeliverClaimPacket-DeliveryFailed", "severity": "info", "message": "Command DeliverClaimPacket references event 'DeliveryFailed' not present in domain_events", "refs": [ "DeliverClaimPacket", "DeliveryFailed" ] }, { "id": "CMD-EVT-ResolveOwnerAction-OwnerActionRejected", "severity": "info", "message": "Command ResolveOwnerAction references event 'OwnerActionRejected' not present in domain_events", "refs": [ "ResolveOwnerAction", "OwnerActionRejected" ] }, { "id": "CMD-EVT-FileRetraction-RetractionRejected", "severity": "info", "message": "Command FileRetraction references event 'RetractionRejected' not present in domain_events", "refs": [ "FileRetraction", "RetractionRejected" ] } ], "rubric": { "categories": [ { "category": "Domain accuracy", "score": 8, "min": 7, "passed": true }, { "category": "Ubiquitous language quality", "score": 8, "min": 7, "passed": true }, { "category": "Subdomain classification quality", "score": 8, "min": 7, "passed": true }, { "category": "Bounded context clarity", "score": 9, "min": 7, "passed": true }, { "category": "Core domain focus", "score": 9, "min": 7, "passed": true }, { "category": "Context map quality", "score": 8, "min": 7, "passed": true }, { "category": "Aggregate design quality", "score": 8, "min": 7, "passed": true }, { "category": "Invariant quality", "score": 9, "min": 7, "passed": true }, { "category": "AI-agent responsibility design", "score": 9, "min": 7, "passed": true }, { "category": "Human review safety", "score": 9, "min": 7, "passed": true }, { "category": "Data ownership clarity", "score": 8, "min": 7, "passed": true }, { "category": "Integration protection", "score": 8, "min": 7, "passed": true }, { "category": "Implementation feasibility", "score": 8, "min": 7, "passed": true }, { "category": "Scalability", "score": 7, "min": 7, "passed": true }, { "category": "Security and compliance", "score": 7, "min": 7, "passed": true }, { "category": "Testing strategy", "score": 8, "min": 7, "passed": true }, { "category": "Operational realism", "score": 7, "min": 7, "passed": true }, { "category": "MVP practicality", "score": 9, "min": 7, "passed": true } ], "pass": true, "average": 8.2 }, "foundry_package": { "version": "1.0.0", "checksum": "bec1171d", "counts": { "subdomains": 12, "bounded_contexts": 11, "aggregates": 8, "events": 8, "commands": 7, "policies": 5, "ai_agents": 3, "invariants": 9, "integrations": 4, "adrs": 8 }, "subset": { "subdomains": [ "Service Fulfillment (evidence-linked drafting + review)", "AI Orchestration (bounded agents + retrieval)", "Quality Assurance (reviewer signoff + retraction)", "Sales & Intake", "Client Onboarding & Profile", "Client Delivery & Success", "Compliance & Governance", "Billing & Revenue", "Identity & Access", "Knowledge Base & Retrieval", "Analytics & Reporting", "External Integrations (Anti-Corruption Layer)" ], "bounded_contexts": [ "Service Fulfillment", "AI Orchestration", "Quality Assurance", "Compliance & Governance", "Sales & Intake", "Client Onboarding & Profile", "Client Delivery & Success", "Knowledge Base & Retrieval", "Billing & Revenue", "Identity & Access", "Analytics & Reporting" ], "aggregates": [ "ServiceEventAggregate", "ClaimPacketAggregate", "SignoffAggregate", "RetractionAggregate", "AgentRunAggregate", "OwnerActionLedgerAggregate", "TenantAggregate", "DeliveryAggregate" ], "events": [ "serviceEventAccepted", "EvidenceCollected", "DraftReady", "EscalationRaised", "ReviewerSigned", "ArtifactDelivered", "OwnerActionResolved", "RetractionFiled" ], "commands": [ "OpenIntake", "AttachEvidence", "StartAgentRun", "ApproveArtifact", "DeliverClaimPacket", "ResolveOwnerAction", "FileRetraction" ], "policies": [ "Auto-request signoff on coverage complete", "Escalate on low confidence", "Block delivery on open compliance blocker", "Retract on material finding", "Alert on delivery failure" ], "ai_agents": [ "Drafter Agent", "Classifier Agent", "Evaluator Agent" ], "invariants": [ "A Claim Submission Pack cannot be delivered without a valid Reviewer signoff.", "Every claim in a delivered artifact cites at least one evidence item.", "A signature is bound to a live authenticated session, not a form field.", "Signed artifacts are immutable; corrections go through Retraction.", "No AI output leaves AI Orchestration without OutputValidator pass.", "Retrieval is scoped to a single tenant partition per call.", "Release cannot flip to 'ready' with open blocking owner actions.", "Every tenant has at least one named reviewer with valid credential.", "Roles are stored in a dedicated table and checked server-side." ], "integrations": [ "Vendor invoice inboxes", "HVAC work-order / CMMS platforms", "Customer AP / document portals", "OpenAI / Anthropic API" ], "adrs": [ "ADR-001", "ADR-002", "ADR-003", "ADR-004", "ADR-005", "ADR-006", "ADR-007", "ADR-008" ] } } } }, "ddd_coverage": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "total": 20, "passed": 20, "pct": 100, "checks": [ { "key": "actors", "label": "Actors", "count": 5, "min": 3, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "glossary", "label": "Glossary", "count": 8, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "decisions", "label": "Business decisions", "count": 5, "min": 4, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "events", "label": "Domain events", "count": 8, "min": 6, "ok": true, "gate": "domain", "unblock": "Not needed — check passes at current counts." }, { "key": "subdomains", "label": "Subdomains", "count": 12, "min": 8, "ok": true, "gate": "core", "unblock": "Not needed — check passes at current counts." }, { "key": "bcs", "label": "Bounded contexts", "count": 11, "min": 4, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "ctx_map", "label": "Context map", "count": 11, "min": 3, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "event_storm", "label": "Event storm rows", "count": 13, "min": 6, "ok": true, "gate": "boundary", "unblock": "Not needed — check passes at current counts." }, { "key": "aggregates", "label": "Aggregates", "count": 8, "min": 3, "ok": true, "gate": "invariant", "unblock": "Not needed — check passes at current counts." }, { "key": "invariants", "label": "Invariants", "count": 9, "min": 4, "ok": true, "gate": "invariant", "unblock": "Not needed — check passes at current counts." }, { "key": "ai_agents", "label": "AI agents", "count": 3, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Not needed — check passes at current counts." }, { "key": "use_cases", "label": "Use cases", "count": 3, "min": 3, "ok": true, "gate": "buildability", "unblock": "Not needed — check passes at current counts." }, { "key": "evidence_reg", "label": "Evidence register", "count": 8, "min": 5, "ok": true, "gate": "domain", "unblock": "Attach or verify a domain-evidence claim (source + strength)." }, { "key": "assumptions", "label": "Assumption register", "count": 7, "min": 4, "ok": true, "gate": "domain", "unblock": "Log and validate a blocking assumption in the evidence register." }, { "key": "stress_boundary", "label": "Boundary stress tests", "count": 5, "min": 3, "ok": true, "gate": "boundary", "unblock": "Resolve an unresolved-ownership scenario before wiring boundary evidence." }, { "key": "stress_agg", "label": "Aggregate stress tests", "count": 5, "min": 3, "ok": true, "gate": "invariant", "unblock": "Add or verify an aggregate invariant enforcement test." }, { "key": "stress_agent", "label": "Agent stress tests", "count": 3, "min": 2, "ok": true, "gate": "ai-safety", "unblock": "Attach an AI-safety guardrail evidence item for the agent." }, { "key": "gates_pass", "label": "Hard gates passing", "count": 7, "min": 7, "ok": true, "unblock": "One or more hard gates are failing — see failing gates below." }, { "key": "rubric", "label": "Extended rubric pass", "count": 1, "min": 1, "ok": true, "gate": "buildability", "unblock": "Raise weakest rubric category by attaching evidence for the linked concern." }, { "key": "foundry", "label": "Foundry package", "count": 11, "min": 4, "ok": true, "gate": "buildability", "unblock": "Foundry package under-populated — regenerate blueprint via GitHub sync." } ], "failingGates": [] }, "architecture": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "archetypes": [ "regulated system", "CRUD/workflow application", "internal operations platform" ], "archetype_impact": "Insurer and practice identity are global query parameters — every read/write is scoped by claim, insurer, and practice, not just tenant.", "personality": [ "workflow-heavy", "cost-sensitive", "highly regulated", "highly secure" ], "forces_ranked": [ { "force": "compliance", "why": "Regulated verticals gate release; the architecture must prove, not assert, compliance." }, { "force": "auditability", "why": "Every release decision, every evidence toggle, must be defensible in review." }, { "force": "reliability", "why": "A broken blueprint is a broken release gate — availability is a product feature." }, { "force": "data integrity", "why": "Evidence is the product; a corrupted citation is a shipped defect." }, { "force": "maintainability", "why": "One team maintains dozens of blueprints; the shape must be identical across them." } ], "tradeoffs": [ "Prioritizing auditability slows raw throughput — accepted; the product IS the audit trail.", "Choosing a modular monolith trades independent scaling for a single deploy story — accepted while the team is small.", "Using managed Cloud primitives trades some portability for zero ops — accepted; data is portable, runtime is not the moat." ], "quality_scenarios": [ { "attribute": "Performance (interactive p95)", "target": "600 ms on Blueprint detail routes", "assumption": "Measured from Cloud edge, warm cache." }, { "attribute": "Availability", "target": "99.5% (with March-reporting-window freeze protection)", "assumption": "Rolling 30-day window; excludes announced maintenance." }, { "attribute": "RTO", "target": "24h" }, { "attribute": "RPO", "target": "24h (daily backups)" }, { "attribute": "Latency (edge function warm)", "target": "≤ 800ms p95 excluding upstream AI calls" }, { "attribute": "Data durability", "target": "11 nines via managed Postgres + storage replication" }, { "attribute": "Security", "target": "OWASP ASVS L1 baseline" }, { "attribute": "Auditability", "target": "100% of release decisions + evidence toggles logged with actor + timestamp" }, { "attribute": "Maintainability", "target": "New blueprint reaches validation-microsite state in ≤ 1 working session" }, { "attribute": "Deployment frequency", "target": "≥ 5 deploys/week without incident" }, { "attribute": "Observability", "target": "Every edge function emits correlationId; retries + phases visible in diagnostics drawer" }, { "attribute": "Cost envelope", "target": "Idle per-blueprint cost ≈ $0; active < $5/month at MVP traffic" }, { "attribute": "Scalability", "target": "Horizontal by blueprint count; single blueprint sized for < 10 req/s sustained" } ], "options": [ { "style": "simple monolith", "fits_when": "Single team, low traffic, no independent scaling concerns.", "fits_here": "Matches the per-blueprint scope — one microsite, one schema, one code path.", "wrong_here": "Would couple every blueprint into a single deploy — not acceptable at network scale.", "complexity": "low", "cost": "low", "ops_burden": "low", "security_impact": "Small surface, single audit boundary.", "scaling_path": "Vertical scale only; hits ceiling on team velocity, not compute.", "team_fit": "Ideal for one dev; fine at MVP.", "recommended": false }, { "style": "modular monolith", "fits_when": "Multiple bounded contexts but shared deploy lifecycle acceptable.", "fits_here": "Each blueprint is a module inside the network shell; shared shell, isolated data.", "wrong_here": "Wrong only if a blueprint needs independent SLOs — none currently do.", "complexity": "moderate", "cost": "low", "ops_burden": "low", "security_impact": "Single trust boundary; row-level isolation carries the tenancy load.", "scaling_path": "Modules become services only when SLOs or teams diverge.", "team_fit": "Best fit for a small team maintaining many blueprints.", "recommended": true }, { "style": "serverless", "fits_when": "Bursty, per-request workloads with idle-to-zero cost targets.", "fits_here": "Edge functions already handle sync, docs, legal, seed articles, integrity — pay-per-invoke.", "wrong_here": "Wrong for long-running orchestrations; IDLE_TIMEOUT already bit us on legal docs.", "complexity": "moderate", "cost": "low", "ops_burden": "moderate", "security_impact": "Function-scoped IAM; secrets via managed vault.", "scaling_path": "Auto; watch cold-start p95 and per-invocation cost.", "team_fit": "Good — team already ships functions weekly.", "recommended": false }, { "style": "microservices", "fits_when": "Multiple teams, divergent SLOs, independent release cadence required.", "fits_here": "Nothing here justifies it; single team, single deploy cadence, shared data plane.", "wrong_here": "Adds network, discovery, deploy topology, and observability cost with zero product benefit.", "complexity": "very high", "cost": "high", "ops_burden": "high", "security_impact": "Bigger attack surface, more inter-service auth to get right.", "scaling_path": "Best-in-class if the org can afford it.", "team_fit": "Wrong for this team.", "recommended": false }, { "style": "event-driven", "fits_when": "Async fan-out, decoupled producers/consumers, replayable history required.", "fits_here": "Only the sync + integrity pipeline is fan-out; keep it as background jobs, not a broker.", "wrong_here": "Broker + schema registry + DLQ topology is overkill for current volumes.", "complexity": "high", "cost": "moderate", "ops_burden": "high", "security_impact": "Extra ACLs; message-level auth needed.", "scaling_path": "Excellent for future audit-log fan-out, revisit at 10x volume.", "team_fit": "Team can operate a small in-process queue; not a full broker yet.", "recommended": false }, { "style": "workflow/orchestration", "fits_when": "Long, multi-step, resumable pipelines with human-in-the-loop steps.", "fits_here": "Blueprint pipeline (sources → articles → integrity → smoke test) already smells like this.", "wrong_here": "Full engine (Temporal/Airflow) is heavy; a typed in-app queue with retries covers today's needs.", "complexity": "high", "cost": "moderate", "ops_burden": "moderate", "security_impact": "Central choke point — must be hardened.", "scaling_path": "Adopt engine once we cross ~10 concurrent long-running jobs per blueprint.", "team_fit": "Would require operator ramp-up.", "recommended": false } ], "chosen_style": "modular monolith", "chosen_rationale": "Modular monolith with edge functions for bursty AI/generation — one audit boundary, low ops burden, easy per-team ownership.", "rejected": [ { "style": "microservices", "why_rejected": "Adds network, discovery, deploy topology, and observability cost with zero product benefit." }, { "style": "event-driven", "why_rejected": "Broker + schema registry + DLQ topology is overkill for current volumes." } ], "target": { "overview": "React shell → Lovable Cloud (Postgres + Auth + Storage + Edge Functions). Every blueprint is a module inside the shell; per-vertical differences live in derived DNA, not in separate deploys. Compliance posture: Domain-specific (claims-authorization records, reviewer attestations, retention schedules).", "frontend": "Vite + React + TypeScript + Tailwind + shadcn primitives; per-blueprint themed via Design DNA; job queue for background pipelines; URL-persisted filter state on audit + diagnostics.", "backend": "Deno-based edge functions per capability. Long generations split into per-item endpoints to stay under IDLE_TIMEOUT.", "data": "Managed Postgres with RLS + JSONB for shape drift. Object storage for source files + generated artifacts.", "api": "REST-ish RPC over edge functions with typed payloads; correlationId on every call for retry/diagnostics.", "authn_authz": "Managed OAuth (Google default). Roles in a dedicated user_roles table + has_role() SECURITY DEFINER function referenced by RLS policies.", "integrations": "GitHub (public read for sync + sources), Lovable AI Gateway (all LLM calls), Cloud Storage (artifacts). No third-party CRM/email yet.", "background_jobs": "blueprintJobQueue in-app: per-slug concurrency limit, exponential backoff + jitter, cancel + invalidate, retention of last error diagnostics.", "object_storage": "Cloud Storage buckets scoped per blueprint slug; signed URLs for artifact download.", "notifications": "In-app toasts + audit trail entries. Email/webhook deferred until owners request it.", "search": "Postgres FTS on blueprint titles + evidence claims; client-side filter for audit trail. Dedicated index deferred.", "analytics": "Lightweight event log in Postgres; dashboard-grade analytics deferred until we have a paying tenant.", "ai": "not applicable", "observability": "correlationId per request, per-phase timings, retry timeline in diagnostics drawer, per-blueprint pipeline status panel, JSON report export.", "deployment": "Preview + Production environments; edge functions deploy with the app; Postgres migrations shipped via managed migration tool.", "security": "RLS on every public table; roles in user_roles; secrets in managed vault; OWASP ASVS L1 baseline.", "dr": "Daily backups; restore drill twice/year." }, "modules": [ { "name": "Blueprint Core", "responsibility": "Owns the SeedBusiness catalog, release decisions, evidence register, owner actions.", "owned_data": [ "seed business rows", "release_decision", "evidence items", "owner-action state" ], "entities": [ "SeedBusiness", "EvidenceItem", "OwnerAction", "ReleaseDecision" ], "interfaces": [ "React store (StoreProvider)", "public read via microsite route" ], "depends_on": [ "Content Pipeline (for source files + articles)", "Cloud auth" ], "events_produced": [ "release.decision.changed", "evidence.status.changed", "owner.action.resolved" ], "events_consumed": [ "sync.blueprint.applied", "integrity.check.completed" ], "failure_risks": [ "Duplicate slug in seed → React key crash (mitigated by dedupe in mergedSeed)", "Evidence drift after sync" ], "scaling": "Bounded by SEED size; irrelevant even at 10x.", "future_split_trigger": "Split out Blueprint Core into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Content Pipeline", "responsibility": "Fetches GitHub sources, generates docs/seed articles, runs citation integrity, per slug with concurrency + backoff.", "owned_data": [ "blueprint_sources", "blueprint_seed_articles", "job status per slug", "integrity results" ], "entities": [ "SourceFile", "SeedArticle", "IntegrityReport", "JobState" ], "interfaces": [ "blueprintJobQueue API", "edge functions: fetch-blueprint-sources, generate-seed-articles, generate-blueprint-docs" ], "depends_on": [ "Cloud edge functions", "AI Gateway", "GitHub public read" ], "events_produced": [ "sources.fetched", "articles.generated", "integrity.completed", "cache.invalidated" ], "events_consumed": [ "blueprint.cache.invalidate" ], "failure_risks": [ "Edge IDLE_TIMEOUT on long generations (mitigated: per-doc endpoints + retries)", "Upstream AI 5xx storms" ], "scaling": "Concurrency + backoff configurable in UI; scales with edge function limits.", "future_split_trigger": "If cross-blueprint queueing coordination is needed, promote to a shared job service." }, { "name": "Runtime & Capabilities", "responsibility": "Per-blueprint runtime modules — verification, SEO, legal docs, chatbot — with retry + diagnostic history.", "owned_data": [ "capability status per slug", "runtime module errors", "chatbot threads + FAQ" ], "entities": [ "CapabilityStatus", "RuntimeError", "ChatMessage" ], "interfaces": [ "React Runtime tab", "edge functions: verify-blueprint, generate-seo-posts, generate-legal-docs/*, blueprint-chat" ], "depends_on": [ "Content Pipeline (grounding)", "AI Gateway" ], "events_produced": [ "capability.status.changed", "runtime.error.recorded" ], "events_consumed": [ "cache.invalidated" ], "failure_risks": [ "AI provider outage", "Prompt drift causing ungrounded output" ], "scaling": "Per-slug; independent of network size.", "future_split_trigger": "Split out Runtime & Capabilities into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Sync & Rollback", "responsibility": "Daily GitHub sync of blueprint definitions with dry-run, partial-apply, and server-backed rollback of last snapshot.", "owned_data": [ "sync_runs", "sync_snapshots per slug", "audit_trail" ], "entities": [ "SyncRun", "SyncDiff", "SyncSnapshot", "AuditEntry" ], "interfaces": [ "/github-sync page", "edge functions: github-sync-blueprints, rollback-blueprint-sync" ], "depends_on": [ "Blueprint Core", "Cloud storage for snapshots" ], "events_produced": [ "sync.run.completed", "sync.blueprint.applied", "sync.blueprint.rolled_back" ], "events_consumed": [], "failure_risks": [ "Partial apply leaving mixed state (mitigated by per-blueprint snapshots)", "Audit trail size growth" ], "scaling": "Paginate audit trail; snapshot retention window is finite.", "future_split_trigger": "Split out Sync & Rollback into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." }, { "name": "Design & Architecture DNA", "responsibility": "Deterministic per-blueprint design + architecture briefs used to gate release readiness.", "owned_data": [ "derived only — no persistence" ], "entities": [ "DesignDNA", "ArchitectureDNA" ], "interfaces": [ "React panels in Business Detail" ], "depends_on": [ "Blueprint Core" ], "events_produced": [], "events_consumed": [], "failure_risks": [ "Vertical → profile drift if new verticals are not mapped" ], "scaling": "Pure functions; free.", "future_split_trigger": "Split out Design & Architecture DNA into an independent deployment when its throughput or a distinct scaling profile justifies it; not warranted pre-revenue." } ], "data_architecture": { "primary_db": "Managed Postgres (Cloud)", "secondary": [ "Object storage for artifacts + snapshots", "Client localStorage for UI state (filters, drawer state) — never for auth" ], "cache": "React Query + module-level memoization; no dedicated cache service.", "search": "Postgres FTS on titles + evidence; consider pg_trgm on slugs.", "vector": "not applicable", "object_storage": "Per-slug prefixes; lifecycle rules to prune stale sync snapshots.", "schema_strategy": "Normalized core + JSONB for evolving shapes (evidence details, capability status).", "migrations": "Forward-only migrations reviewed in PR; every CREATE TABLE ships GRANTs + RLS enable + policies in the same migration.", "backups": "Managed daily backups with 30-day retention.", "retention": "Audit trail retained ≥ 1y; sync snapshots retained 90d; error diagnostics retained 30d.", "audit_logs": "audit_trail table + append-only pattern; export CSV from UI.", "soft_delete": "Soft-delete evidence via status transition; hard-delete only via owner-initiated purge.", "privacy": "Only owner-supplied facts persist; service records, attestations, regulator correspondence handled per vertical policy.", "encryption": "TLS 1.2+ in transit; AES-256 at rest via managed storage.", "multi_tenancy": "Row-level tenancy keyed on auth.uid() + blueprint slug; RLS policies enforce isolation." }, "api": { "style": "REST-ish RPC over edge functions with JSON payloads; typed client wrappers.", "public_vs_internal": "Public microsite reads via Postgres RLS-protected queries; internal capability calls via authenticated edge functions.", "versioning": "Version via function name suffix (v1, v2) when breaking; additive changes preferred.", "rate_limiting": "Per-user + per-slug in edge functions; UI-level concurrency caps for AI calls.", "idempotency": "Sync + rollback carry an idempotency key; retries safe.", "pagination": "Cursor pagination on audit trail; offset paging tolerated on small lists.", "error_format": "{ code, message, correlationId, retryable, details? } — normalized in client.", "webhook_security": "HMAC-signed webhooks (deferred until we accept inbound webhooks).", "retries": "Exponential backoff + jitter, capped attempts, respect idempotency keys.", "contract_testing": "Zod schemas shared between client + edge; smoke test runner exercises each endpoint.", "backward_compat": "Additive fields only; deprecations announced in audit trail before removal.", "contract_testing_plan": "Intake, source-result, and delivery payload schemas are contract-tested per consumer; the JSON contract between AI layers is schema-pinned and versioned." }, "security": { "authn": "Managed OAuth (Google default). Session in httpOnly cookie / managed client storage.", "authz": "user_roles table + has_role() SECURITY DEFINER, referenced from RLS policies. Never store roles on profiles.", "tenant_isolation": "RLS on every public table; every query filters by auth.uid() or by an explicit owner grant.", "secrets": "Managed vault; never in client bundle; edge functions read via runtime env.", "encryption": "TLS in transit; AES-256 at rest; column-level encryption only when regulation requires.", "session": "Short-lived access tokens + refresh rotation; SSR cookie parity for edge routes.", "input_validation": "Zod schemas at the edge boundary; reject on unknown fields.", "api_protection": "Rate limits + WAF rules on public endpoints; correlationId logging for abuse forensics.", "audit_log": "Every release decision, evidence toggle, sync, and rollback records actor + timestamp + before/after.", "admin_access": "Admin actions gated behind role check + two-key confirmation on destructive operations.", "supply_chain": "Lockfile pinning + weekly dependency scan; SBOM produced on release.", "threat_model": [ "Prompt injection via ingested source files → sanitize + refuse instructions from ingested content.", "Cross-tenant read via missing RLS on new table → migration checklist blocks merge.", "Rollback abuse to overwrite recent legitimate edits → rollback preview + confirm-typed pattern.", "AI cost DOS by repeated regeneration → per-slug rate limits + concurrency cap." ], "abuse_cases": [ "Malicious owner uploads privileged content into a public microsite field.", "Sync run tampered with to inject a slug that overlaps a real blueprint.", "Attacker triggers regeneration loop to drive AI cost." ], "zero_trust": "Every service call authenticates; no implicit trust between edge functions.", "asvs_notes": "OWASP ASVS L1 baseline." }, "reliability": { "failure_modes": [ "Edge function IDLE_TIMEOUT on long AI generations.", "Upstream AI provider 5xx / rate limit.", "GitHub API rate limit during sync.", "Postgres connection saturation during sync fan-out." ], "graceful_degradation": "Runtime tab modules degrade independently; microsite serves cached last-known-good content when generation fails.", "retry_policy": "Exponential backoff + jitter, max 5 attempts, respect Retry-After.", "timeouts": "Edge function ≤ 120s wall clock (safety margin under 150s limit); client fetch ≤ 60s per call.", "circuit_breaker": "Client-side per-endpoint breaker: after 3 consecutive IDLE_TIMEOUTs, pause 5m and surface to UI.", "queueing": "In-app blueprintJobQueue with concurrency limits per slug.", "idempotency": "Sync + rollback idempotent via key; generation endpoints idempotent per (slug, doc_key).", "dlq": "Failed jobs recorded in error diagnostics; user re-triggers manually (no auto-DLQ needed at current volume).", "transactions": "Multi-row writes wrapped in single transaction; audit entry written in the same transaction as the mutation.", "dr": "Daily backup + semi-annual restore drill.", "incident_response": "correlationId in every log line; on-call runbook per capability module; smoke test replays post-incident.", "slos": [ { "name": "Interactive p95", "target": "600 ms on blueprint detail" }, { "name": "Availability", "target": "99.5% (with March-reporting-window freeze protection)" }, { "name": "Sync success rate", "target": "≥ 99% per daily run over rolling 7 days" }, { "name": "Generation success rate", "target": "≥ 95% per doc across last 7d (excludes provider outages)" } ] }, "scaling": { "mvp_can_stay_simple": [ "Single Postgres, single region.", "No dedicated search or vector index.", "In-app job queue; no message broker." ], "modular_now": [ "Content Pipeline is already isolated behind blueprintJobQueue — future extraction is a 1-day job.", "Runtime capabilities are one function per module — swap in isolation." ], "deferrable": [ "Workflow engine (Temporal/Airflow).", "Vector DB / RAG.", "Multi-region replication.", "Feature flag service (env-based toggle covers MVP)." ], "breaks_first": "Edge function IDLE_TIMEOUT under multi-doc generation — already addressed by per-doc endpoints; watch for regression.", "db_path": "Vertical scale → read replica → partition by tenant if a single tenant dominates load.", "jobs_path": "In-app queue → dedicated worker → workflow engine, gated by concurrency + resumability need.", "cache_path": "React Query only → HTTP cache headers → CDN edge cache for microsite content.", "search_path": "Postgres FTS → pg_trgm → dedicated search only when p95 breaches SLO.", "files_path": "Managed object storage → CDN → per-region cache if traffic warrants.", "api_path": "Vertical edge function scale → per-capability autoscaling → extract hot module to its own service.", "multi_region": "Not planned; introduce only on customer contract with residency requirement.", "cost_control": "Per-blueprint AI budget, concurrency cap, smoke-test cache; monthly cost review with per-blueprint attribution." }, "ai": { "provider": "Frontier LLM via API with provider-agnostic prompt contracts; a second vendor is configured for failover so a released deliverable never depends on a single model.", "prompt_mgmt": "Extraction, drafting, and matrix prompts are held in versioned files with eval-gated deploys and one-step rollback; prompt changes require diff review.", "rag": "A versioned, jurisdiction-scoped rule pack for Healthcare / revenue cycle is retrieved with source-scoped filters; drafting is grounded and citation-anchored to the source text, never free-form generation.", "vector": "Not warranted pre-revenue — the rule pack is small and structured, so section/keyword lookups suffice until a larger corpus justifies similarity search.", "embeddings": "Deferred with the vector store; rule-pack keys are structured (element, source, subsection), not semantic.", "eval": "A gold set of specialist-released packs measures element-extraction F1 and completeness-gate agreement per model release; accuracy vs specialist labels is reviewed on a fixed cadence.", "hitl": "Specialist release is never automated; a domain expert signs off on the exception queue, with sampling QA on a fraction of outputs and expert red-team on the first releases.", "guardrails": "Field-locked templates, source-tie reconciliation, and completeness rules mean a draft missing a required field emits a MISSING_ELEMENT exception rather than inventing content.", "prompt_injection": "Source documents are treated as data, never instructions; the red-team suite includes injected-instruction files disguised as legitimate inputs.", "leakage": "Client and subject identifiers are scoped per case; retrieval is scoped per client; provider training-use is disabled; there is no cross-client corpus.", "fallback": "A manual specialist workbench runbook plus the second LLM vendor keep production moving if the primary model is unavailable.", "latency_cost": "Inference cost per deliverable is bounded at launch and trends down with volume; the standard SLA leaves generous headroom over model latency.", "memory": "Agents are stateless per case; durable knowledge lives in the versioned rule pack and SOP library, not in model memory.", "tool_permissions": "The prompt runner has no tool access beyond returning JSON; search ordering, document assembly, and delivery are deterministic code.", "auditability": "Every prompt+output pair is logged to the per-case audit trail with version tags alongside the specialist release record.", "citation": "Every drafted element carries the source provision it satisfies, and every matrix entry carries the search or record it came from." }, "devops": { "environments": [ "Preview (per branch)", "Production" ], "cicd": "Lovable build pipeline; deploys on merge; edge functions ship atomically with the app.", "iac": "Cloud managed; migrations + config in-repo.", "secrets": "Managed vault; separate values per environment.", "preview_envs": "Automatic per branch; seeded with anonymized fixtures.", "migrations": "Forward-only; migrations reviewed for GRANT + RLS + policies; every table gated by the migration checklist.", "rollback": "App: redeploy previous build. Data: server-backed rollback per blueprint via rollback-blueprint-sync.", "release_style": "Continuous deploy with feature flags; canary only when a change touches shared shell.", "feature_flags": "Env-based booleans at MVP; consider a flag service when we have > 20 flags in flight.", "monitoring": "Cloud platform metrics + per-function logs + client error reporting.", "alerting": "SLO burn-rate alerts + IDLE_TIMEOUT rate alert + AI cost anomaly alert.", "logs": "Structured JSON with correlationId; retained per platform defaults.", "error_tracking": "Client-side error capture wired to console + in-app diagnostics drawer.", "uptime": "Synthetic checks on microsite + shell login every 5 minutes.", "cost_monitoring": "Per-blueprint cost view; alert on 3x baseline over 24h." }, "testing": { "unit": "Vitest for pure derivations (DNA, business helpers).", "integration": "Edge function contract tests with recorded fixtures.", "contract": "Zod schemas shared client + edge; smoke test runner as continuous contract check.", "e2e": "Playwright against localhost preview for critical flows (sign in, evidence toggle, sync apply).", "security": "Weekly dependency scan; RLS policy audit script; abuse-case checklist per release.", "a11y": "Axe checks + keyboard-only smoke on shell components; WCAG 2.2 AA target.", "load": "k6 scenarios against edge functions before enabling a new capability network-wide.", "chaos": "Manual fault injection on AI provider (simulate 500s) during release rehearsal.", "migration": "Every migration runs in preview + dry-run on prod snapshot before apply.", "backup_restore": "Semi-annual restore drill.", "ai_eval": "not applicable", "test_data": "Deterministic fixtures per vertical; no real PHI/PII ever in fixtures." }, "observability": { "logs": "Structured JSON with correlationId, phase, attempt, doc_key, slug.", "metrics": "Per-endpoint latency, error rate, retry count, AI token spend.", "traces": "Cross-function trace via correlationId propagation.", "audit_events": "Release decision, evidence toggle, sync, rollback, cache invalidation.", "business_events": "Blueprint promoted to ready, first microsite view, first customer-visible export.", "error_tracking": "In-app diagnostics drawer + persistent per-slug error history.", "security_monitoring": "Failed auth + rate-limit breach + admin action logs.", "cost_monitoring": "Per-blueprint + per-capability cost attribution.", "dashboards": [ "SLO burn", "AI cost per blueprint", "Sync success rate", "Generation success rate" ], "alert_thresholds": [ "IDLE_TIMEOUT rate > 3/day for one blueprint.", "Sync run failure > 1 in rolling 7 days.", "AI cost > 3x rolling 7-day baseline over 24h.", "p95 breach on Blueprint detail > 800ms for 15 min." ], "triage": "correlationId → diagnostics drawer → retry timeline → JSON report export → runbook link." }, "cost": { "drivers": [ { "name": "AI generation", "note": "Dominant driver; capped by concurrency + per-slug budget." }, { "name": "Edge function invocations", "note": "Bursty at sync + generation; idle-to-zero otherwise." }, { "name": "Managed Postgres", "note": "Small; scales with audit trail retention." }, { "name": "Object storage", "note": "Snapshots + artifacts; lifecycle rules prevent growth." }, { "name": "Bandwidth", "note": "Low; static microsite content." } ], "likely_traps": [ "Regeneration loops on failure (mitigated by circuit breaker).", "Audit trail unbounded growth (mitigated by retention policy).", "Storing large HTML snapshots per sync (mitigated by delta snapshots)." ], "controls": [ "Per-blueprint AI budget with hard cap.", "Smoke-test result caching in localStorage.", "Concurrency cap in blueprintJobQueue.", "Retention policy on audit + diagnostics." ] }, "multi_tenancy": { "model": "Row-level tenancy: one shared Postgres, tenant scope by auth.uid() + blueprint slug.", "isolation": "RLS policies on every public table; policies reference has_role() where role checks are needed.", "tenant_aware_authz": "Every query filters by auth.uid(); admin overrides go through explicit role check + audit entry.", "tenant_config": "Per-slug config stored as JSONB on the blueprint row; no per-tenant deploy.", "branding": "Per-blueprint Design DNA drives theme; no runtime branding upload at MVP.", "tenant_export": "Owner can export evidence + audit trail as JSON/CSV from the UI.", "tenant_deletion": "Owner-initiated purge cascades across blueprint rows + storage prefix; soft-delete window of 30 days.", "tenant_audit": "Per-slug audit trail table view with actor + timestamp on every mutation.", "noisy_neighbor": "Per-slug concurrency cap in blueprintJobQueue; per-slug AI budget.", "tenant_rate_limits": "Edge functions apply per-slug + per-user rate limits.", "billing": "Not billed at MVP; per-blueprint cost attribution feeds the future billing model.", "why_this_fits": "Team size and blueprint scale don't justify schema/db-per-tenant; RLS covers the isolation requirement with negligible ops burden." }, "privacy_compliance": { "data_classification": "Owner-supplied facts and evidence citations are the sensitive classes; service records, attestations, regulator correspondence per vertical.", "minimization": "Only owner-supplied facts persist; no third-party enrichment; no PII scraping.", "consent": "Consent captured at intake for owner-supplied contact info; microsite visitors get standard cookie/consent banner where required.", "access_logs": "Every admin + edge function invocation logged with correlationId + actor.", "audit_trails": "Immutable append-only audit_trail table; export from UI.", "retention": "Audit ≥ 1y; sync snapshots 90d; error diagnostics 30d; artifacts per lifecycle rule.", "legal_hold": "Deferred until a matter requires it.", "right_to_delete": "Owner-initiated purge honored within 30 days; downstream copies pruned by lifecycle rules.", "right_to_export": "JSON + CSV export for evidence, audit trail, and generated artifacts.", "sensitive_handling": "No PHI/PII in prompts; owner-supplied facts only; secrets in managed vault.", "boundaries": "Domain-specific (claims-authorization records, reviewer attestations, retention schedules)", "residency": "Single region at MVP; residency contract triggers per-tenant residency planning.", "vendor_risk": "Lovable Cloud + AI Gateway are the only critical vendors; both reviewed for security posture.", "breach_response": "correlationId + audit trail enables scope determination; disclosure per compliance policy within statutory window.", "admin_controls": "Admin actions gated by role check + two-key confirm for destructive operations; every admin session logged.", "evidence_collection": "Access reviews, change management, restore drills produce artifacts filed into the evidence pipeline." }, "frontend": { "framework": "React 18 + Vite + TypeScript.", "rendering": "SPA with per-route code-split; microsite routes prerender-friendly.", "routing": "react-router-dom v6 with URL-persisted filter/drawer state.", "state": "React context + useSyncExternalStore for the job queue; localStorage only for UI state, never for auth.", "server_state": "@tanstack/react-query for cache + retries.", "forms": "Controlled components + Zod validation on submit; RHF only where forms grow.", "error_handling": "Error boundary at shell + per-panel skeletons + retry affordances.", "components": "shadcn primitives + per-blueprint themed panels; deterministic Design DNA drives look.", "design_system": "Tailwind semantic tokens (index.css); no hardcoded color utilities in components.", "auth_ui": "Managed OAuth callback via Cloud client; session hydration before protected routes render.", "authz_aware_ui": "UI hides actions the current role cannot perform; server-side check is authoritative.", "a11y": "WCAG 2.2 AA target; visible focus rings; keyboard shortcuts in diagnostics drawer.", "i18n": "Copy budgets assume +35% expansion for DE/FR; Intl APIs for dates/currencies.", "performance": "Route-level code split; lazy-load Runtime tab; memoize DNA derivations.", "bundling": "Vite defaults; per-route lazy imports for heavy panels.", "testing": "Vitest for unit; Playwright for critical flows.", "offline": "Not required; last-known-good served from React Query cache.", "realtime": "Not required at MVP; audit trail is polled on interaction." }, "backend": { "framework": "Deno-based edge functions on Lovable Cloud, one function per capability.", "layering": "Handler → validator (Zod) → service → repository → Postgres.", "domain": "Blueprint, Evidence, OwnerAction, SyncRun, RuntimeCapability, ChatMessage.", "services": "Pure functions kept out of edge boundary; shared logic imported from a common module.", "repositories": "Thin Postgres wrappers; RLS enforces tenant scope.", "validation": "Zod at the edge boundary; reject unknown fields.", "authorization": "has_role() SECURITY DEFINER in Postgres; edge function also asserts role for defense in depth.", "jobs": "In-app blueprintJobQueue on the client for user-triggered pipelines; server-side cron only for daily sync.", "events": "Domain events emitted to audit_trail; no external broker.", "files": "Signed URLs from Cloud Storage; virus scan on upload (deferred until user uploads exist).", "email_sms": "Deferred; owner-configured inbox required before enabling outbound mail.", "scheduled": "Daily GitHub sync via scheduled function; retention prune weekly.", "errors": "Normalized error envelope { code, message, correlationId, retryable, details? }.", "logging": "Structured JSON logs with correlationId, phase, attempt, slug.", "config": "Env-based; secrets from managed vault.", "di": "Not required at current size; explicit imports.", "testing": "Contract tests per function with recorded fixtures + smoke-test runner." }, "diagrams": { "context_mermaid": "flowchart LR\n Owner([Blueprint Owner]) --> Shell[Network Shell]\n Reviewer([Reviewer]) --> Shell\n Public([Public Visitor]) --> Micro[Public Microsite veterinary-insurance-claims-case-acceptance-desk]\n Shell --> Cloud[(Lovable Cloud: DB + Auth + Storage + Edge)]\n Cloud --> AI[[AI Gateway]]\n Cloud --> GH[[GitHub API]]\n Micro --> Cloud", "container_mermaid": "flowchart TB\n subgraph Client\n UI[React Shell + Blueprint Detail]\n Queue[blueprintJobQueue]\n end\n subgraph Cloud[Lovable Cloud]\n DB[(Postgres + RLS)]\n Store[(Object Storage)]\n subgraph Edge[Edge Functions]\n Sync[github-sync-blueprints]\n Roll[rollback-blueprint-sync]\n Src[fetch-blueprint-sources]\n Seed[generate-seed-articles]\n Docs[generate-blueprint-docs]\n Legal[generate-legal-docs/*]\n Verify[verify-blueprint]\n SEO[generate-seo-posts]\n Chat[blueprint-chat]\n end\n end\n UI --> DB\n Queue --> Src\n Queue --> Seed\n UI --> Docs\n UI --> Legal\n UI --> Verify\n UI --> SEO\n UI --> Chat\n UI --> Sync\n UI --> Roll\n Seed --> AI[[AI Gateway]]\n Docs --> AI\n Legal --> AI\n Chat --> AI\n Src --> GH[[GitHub]]", "data_flow_mermaid": "flowchart LR\n A[Owner edits Evidence] --> B[Store: evidence.custom]\n B --> C{Release Gate}\n C -- ready --> D[Business marked Ready]\n C -- blocker --> E[Owner Actions queue]\n F[GitHub Sync] --> G[Diff + Snapshot]\n G --> H[(Postgres)]\n H --> I[Audit trail]\n H --> J[React store]", "auth_flow_mermaid": "sequenceDiagram\n participant U as User\n participant UI as Network Shell\n participant Auth as Cloud Auth\n participant API as Edge Function\n participant DB as Postgres+RLS\n U->>UI: sign in\n UI->>Auth: OAuth (Google)\n Auth-->>UI: session (JWT)\n UI->>API: call with JWT\n API->>DB: query as auth.uid()\n DB-->>API: rows filtered by RLS\n API-->>UI: response", "authz_flow_mermaid": "flowchart LR\n Req[Request w/ JWT] --> Fn[Edge Function]\n Fn --> Role[has_role user_id, role]\n Role --> DB[(user_roles + RLS policies)]\n DB -- allow --> Ok[Return rows]\n DB -- deny --> Err[403 + audit entry]", "deployment_mermaid": "flowchart LR\n Dev[Developer] --> Repo[Git]\n Repo --> CI[Lovable Build]\n CI --> Preview[Preview Env]\n CI --> Prod[Production]\n Prod --> Cloud[(Lovable Cloud)]\n Prod --> CDN[[Edge CDN]]", "background_job_mermaid": "flowchart LR\n UI[Blueprint Detail] --> Enq[blueprintJobQueue.enqueue]\n Enq --> Slot{Concurrency slot?}\n Slot -- yes --> Run[Run job]\n Slot -- no --> Queued[queued]\n Run -->|success| Done[Persist result + emit event]\n Run -->|error| Back[Exponential backoff + jitter]\n Back -->|attempts left| Run\n Back -->|exhausted| Fail[Record diagnostic + expose retry button]", "event_flow_mermaid": "flowchart LR\n Sync[sync.blueprint.applied] --> Core[Blueprint Core]\n Integ[integrity.completed] --> UI\n CacheInv[cache.invalidated] --> Pipe[Content Pipeline]\n Pipe --> Sources[sources.fetched]\n Sources --> Articles[articles.generated]\n Articles --> Integ", "failure_flow_mermaid": "flowchart LR\n Call[Edge Function call] --> Timeout{Timeout / 5xx?}\n Timeout -- no --> Ok[Success]\n Timeout -- yes --> Retry[Backoff + retry]\n Retry --> Cap{Attempts cap?}\n Cap -- no --> Call\n Cap -- yes --> Breaker[Open circuit]\n Breaker --> Cache[Serve last-known-good]\n Breaker --> Owner[Surface diagnostic + owner action]", "multi_tenant_flow_mermaid": "flowchart LR\n Owner1([Owner A]) --> UI\n Owner2([Owner B]) --> UI\n UI --> API[Edge Function w/ JWT]\n API --> Policy{RLS: auth.uid + slug scope}\n Policy -- match --> Rows[Owner-scoped rows]\n Policy -- no match --> Deny[403]", "ai_flow_mermaid": "graph LR; SRC[Source documents as DATA]-->EX[Extract + normalize]-->SR[Order source searches]-->MTX[Build matrix]-->DR[Draft locked-field elements]-->GT[Deterministic completeness gates]-->SP[Specialist release]-->DL[Deliver]; GT-.exception.->SP; SP-.high-risk.->EXP[Expert review]" }, "adrs": [ { "id": "ADR-001", "decision": "Adopt modular monolith as the network-wide architecture style", "context": "Small team maintaining many blueprints with shared shell, evidence discipline, and per-vertical trust variation.", "options": [ "simple monolith", "modular monolith", "microservices", "serverless-only", "hybrid" ], "chosen": "modular monolith", "why": "Preserves a single audit boundary and deploy cadence while allowing edge functions for burst workloads.", "consequences": [ "Shared deploy lifecycle across blueprints", "Row-level tenant isolation carries the security load" ], "risks": [ "A rogue blueprint can regress network shell performance" ], "reversal": "Extract a module to its own deploy only when its SLO diverges from the network shell.", "revisit_when": "A blueprint acquires a divergent SLO, a second team joins, or the shell deploy time exceeds 10 minutes." }, { "id": "ADR-002", "decision": "Managed Postgres as the sole primary datastore", "context": "All entities are relational (blueprints, evidence, sync runs, articles, audit).", "options": [ "Postgres", "Postgres + DocumentDB", "Postgres + vector DB", "Firestore" ], "chosen": "Postgres (Cloud managed) with JSONB for semi-structured fields", "why": "Relational integrity + row-level security satisfies audit, tenancy, and reporting; JSONB absorbs shape drift.", "consequences": [ "RLS policies are the primary tenancy control", "Full-text search via Postgres FTS until it stops scaling" ], "risks": [ "Complex joins under growth" ], "reversal": "Introduce a read-replica or a dedicated search index only when p95 breaches SLO.", "revisit_when": "FTS p95 > SLO for 2 consecutive weeks, or a genuine RAG surface appears." }, { "id": "ADR-003", "decision": "Per-document edge functions for long-running AI generation", "context": "IDLE_TIMEOUT (150s) on monolithic legal-docs generator forced this split.", "options": [ "Single long function", "Chunked per-doc functions", "Background job with polling" ], "chosen": "Per-document endpoints with client-side fan-out + retries", "why": "Keeps each invocation under the timeout, isolates failures, enables partial success reporting.", "consequences": [ "More endpoints to maintain", "Client must own orchestration" ], "risks": [ "Client back-pressure if fan-out is too wide" ], "reversal": "Move to a real workflow engine when we cross ~10 concurrent long jobs per blueprint.", "revisit_when": "Concurrent long-running jobs > 10 per blueprint, or client-side orchestration becomes buggy." }, { "id": "ADR-004", "decision": "Evidence-first release gate", "context": "Vertical compliance posture: Domain-specific (claims-authorization records, reviewer attestations, retention schedules).", "options": [ "Owner-declared ready", "Auto-ready via checklist", "Evidence-gated ready" ], "chosen": "Evidence-gated ready — release requires resolved owner actions + verified evidence", "why": "Regulated verticals cannot ship on self-declaration; evidence provides defensibility.", "consequences": [ "Slower path to ready", "Higher confidence at ready" ], "risks": [ "Owners abandon incomplete blueprints" ], "reversal": "Introduce a 'ready-with-caveats' state only if the network stalls on this gate.", "revisit_when": "> 30% of blueprints stuck in owner-action state for > 30 days." }, { "id": "ADR-005", "decision": "Defer AI adoption until a specific evidence-generation need arises", "context": "AI is powerful but adds cost, latency, and auditability burden.", "options": [ "No AI", "Grounded AI only", "Agentic AI" ], "chosen": "No AI in this vertical", "why": "Vertical does not currently justify AI-shaped complexity.", "consequences": [ "No prompt catalog to maintain" ], "risks": [], "reversal": "Introduce AI only for a scoped generation task.", "revisit_when": "A specific generation task appears with clear source grounding." }, { "id": "ADR-006", "decision": "Managed OAuth (Google) with roles in a dedicated user_roles table", "context": "Storing roles on the profile row invites privilege-escalation bugs; RLS policies must reference a stable role source.", "options": [ "Roles on profiles", "user_roles + has_role() SECURITY DEFINER", "External IdP with JIT claims" ], "chosen": "user_roles table + has_role() SECURITY DEFINER, referenced by RLS", "why": "Prevents recursive RLS, isolates authz decisions, satisfies audit review.", "consequences": [ "One extra join in policies", "Explicit role grants required" ], "risks": [ "Role drift if grants are not audited" ], "reversal": "Swap SECURITY DEFINER function for an IdP claim without changing policies.", "revisit_when": "Enterprise SSO / SAML contract signed, or role count exceeds ~10." }, { "id": "ADR-007", "decision": "Single-tenant per blueprint slug with row-level isolation", "context": "Blueprints share infra but must never cross-read evidence, sync history, or generated artifacts.", "options": [ "Shared DB + RLS", "Schema-per-tenant", "DB-per-tenant" ], "chosen": "Shared DB + RLS keyed on auth.uid() and blueprint slug", "why": "Simplest operable model at current scale; migration cost stays near zero.", "consequences": [ "RLS is load-bearing security" ], "risks": [ "A missing policy = a leak" ], "reversal": "Extract a specific tenant to its own schema when contract requires it.", "revisit_when": "First enterprise customer with a residency or dedicated-DB clause." } ], "roadmap": [ { "phase": "MVP", "build": [ "Network shell + Blueprint Core module", "Content Pipeline with concurrency + backoff", "Design + Architecture DNA per blueprint", "Sync + rollback + audit trail" ], "avoid": [ "Any per-blueprint deploy pipeline", "Message brokers", "Vector DBs", "Multi-region" ], "defer": [ "A workflow engine", "Full-text search infra", "Dedicated CDN rules" ], "monitor": [ "Edge function IDLE_TIMEOUT rate", "AI cost per generation", "Duplicate-slug regressions" ], "triggers_to_change": [ "p95 breach on Blueprint detail > 800ms", "≥ 3 IDLE_TIMEOUTs/day sustained" ], "acceptable_debt": [ "Client-owned job orchestration", "localStorage-backed UI state" ], "dangerous_debt": [ "Missing RLS on any public table", "Ungrounded AI in customer-visible surfaces" ] }, { "phase": "Stabilization", "build": [ "Automated smoke test per blueprint on cache invalidation", "Per-slug retention + audit trail export", "Contract tests for every edge function" ], "avoid": [ "Premature module extraction" ], "defer": [ "Multi-tenant admin console" ], "monitor": [ "SLO burn rate", "Cost per blueprint per week" ], "triggers_to_change": [ "A single blueprint accounts for > 30% of AI spend" ], "acceptable_debt": [ "Manual runbook execution for rare failures" ], "dangerous_debt": [ "Untested rollback path", "Backups without a restore drill" ] }, { "phase": "Growth", "build": [ "Optional workflow engine adapter behind the current queue interface", "Read replica for Postgres if analytics queries interfere", "Feature flags per capability module" ], "avoid": [ "Splitting Blueprint Core into services without SLO justification" ], "defer": [ "Real-time collaboration" ], "monitor": [ "Fan-out concurrency vs edge function limits" ], "triggers_to_change": [ "> 10 concurrent long jobs per blueprint", "New team joins with independent release cadence" ], "acceptable_debt": [ "Env-based feature flags" ], "dangerous_debt": [ "Skipping migration reviews", "Unaudited role grants" ] }, { "phase": "Scale", "build": [ "Extract Content Pipeline to a dedicated service if it dominates deploys", "Search index (Postgres FTS → dedicated) once FTS p95 breaches SLO" ], "avoid": [ "Microservices per blueprint" ], "defer": [ "Multi-region until a customer contract requires it" ], "monitor": [ "DB CPU + IO under peak", "Search p95" ], "triggers_to_change": [ "Regional compliance contract signed" ], "acceptable_debt": [ "Single-region deployment" ], "dangerous_debt": [ "Unbounded audit trail growth", "Missing DR drill evidence" ] }, { "phase": "Enterprise/Compliance", "build": [ "Formal SOC 2 evidence pipeline (access reviews, change management)", "Tenant-scoped encryption keys where regulation requires", "DR drill quarterly with restore proof" ], "avoid": [ "Custom compliance frameworks; ride managed platform attestations" ], "defer": [ "FedRAMP unless a customer commits" ], "monitor": [ "Access review completion", "Restore-test success rate" ], "triggers_to_change": [ "Signed contract with SOC 2 clause", "PHI/PII scope change" ], "acceptable_debt": [ "Manual quarterly access review with checklist" ], "dangerous_debt": [ "Ad-hoc admin access without approval trail" ] } ], "anti_overengineering": { "flagged": [ { "item": "Introducing Kubernetes", "why": "Team size + workload shape don't justify it.", "simpler": "Managed Cloud primitives." }, { "item": "Adopting microservices", "why": "Single deploy cadence + shared audit boundary.", "simpler": "Modular monolith with edge functions." }, { "item": "Adopting a vector DB", "why": "Sources are small + structured; deterministic retrieval works.", "simpler": "Direct source fetch + Postgres FTS." }, { "item": "Adopting event sourcing", "why": "Audit trail table already provides the needed reconstructibility.", "simpler": "Append-only audit_trail + snapshots." }, { "item": "Multi-region from day one", "why": "No customer contract requires it.", "simpler": "Single region + documented DR plan." }, { "item": "Custom workflow engine", "why": "In-app queue covers current concurrency needs.", "simpler": "blueprintJobQueue with backoff." }, { "item": "Premature message queue", "why": "In-app queue + audit trail cover the fan-out cases.", "simpler": "Keep blueprintJobQueue; revisit at 10x volume." }, { "item": "Custom auth", "why": "Managed OAuth + user_roles cover the model.", "simpler": "Cloud Auth + user_roles table." }, { "item": "Premature caching layer", "why": "React Query covers the read-heavy paths.", "simpler": "React Query + HTTP cache headers." }, { "item": "Data warehouse", "why": "No analytics contract; Postgres analytics queries suffice.", "simpler": "Read replica if the primary is hurt." } ] }, "risks": [ { "risk": "Edge function IDLE_TIMEOUT on long generations", "likelihood": "moderate", "impact": "high", "mitigation": "Per-document endpoints + client-side retries with exponential backoff.", "detection": "Smoke test runner + diagnostics drawer flags IDLE_TIMEOUT.", "owner": "engineering", "escalation": "Sustained > 3/day for one blueprint → open incident.", "fallback": "Fall back to last-known-good cached artifact; pause auto-generation for the affected blueprint.", "category": "technical" }, { "risk": "Duplicate slugs in SEED causing UI regressions", "likelihood": "moderate", "impact": "moderate", "mitigation": "mergedSeed dedupes by slug; add lint on SEED at build time.", "detection": "React duplicate-key warning; per-slug uniqueness assertion in tests.", "owner": "engineering", "escalation": "Ship-block if reproduced on main.", "fallback": "Runtime dedupe in mergedSeed keeps first occurrence.", "category": "technical" }, { "risk": "Ungrounded AI output shipped to microsite", "likelihood": "low", "impact": "high", "mitigation": "Citation-first prompts; integrity check gates Seed Articles view.", "detection": "Integrity report failing count > 0 blocks display.", "owner": "engineering", "escalation": "Any customer-visible ungrounded claim → rollback the blueprint.", "fallback": "Auto-hide the article + surface owner action to regenerate with stricter prompt.", "category": "product" }, { "risk": "Cross-tenant data leak via missing RLS on new table", "likelihood": "low", "impact": "critical", "mitigation": "Every CREATE TABLE ships with GRANT + ENABLE RLS + policies in the same migration.", "detection": "Security scanner + migration checklist.", "owner": "engineering", "escalation": "Immediate lockdown + audit.", "fallback": "Revoke Data API grants on affected table; restore from PITR if data was modified.", "category": "security" }, { "risk": "AI cost runaway on a single blueprint", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-slug rate limits + smoke-test cache + concurrency cap in UI.", "detection": "Cost monitoring dashboard; per-blueprint spend alert at 3x baseline.", "owner": "SRE", "escalation": "Auto-pause generation; require manual re-enable.", "fallback": "Disable AI for the offending blueprint via feature flag; serve last-known-good.", "category": "cost" }, { "risk": "AI provider outage or model deprecation", "likelihood": "moderate", "impact": "moderate", "mitigation": "Per-capability fallback model + retry with backoff; abstract via Lovable AI Gateway.", "detection": "Elevated 5xx or empty completions; smoke test failing across blueprints.", "owner": "engineering", "escalation": "Sustained > 30 min → switch fallback model; notify owners.", "fallback": "Serve cached artifacts + disable AI-only capabilities until restored.", "category": "vendor" }, { "risk": "Compliance evidence gap during audit", "likelihood": "low", "impact": "high", "mitigation": "Evidence-first release gate + audit trail export from UI.", "detection": "Missing audit entries surfaced in periodic reconciliation report.", "owner": "legal", "escalation": "Regulator-visible gap → incident + disclosure per policy.", "fallback": "Freeze affected blueprint's release state; produce backfill evidence pack.", "category": "compliance" }, { "risk": "Solo/small-team key-person dependency", "likelihood": "moderate", "impact": "high", "mitigation": "Deterministic DNA modules keep decisions in code, not in one head; runbooks per capability.", "detection": "Bus-factor review each quarter.", "owner": "owner", "escalation": "> 1 critical path with no backup → hire or contract.", "fallback": "Freeze non-critical changes; document current state before further work.", "category": "team" }, { "risk": "Audit trail gaps on release decisions", "likelihood": "low", "impact": "critical", "mitigation": "Every mutation writes audit entry in the same transaction.", "detection": "Audit trail row count vs mutation count reconciliation.", "owner": "engineering", "escalation": "Regulator-visible gap → incident + disclosure.", "fallback": "Reconstruct from Postgres WAL + application logs; disclose per compliance policy.", "category": "compliance" } ], "rules": [ "Keep business logic out of UI components — derivations live in lib/*, panels only render.", "Do not introduce a new service without a clear owner and a scaling reason.", "All external integrations must have retries, timeouts, and failure handling.", "All sensitive actions must be auditable in the same transaction that performs them.", "All background jobs must be idempotent.", "All APIs must return the normalized error envelope.", "All tenant-scoped queries must enforce tenant isolation via RLS — never trust the client.", "All expensive AI calls must be logged, capped, and observable.", "All schema changes must be reversible or safely migratable — no destructive drops without a rollout plan.", "All critical workflows must have observability: correlationId, phase timings, retry timeline.", "Every public table ships with GRANT + ENABLE RLS + policies in the same migration.", "Every AI span carries a citation; no citation, no ship.", "Every destructive action requires typed confirmation." ], "audit": { "product_fit": "Architecture matches an evidence-first, regulated-adjacent workflow product per blueprint.", "simplicity": "One shell, one DB, edge functions for bursts — near the simplicity floor for the product's ambitions.", "security": "RLS + role table + audit trail; meets ASVS L1 baseline.", "reliability": "SLOs defined; per-module degradation; retries + diagnostics in place.", "scalability": "Horizontal by blueprint count is the growth axis; per-blueprint scaling is comfortably in headroom.", "maintainability": "Deterministic derivations (Design DNA, Architecture DNA) keep per-vertical drift out of components.", "performance": "p95 target 600ms is realistic on Cloud edge with warm cache.", "cost": "Idle-to-zero for cold blueprints; per-blueprint attribution keeps AI spend controllable.", "compliance": "Domain-specific (claims-authorization records, reviewer attestations, retention schedules)", "dx": "Single stack (React + Vite + Tailwind + Cloud); new blueprint reaches microsite state in one session.", "ops_burden": "Managed platform absorbs infra ops; SRE work is limited to SLO watch + runbooks.", "extensibility": "New capability = new edge function + new Runtime tab entry; no shell changes required.", "team_suitability": "Fits a small team; every added component must retire an older one.", "time_to_market": "New blueprint reachable to validation-microsite state within one working session.", "recommendation": { "style": "modular monolith", "stack": "React + Vite + TypeScript + Tailwind + shadcn on the client; Deno edge functions + managed Postgres (RLS) + object storage on the server; Lovable AI Gateway (unused in this vertical).", "hosting": "Lovable Cloud managed hosting; preview + production environments; edge functions co-deploy with the app.", "database": "Managed Postgres with RLS + JSONB; PITR enabled for critical-tier tenants.", "auth": "Managed OAuth (Google default) + user_roles table + has_role() SECURITY DEFINER referenced from RLS policies.", "integrations": "GitHub (public read) for sync + sources; Lovable AI Gateway for LLM calls; Cloud Storage for artifacts. No third-party CRM/email/SMS at MVP.", "ai_approach": "No AI at MVP for this vertical; revisit only when a scoped generation task with clear sources appears.", "build_first": [ "Blueprint Core (evidence + release gate) — vertical-agnostic.", "Content Pipeline (sources → articles → integrity) — required for any evidence claim.", "Sync + rollback — required to safely onboard the network." ], "avoid": [ "Any per-blueprint deploy pipeline.", "Autonomous AI agents that mutate data without owner confirmation.", "Bespoke workflow engines before the in-app queue is exhausted." ], "revisit_later": [ "Workflow engine adoption when > 10 concurrent long jobs per blueprint.", "Search index dedicated infra when Postgres FTS p95 breaches SLO.", "Multi-region on the first residency-bound contract." ], "biggest_risks": [ "Missing RLS on a new public table (critical).", "Ungrounded AI output reaching a customer-visible surface.", "AI cost runaway on a single blueprint.", "Solo/small-team key-person dependency." ], "first_10_steps": [ "Confirm managed OAuth + user_roles table + has_role() function are in place.", "Enable RLS + policies on every existing public table; add the migration checklist to CI.", "Wire correlationId end-to-end across every edge function call.", "Ship the smoke test runner as a required post-deploy gate.", "Enable PITR + schedule the first restore drill on the calendar.", "Add per-slug AI budget caps and cost dashboards.", "Enforce evidence-first release gate for every blueprint.", "Set SLO burn-rate alerts on the top 3 SLIs.", "Document the per-capability runbook (retry, cancel, invalidate).", "Publish this Architecture DNA per blueprint as part of the release evidence pack." ], "top_10_rules": [ "Every public table ships with GRANT + RLS + policies in the same migration.", "Every mutation writes an audit entry in the same transaction.", "Every AI span carries a citation; no citation, no ship.", "Every long AI call is per-item, never monolithic.", "Every edge function call carries a correlationId end-to-end.", "Every retry uses exponential backoff + jitter with a hard attempt cap.", "Every destructive action requires typed confirmation.", "No microservice extraction without a divergent SLO.", "No new dependency without a supply-chain scan.", "Signature element (Pack-register tabs with regime chip) and accent (clinical-teal) are network invariants — respect them." ] } } }, "design": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "archetypes": [ "healthcare-adjacent workflow tool", "claims-operations system", "financial-administration back office" ], "user_mindset": { "goals": "Get an insured client's claim submitted complete and on time, without becoming an insurance expert.", "session_length": "Bursty around insured-client visits; otherwise a weekly-digest review of open claims.", "confidence": "Practical, time-pressed users; will not tolerate a portal that takes longer to operate than doing the paperwork themselves.", "interface_needs": "Fast status scanning, plain-language claim states, clear next-action per claim." }, "posture": [ "warm", "trustworthy", "operational" ], "density": "comfortable", "trust_level": { "tier": "high", "sensitive_domains": [ "client medical-record excerpts", "itemized invoice data", "claims-authorization records" ], "implications": [ "Every destructive action confirmed with typed intent, never a single-click.", "Errors carry remediation copy + owner, not just a message.", "Focus rings visible on every interactive element (WCAG 2.2 AA minimum).", "Named claims reviewer on every submitted claim.", "Explicit unsaved-changes gate on nav." ] }, "differentiation": { "avoid": [ "Material Design defaults", "shadcn stock look (unstyled cards + slate ring)", "Purple/indigo gradient heroes", "Stripe/Linear/Notion mimicry", "Vertical cliché: paw-print clip-art and alarm-red penalty banners" ], "strategy": "Anchor on the claim-status chip (submitted / pending / past-window / needs-input) as the recurring signature element; every page must include it at least once. Reserve the warm amber accent for action/CTA and status signals only." }, "territories": [ { "name": "Claim Desk", "color_mood": "clinical teal + warm parchment", "typography": "Charter/Iowan Old Style serif + system sans", "density": "comfortable card grid", "component_feel": "front-desk claim tracker", "motion": "none (static, print-parity)", "fits": "practice-manager daily use", "risks": "could read as generic healthcare SaaS without the warm accent" }, { "name": "Portfolio Atlas", "color_mood": "map ink + civic navy", "typography": "Neue Haas Grotesk", "density": "map-driven", "component_feel": "multi-location DSO atlas", "motion": "map pan", "fits": "multi-location portfolios", "risks": "requires multi-location data not present at launch" }, { "name": "Claim-Window Timeline", "color_mood": "slate + amber", "typography": "Inter", "density": "timeline", "component_feel": "gantt of open claims", "motion": "scroll-sync", "fits": "recurring visit/claim cadence", "risks": "gantt fatigue for small practices" } ], "chosen_territory": "Claim Desk", "chosen_rationale": "The claim is the deliverable; the desk metaphor keeps every screen artifact-shaped, the way a practice manager would check it between appointments.", "prioritized_components": [ { "name": "Claim-status chip", "why": "every claim is scoped by one of four domain-state statuses" }, { "name": "Claim-window card w/ next-action", "why": "primary time-critical work unit" }, { "name": "Claim Submission Pack assembler", "why": "output is a bundle with a hard-fail completeness checklist" } ], "patterns": [ { "name": "Insurer switcher", "description": "Global insurer selector; every completeness check respects the selected insurer's rule set." }, { "name": "Claim release sign-off", "description": "Named claims reviewer with attestation copy; clinical appeals cannot release without DVM/credentialed-technician sign-off." } ], "states": [ "default", "hover", "active", "focus", "disabled", "loading", "skeleton", "empty", "error", "warning", "success", "offline", "permission-denied", "partial-data", "syncing", "unsaved-changes", "ai-generating" ], "localization": [ "Copy budgets assume +35% expansion for DE/FR translations.", "RTL mirror verified for AR/HE (icons flipped, numerals kept LTR).", "Dates/times/currencies use Intl APIs, never hardcoded formats.", "Touch targets ≥ 44px; keyboard tab order matches visual order.", "Density modes: comfortable (default), compact (power users), spacious (accessibility)." ], "uniqueness_audit": { "app_specific_decisions": [ "Claim-status chip motif", "Gap-register-not-invented-data copy discipline" ], "cliches_avoided": [ "Paw-print clip-art", "Green-check compliance theatre", "Insurance-scare banners" ], "scale_notes": "New blueprints inherit the network shell but MUST declare their own signature element, accent role, and anti-reference before they can be marked ready. Enforced by the release gate." }, "tokens": { "brand": "168 58% 22%", "brand-fg": "40 30% 97%", "surface": "40 22% 97%", "ink": "200 22% 14%", "muted": "200 10% 40%", "accent": "20 63% 37%" }, "type": { "display": "Charter, 'Iowan Old Style', Georgia, ui-serif, serif", "body": "-apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif", "fonts_url": "" }, "signature": { "motif": "Claim-status chip · warm clinical palette", "render": "status-chip-grid" } }, "seo": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "archetype": "insurer-fluent authority site", "archetype_impact": "Search fit is an insurer-fluent authority site aimed at practice managers, not pet owners. That means depth over breadth: each page names the specific insurer, PMS, or workflow step it addresses, and thin variants are refused.", "authority_dna": { "site_archetype": "insurer-fluent authority site", "monetization_model": "B2B lead → free Unclaimed Revenue Scan → paid Claim Submission Pack engagement (not ad revenue; not affiliate).", "main_search_intents": [ "informational", "commercial" ], "topical_authority_opportunity": "Own the 'veterinary pet-insurance claims submission' topic cluster for the practice-manager audience by covering the entire workflow — insurer-by-insurer completeness requirements, claims-authorization mechanics, denial-appeal drafting, EOB reconciliation — better than any consumer-facing claims-filing guide.", "local_seo_opportunity": "Not justified: buyers search by insurer/workflow, not by city. Do not build /city/ pages.", "global_national_opportunity": "National (US-first) is the primary market; no international variant needed at launch.", "easiest_ranking_path": "Long-tail, practice-manager-specific queries ('claim submitted but insurer never responded', 'pet insurance claim denied incomplete documentation what to do') where the SERP is dominated by consumer-facing insurer explainer pages, not practice-side operational content.", "hardest_ranking_path": "Head terms like 'pet insurance' or 'veterinary practice management software' — dominated by aged insurer and PMS-vendor domains. Defer until authority is established.", "trust_credibility_requirements": [ "Named human authors with role + credentials", "Insurer/statute citations on every completeness-checklist claim", "Last-reviewed date + change log on insurer-format pages", "Direct links to each insurer's own claims-filing guidance (not aggregators)", "Claims-reviewer attribution on any page describing the review process" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Authority hub + narrow high-intent service page + linkable evidence assets (Unclaimed Revenue Scan, insurer cheat sheets). Not a directory. Not a marketplace.", "seo_moat": "always-current, insurer-by-insurer completeness-checklist pages with change-log timestamps, covering all major carriers rather than one" }, "search_market": { "primary_markets": [ "veterinary pet-insurance claims submission workflow", "insured-client claim reimbursement delay" ], "secondary_markets": [ "claims-status tracking for veterinary practices", "pet-insurance denial appeal support", "case-acceptance benefit estimates" ], "low_competition_subtopics": [ "insurer-by-insurer completeness checklist differences", "PMS-export-to-claim workflow", "veterinary claims-authorization mechanics" ], "high_commercial_intent": [ "done-for-you pet insurance claims processing for veterinary practices", "outsource veterinary insurance claims submission", "veterinary claims reviewer service" ], "informational": [ "why was my pet insurance claim denied", "how long does a pet insurance claim take", "what does a complete pet insurance claim need" ], "local_intent": [], "transactional": [ "ClaimTail pricing", "book a free Unclaimed Revenue Scan", "veterinary claims processing service demo" ], "comparison": [ "done-for-you claims processing vs Trupanion Vet Portal", "claims processing service vs in-house front desk" ], "problem_solution": [ "insured client claim stuck pending", "pet insurance claim missing documentation", "front desk no time for insurance claims" ], "near_me": [], "long_tail": [ "how to submit a Healthy Paws claim from a veterinary PMS", "what happens when a pet insurance claim is denied for incomplete documentation", "veterinary claims authorization form template" ], "questions": [ "what does a complete pet insurance claim packet need?", "who is responsible for filing a pet insurance claim?", "how fast should a submitted pet insurance claim resolve?" ], "emerging": [ "AI-assisted veterinary claims extraction", "automated EOB reconciliation for veterinary practices" ], "seasonal": [], "underserved_serps": [ "insurer-by-insurer completeness checklist comparisons", "veterinary claims-authorization mechanics explained" ], "weak_serps": [ "pet insurance claim denial reasons list", "veterinary practice insurance claims checklist" ], "forum_dominated_serps": [ "what happens if a pet insurance claim is never submitted", "pet insurance reimbursement horror stories" ], "winnable_authoritative_serps": [ "veterinary pet-insurance claims submission definitive guide", "insurer completeness-checklist requirements by carrier" ], "avoid_initially": [ "pet insurance reviews", "best pet insurance company", "pet insurance cost calculator" ], "easy_wins": [ "insurer-by-insurer completeness checklist differences", "veterinary claims-authorization mechanics", "why pet insurance claims get denied for incomplete documentation" ], "moderate": [ "veterinary pet-insurance claims submission definitive guide", "case-acceptance benefit-estimate workflow" ], "long_term_plays": [ "veterinary practice management software comparison", "portfolio-wide reimbursement dashboards for DSOs" ], "do_not_pursue": [ "generic 'how to start a pet business' content", "celebrity or trend-jacking posts", "AI-generated listicles" ] }, "keyword_clusters": [ { "primary": "why was my pet insurance claim denied for incomplete documentation", "related": [ "pet insurance claim denial reasons", "incomplete documentation pet insurance" ], "intent": "informational", "user_problem": "A practice's insured client is asking why their claim was denied and the practice doesn't have a clear answer", "funnel": "MOFU", "business_value": "high", "ranking_difficulty": "low", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "SERP dominated by generic consumer-side insurer FAQ pages, not practice-side operational content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / evidence guide", "reason": "High buyer intent + weak SERP + our unique practice-side proof", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "done-for-you veterinary insurance claims processing vs Trupanion Vet Portal", "related": [ "veterinary claims processing service alternatives", "single-insurer portal comparison" ], "intent": "commercial", "user_problem": "Evaluating a single-insurer portal nobody fully operates vs a multi-insurer done-for-you service", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Weak — mostly Trupanion's own vendor pages", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Comparison page (honest, evidence-based)", "reason": "Late-funnel intent with weak competition", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "veterinary claims-authorization form explained", "related": [ "assignment of benefits pet insurance", "claims authorization template" ], "intent": "informational", "user_problem": "Practice manager wants a concrete, plain-language explanation of the claims-authorization mechanism", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Weak — thin insurer glossary entries", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Resource / explainer page", "reason": "Easy win + strong trust-building fit", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "insurer-by-insurer completeness checklist comparison", "related": [ "what does a complete pet insurance claim need", "pet insurance claim requirements by carrier" ], "intent": "informational", "user_problem": "Needs authoritative, carrier-specific completeness requirements in one place", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "Weak — no aggregator covers this from the practice side", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Data table page (updated quarterly)", "reason": "Recurring reference traffic + easy freshness moat", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "how to speed up a pet insurance claim reimbursement", "related": [ "pet insurance claim taking too long", "veterinary claim status tracking" ], "intent": "informational", "user_problem": "A client or practice wants to understand why a claim is slow and what actually speeds it up", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "medium", "serp_weakness": "SERP is thin and forum-heavy", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "How-to cluster page", "reason": "Easy win + high assist to the product page", "priority_score": 13, "priority": "P0", "bucket": "easy-win" }, { "primary": "veterinary practice management software claims features", "related": [ "ezyVet insurance claims", "PMS insurance integration comparison" ], "intent": "commercial", "user_problem": "Ready to evaluate whether their PMS already solves this", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "high", "conversion_potential": "high", "content_effort": "high", "serp_weakness": "Strong — aged PMS vendor domains", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Product page (defer)", "reason": "Long-term play — do not chase before authority is built", "priority_score": 9, "priority": "P1", "bucket": "medium" }, { "primary": "veterinary pet-insurance claims submission definitive guide", "related": [ "how pet insurance claims work for veterinary practices", "pet insurance claims process explained" ], "intent": "informational", "user_problem": "Just took on claims-support responsibility and needs to orient", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "low", "content_effort": "high", "serp_weakness": "Moderate — mostly consumer-facing insurer content", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar page", "reason": "Anchors topical authority for the whole cluster", "priority_score": 7, "priority": "P1", "bucket": "medium" } ], "topical_authority_map": { "core_topics": [ "Veterinary pet-insurance claims submission — definitive guide", "Claim-status tracking & reimbursement delay", "Insurer completeness-checklist library" ], "pillars": [ { "name": "Veterinary pet-insurance claims submission — definitive guide", "core_intent": "informational", "audience": "practice managers, hospital administrators, and RCM leads", "conversion_goal": "Unclaimed Revenue Scan signup → later pilot conversation", "supporting_pages": [ "Why claims get denied for incomplete documentation", "Claims-authorization mechanics explained", "Insurer-by-insurer completeness checklist comparison", "FAQ: veterinary insurance claims" ], "internal_links": [ "/product", "/insurers/", "/resources/checklist" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "evidence_needed": [ "Named claims reviewer", "Primary-source insurer citations", "Worked example" ], "local_variants": [], "national_variants": [ "US-national (default)" ] }, { "name": "Claim-status tracking & reimbursement delay", "core_intent": "commercial", "audience": "practice managers, hospital administrators, and RCM leads", "conversion_goal": "Book a pilot conversation", "supporting_pages": [ "Claim reimbursement delay causes, ranked", "Unclaimed revenue: what it is and how to check for it", "Common claim-completeness gaps" ], "internal_links": [ "/product", "/guides/claims-submission/", "/resources/unclaimed-revenue-scan" ], "schema": [ "Article", "FAQPage", "BreadcrumbList" ], "evidence_needed": [ "Worked evidence artifact", "Insurer citation", "Reviewer credential" ], "local_variants": [], "national_variants": [ "US-national" ] }, { "name": "Insurer completeness-checklist library", "core_intent": "informational", "audience": "practice managers, hospital administrators, and RCM leads", "conversion_goal": "Assisted conversion via internal linking", "supporting_pages": [ "Trupanion Vet Portal vs a done-for-you desk", "Healthy Paws completeness requirements", "Nationwide, MetLife, Pets Best, ASPCA, Embrace, Lemonade, Fetch, Spot, Prudent Pet — submission requirements" ], "internal_links": [ "/guides/claims-submission/", "/product" ], "schema": [ "Article", "BreadcrumbList" ], "evidence_needed": [ "Primary source link", "Visited-on date", "Reviewer sign-off" ], "local_variants": [], "national_variants": [ "US-national" ] } ], "supporting_page_types": [ "definition / glossary", "how-to workflow", "edge-case handling", "insurer-format-change explainer", "worked example", "FAQ", "comparison (only when honest)", "case study (only with permission)", "evidence artifact / template" ] }, "site_architecture": { "homepage_strategy": "Above-the-fold: one-sentence purpose + primary CTA (free Unclaimed Revenue Scan). Below: pain cards linking to pillars, one evidence-asset teaser, one authority statement with named claims reviewer.", "main_nav": [ "Product", "How it works", "Pricing", "Resources", "About", "Contact" ], "footer_nav": [ "Editorial policy", "Contact", "Privacy", "Terms", "Sitemap" ], "hubs": [ { "name": "Product / service", "url": "/product", "purpose": "High-intent commercial page" }, { "name": "Guides pillar", "url": "/guides", "purpose": "Topical authority hub" }, { "name": "Insurer library", "url": "/insurers", "purpose": "Entity/insurer reference" }, { "name": "Resources", "url": "/resources", "purpose": "Linkable assets (Unclaimed Revenue Scan, checklists)" } ], "url_patterns": [ "/product", "/guides/[topic]/", "/insurers/[insurer]/", "/resources/[asset]/", "/compare/[a]-vs-[b]/", "/glossary/[term]/" ], "avoid_url_patterns": [ "/[city]/[service]/ (no local intent for this buyer)", "/blog/[year]/[month]/[slug]/ (dated slugs decay CTR)", "/tag/[tag]/ (thin archive pages)" ] }, "global_national": { "national_clusters": [ "veterinary pet-insurance claims submission definitive guide", "insurer completeness-checklist library", "claim-status tracking & reimbursement delay" ], "linkable_assets": [ "Free Unclaimed Revenue Scan (email-gated report)", "Insurer completeness-checklist cheat sheet (downloadable)", "Claims-authorization template" ], "original_research_ideas": [ "Annual insured-client claims-readiness benchmark across a small operator sample", "Invoice completeness index: share of intake invoices missing insurer-required fields (anonymized)" ], "international_needed": false, "international_notes": "Not needed. US-first. Do not build hreflang variants." }, "local_seo": { "justified": false, "reason": "Buyers search by insurer/workflow, not by city. Local pages would be doorway pages.", "gbp_categories_primary": [], "gbp_categories_secondary": [], "location_page_rules": [ "Do not build location pages for this blueprint." ], "citations": [], "review_strategy": "Reviews are not a Local ranking factor here; use direct case studies (with permission) instead.", "local_schema": [] }, "programmatic": { "recommended": false, "reason": "Programmatic pages almost always become doorway pages. Prefer a small number of deeply-researched, insurer-specific pages.", "rules": [ "Only for genuinely differentiated data (e.g., a true insurer-by-insurer completeness table)", "Every page must include a unique data field + unique human-written analysis + human review before publish", "noindex until minimum quality threshold met" ], "per_page_requirements": [ "≥1 unique data point not present on sibling pages", "≥1 unique paragraph of human-written analysis", "Verified last-reviewed date" ], "quality_gates": [ "Reviewer sign-off before publish", "No auto-generated insurer variants without a human pass" ] }, "page_templates": [ { "page_type": "Homepage", "purpose": "State the offer + route to the free Unclaimed Revenue Scan.", "target_intent": "commercial", "url_pattern": "/", "h1_pattern": "[One-sentence purpose]", "title_pattern": "ClaimTail — [One-sentence purpose]", "meta_description_pattern": "One sentence outcome + CTA verb. ≤ 155 chars.", "above_the_fold": [ "H1", "Sub-headline (audience + outcome)", "Primary CTA (Unclaimed Revenue Scan)", "1 trust chip (reviewer / cite)" ], "outline": [ "Problem framing", "deliverable cards", "how-it-works", "pricing", "proof", "FAQ", "compliance" ], "internal_links": [ "/product", "/guides", "/pricing" ], "schema": [ "WebPage", "FAQPage (where genuine)" ], "conversion_elements": [ "Unclaimed Revenue Scan form", "Primary CTA button" ], "trust_elements": [ "Named claims reviewer", "Submitted-or-Free Guarantee" ], "media": [ "No stock photography; illustrative status chips only" ], "faq_opportunities": [ "Do you act as our insurance agent?", "How is pricing structured?" ], "cta_strategy": "One primary CTA (Unclaimed Revenue Scan); secondary CTA deep-links to how-it-works.", "anti_thin_rules": [ "Minimum 600 words of unique copy", "No auto-generated filler sections" ], "quality_requirements": [ "Claims-reviewer sign-off before publish", "Every stat sourced and dated" ] }, { "page_type": "Pillar guide", "purpose": "Own the core topic for search + AI answer engines.", "target_intent": "informational", "url_pattern": "/guides/[topic]/", "h1_pattern": "[Topic], explained for practice managers", "title_pattern": "[Topic] | ClaimTail", "meta_description_pattern": "Plain-language answer + named reviewer credibility signal.", "above_the_fold": [ "H1", "40-60 word extractable definition", "Last-reviewed date" ], "outline": [ "Definition", "Workflow steps", "Edge cases", "FAQ" ], "internal_links": [ "/product", "/resources/checklist" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "conversion_elements": [ "Inline link to Unclaimed Revenue Scan" ], "trust_elements": [ "Named reviewer", "Primary-source citations" ], "media": [ "Diagrams of the claim workflow only" ], "faq_opportunities": [ "What does a complete claim packet need?" ], "cta_strategy": "Soft CTA mid-page + stronger CTA at the end.", "anti_thin_rules": [ "Minimum 900 words", "At least one worked example" ], "quality_requirements": [ "Claims-reviewer sign-off before publish", "Visited-on date for every insurer citation" ] } ], "on_page_rules": { "title_tag": "Pattern: [Primary keyword] — [Angle] | ClaimTail. ≤ 60 chars. Front-load the keyword. No clickbait.", "meta_description": "≤ 155 chars. State the specific outcome. Include a verb + an insurer citation when applicable. No stuffing.", "headings": "One H1. H2s follow the workflow steps or the searcher's questions. No decorative headings.", "intro": "First 100 words: define the topic in the searcher's language, name the specific insurer/workflow step, and preview the answer.", "internal_links": "3-6 contextual internal links per page, no mid-answer commercial links in FAQ content.", "external_citations": "Every insurer-requirement or statistic claim links to its primary source with a visited-on date.", "images": "Illustrative diagrams only; no stock photography; descriptive alt text on every image.", "tables_lists": "Use tables for insurer-by-insurer comparisons; use lists for sequential workflow steps.", "freshness": "Insurer-format pages carry a last-reviewed date and a visible change log.", "author_attribution": "Every content page names its author with role and a linked author page.", "cta_placement": "One CTA above the fold, one at the natural end of the content; never mid-paragraph.", "mobile": "Single-column layout below 640px; tap targets ≥44px; no horizontal scroll.", "snippet_targeting": "40-60 word extractable definition directly under the H1 for featured-snippet eligibility.", "avoid": [ "Keyword stuffing", "AI-generated filler paragraphs", "Duplicate content across insurer variants" ] }, "entity_seo": { "main_entities": [ "veterinary pet-insurance claims", "Claim Submission Pack", "claims reviewer", "claims authorization", "completeness checklist", "EOB reconciliation", "denial appeal" ], "related_entities": [ "Trupanion Vet Portal", "assignment of benefits", "confidence score", "insurer completeness rule" ], "people": [ "Named claims reviewer (role-title until owner facts close)", "DVM or credentialed veterinary technician" ], "orgs": [ "ClaimTail", "the major pet insurers referenced (Trupanion, Healthy Paws, Nationwide, MetLife, Pets Best, ASPCA, Embrace, Lemonade, Fetch, Spot, Prudent Pet)" ], "synonyms": [ "veterinary pet-insurance claims submission", "claims processing packet", "insured-client claim filing", "audit-ready claim" ], "problems": [ "Claim denied for incomplete documentation", "Claim pending past a normal window", "No time to file insurance claims" ], "solutions": [ "Done-for-you Claim Submission Pack", "Denial-Appeal Service", "Eligibility & Monitoring Retainer" ], "processes": [ "Intake", "Extraction", "Completeness check", "Claims-reviewer release", "Submission", "Status tracking", "EOB reconciliation" ], "tools": [ "ezyVet", "Shepherd", "Digitail", "Covetrus Pulse", "Cornerstone" ], "regulations": [ "NY DFS OGC Opinion No. 01-06-36", "NY DFS OGC Opinion No. 03-04-28", "NAIC adjuster-licensing model act framework" ], "alternatives": [ "Trupanion Vet Portal (single-insurer)", "In-house front-desk filing", "General PMS policy-field storage" ] }, "schema_strategy": [ { "type": "Organization", "where": "Site-wide in head", "required_fields": [ "name", "url", "logo" ], "caution": "Keep in sync with visible About/contact; hold until entity facts close." }, { "type": "WebPage", "where": "Every page", "required_fields": [ "name", "description" ], "caution": "None." }, { "type": "FAQPage", "where": "FAQ sections with genuine questions", "required_fields": [ "mainEntity" ], "caution": "Only real, answered questions — never padded." } ], "internal_linking": { "pillar_to_cluster": "Pillar links to every direct cluster page in a curated section.", "cluster_to_pillar": "Every cluster page links back to its pillar in the intro.", "cluster_to_cluster": "Link between sibling clusters only where the reader's next question naturally leads there.", "faq_to_commercial": "Answer the question first, then link to the product page in a 'related' block — never inline mid-answer.", "anchor_text_rules": [ "[PLACEHOLDER] owner to complete" ], "breadcrumbs": "Every guide/insurer page carries a breadcrumb trail: Home > Guides > [Pillar] > [Page].", "service_to_location": "Not applicable — no location pages at launch." }, "technical_seo": { "crawlability": "Flat depth (≤3 clicks from homepage). No orphan pages.", "indexability": "Index all real content. noindex utility pages and thank-you pages.", "sitemaps": "XML sitemap generated at build time.", "robots": "robots.txt allows all; disallow /admin/. Reference sitemap.", "canonicals": "Self-referencing canonical on every page.", "core_web_vitals": "LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 on the landing page per DESIGN-STANDARD §7.", "mobile": "Mobile-first responsive layout; no horizontal scroll; tap targets ≥44px.", "js_seo": "Landing page is server-rendered static HTML; no client-side-only content requiring JS for indexing.", "rendering": "Static HTML, no hydration dependency for primary content.", "pagination": "Not applicable at launch (no paginated archive content).", "faceted_nav": "Not applicable — no faceted product catalog.", "duplicate_control": "One URL per insurer/topic; no auto-generated near-duplicate variants.", "redirects": "301 redirects only; no redirect chains; audited quarterly.", "analytics_setup": "GA4 + server-side event logging for domain.* and ui.* data-events.", "gsc_setup": "Google Search Console verified via DNS; sitemap submitted.", "rank_tracking": "Weekly rank tracking on the P0 keyword cluster once indexed.", "accessibility": "WCAG 2.2 AA. Semantic HTML. Landmarks. Focus states. Alt text." }, "eeat": { "author_bios": "Every content page has a named author with role, credentials, and a linked author page.", "expert_reviewers": "Every YMYL page reviewed by a named claims reviewer with disclosed credentials.", "editorial_policy": "Public /editorial-policy page: sourcing rules, review cadence, correction policy.", "fact_checking": "Every insurer-requirement reference has a link + visited-on date; corrections dated and disclosed.", "credentials": [ "Named claims reviewer (role-title until owner facts close)", "DVM or credentialed-technician clinical reviewer" ], "citations": "Every completeness-checklist claim cites the insurer's own published guidance or a named regulatory opinion.", "first_hand_proof": [ "[PLACEHOLDER] owner to complete" ], "update_cadence": "Insurer-format pages reviewed quarterly at minimum; immediate update on any known insurer format change.", "monetization_disclosure": "Pricing and guarantee terms disclosed on the same page as any claim about outcomes — no hidden fees.", "ymyl_notes": "Claims-processing and reimbursement content is treated as YMYL-adjacent; language stays cautious and cites primary sources." }, "ai_search": { "principles": [ "Answer the exact question in the first paragraph", "Provide a 40-60 word extractable definition near the top", "Cite named primary sources (insurers, NAPHIA, Gallup, PetInsuranceReview.com)" ], "tactics": [ "FAQPage schema for genuine FAQs", "Consistent entity naming across the site", "Concise summaries at the top of long guides" ], "do_not": [ "Write pages targeting AI systems instead of humans", "Fabricate statistics or citations" ] }, "conversion": { "primary_cta": "Get your free Unclaimed Revenue Scan on your last 30 days of insured-client invoices.", "secondary_cta": "See how a Claim Submission Pack is built / download the insurer completeness-checklist cheat sheet (email capture).", "lead_magnets": [ "Free Unclaimed Revenue Scan (human-reviewed report in 24h)", "Insurer completeness-checklist cheat sheet (PDF)" ], "trust_elements": [ "Named claims reviewer + credentials", "Insurer citations with visited-on dates", "Submitted-or-Free Guarantee" ], "per_page_paths": [ { "page_type": "Homepage", "path": "Hero CTA → Unclaimed Revenue Scan form → confirmation" }, { "page_type": "Pillar guide", "path": "Inline CTA → product page → Unclaimed Revenue Scan form" } ], "tracking": "domain.diagnostic_requested fires on Unclaimed Revenue Scan submit; ui.cta_primary fires on any primary CTA click." }, "link_earning": { "digital_pr_ideas": [ "Annual insured-client claims-readiness benchmark report", "Invoice completeness index with a shareable result page" ], "original_research": [ "Small-practice survey (n≥30) once per year" ], "directories": [ "Veterinary trade-association member resource pages", "PMS-vendor partner marketplace listings" ], "avoid": [ "Paid link schemes", "Guest-post link farms", "Reciprocal link exchanges with unrelated sites" ], "expert_contributions": [ "Named claims reviewer contributes to veterinary trade press", "HARO/Qwoted responses on pet-insurance reimbursement topics" ], "partnerships": [ "PMS-vendor partner marketplace listings", "Veterinary trade-association resource-page inclusion" ] }, "roadmap_90d": [ { "phase": "Days 0-30: Foundation", "goal": "Establish trust + ship product page + first pillar.", "pages": [ "Homepage", "Product page", "Pillar: veterinary pet-insurance claims submission definitive guide", "About + reviewer bio (role-titles)", "Editorial policy", "Contact" ], "keywords_targeted": [ "veterinary pet insurance claims submission", "why was my pet insurance claim denied" ], "why_first": "Without a trust surface and a real product page, everything else has nowhere to convert.", "business_value": "high", "conversion_goal": "Unclaimed Revenue Scan signups", "difficulty": "low-medium", "internal_links": [ "/product", "/guides" ], "required_assets": [ "Named reviewer bio", "Editorial policy" ] }, { "phase": "Days 31-60: Insurer library", "goal": "Ship the insurer-by-insurer completeness checklist library.", "pages": [ "Trupanion Vet Portal comparison", "Healthy Paws / Nationwide / MetLife completeness pages" ], "keywords_targeted": [ "insurer completeness checklist comparison" ], "why_first": "Anchors the topical-authority moat.", "business_value": "high", "conversion_goal": "Unclaimed Revenue Scan signups", "difficulty": "low-medium", "internal_links": [ "/product", "/guides" ], "required_assets": [ "Named reviewer bio", "Editorial policy" ] }, { "phase": "Days 61-90: Conversion assets", "goal": "Ship the Unclaimed Revenue Scan landing page and FAQ hub.", "pages": [ "Unclaimed Revenue Scan", "FAQ hub" ], "keywords_targeted": [ "free pet insurance claims audit for veterinary practices" ], "why_first": "Converts organic traffic into pilot leads.", "business_value": "high", "conversion_goal": "Unclaimed Revenue Scan signups", "difficulty": "low-medium", "internal_links": [ "/product", "/guides" ], "required_assets": [ "Named reviewer bio", "Editorial policy" ] } ], "roadmap_12m": [ { "phase": "Months 4-6: Linkable assets", "goal": "Ship the annual benchmark and the invoice completeness index.", "pages": [ "Annual claims-readiness benchmark", "Invoice completeness index" ], "keywords_targeted": [ "veterinary claims benchmark" ], "why_first": "Linkable assets drive referring domains and topical authority.", "business_value": "medium-high", "conversion_goal": "Assisted conversion via internal linking", "difficulty": "medium", "internal_links": [ "/guides", "/product" ], "required_assets": [ "Benchmark survey data", "Anonymized invoice sample" ] }, { "phase": "Months 7-12: Expansion", "goal": "Add DSO/multi-location content and case-acceptance benefit-estimate guides.", "pages": [ "Multi-location rollout guide", "Case-acceptance benefit-estimate explainer" ], "keywords_targeted": [ "DSO veterinary claims processing" ], "why_first": "Follows the product roadmap's multi-location expansion.", "business_value": "medium-high", "conversion_goal": "Assisted conversion via internal linking", "difficulty": "medium", "internal_links": [ "/guides", "/product" ], "required_assets": [ "Benchmark survey data", "Anonymized invoice sample" ] } ], "priority_pages": [ { "rank": 1, "page_title": "Why was my pet insurance claim denied for incomplete documentation", "slug": "/guides/claim-denied-incomplete-documentation/", "page_type": "Pillar / evidence guide", "primary_keyword": "pet insurance claim denied incomplete documentation", "secondary_keywords": [ "veterinary claim denial reasons" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "low", "business_value": "high", "conversion_potential": "high", "cta": "Get my free Unclaimed Revenue Scan", "internal_links": [ "/product", "/guides" ], "production_priority": "P0", "required_proof": [ "Named claims reviewer", "Primary-source insurer citation" ], "schema": [ "Article", "FAQPage" ], "why_opportunity": "High buyer intent with a weak or consumer-only SERP" }, { "rank": 2, "page_title": "Done-for-you veterinary insurance claims processing vs Trupanion Vet Portal", "slug": "/compare/claimtail-vs-trupanion-vet-portal/", "page_type": "Comparison page", "primary_keyword": "claims processing service vs Trupanion Vet Portal", "secondary_keywords": [ "single insurer portal alternative" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "high", "cta": "Get my free Unclaimed Revenue Scan", "internal_links": [ "/product", "/guides" ], "production_priority": "P0", "required_proof": [ "Named claims reviewer", "Primary-source insurer citation" ], "schema": [ "Article", "FAQPage" ], "why_opportunity": "High buyer intent with a weak or consumer-only SERP" } ], "competitor_gaps": { "typical_competitor_types": [ "single-insurer direct-pay portals", "general veterinary PMS platforms", "consumer-facing insurer claims-filing guides" ], "common_weaknesses": [ "No practice-side operational content", "No named claims reviewer or credentials", "No worked examples of a completeness checklist", "Thin FAQ padded with generic questions" ], "how_to_beat_them": [ "Fresh insurer citations with visited-on dates", "Named claims reviewer + credentials visible", "Real, redacted worked completeness-checklist examples" ] }, "metrics": { "weekly": [ "GSC impressions/clicks by pillar", "New indexed pages" ], "monthly": [ "Organic sessions by hub", "Assisted conversions (Unclaimed Revenue Scan signups)" ], "quarterly": [ "Pillar coverage audit", "Insurer-rule freshness audit" ], "annual": [ "Full topical authority audit", "Benchmark report refresh" ] }, "risks": [ { "risk": "Thin content", "applies": true, "mitigation": "Minimum-word + claims-reviewer sign-off gate before publish." }, { "risk": "Duplicate content across insurer variants", "applies": true, "mitigation": "One URL per insurer; no auto-generated variants; canonical to pillar." }, { "risk": "Doorway location pages", "applies": true, "mitigation": "Local pages are refused for this vertical — buyers search by insurer/workflow, not city." } ], "first_20_pages": [ "Homepage", "Product / service page", "About + reviewer bio (role-titles)", "Editorial policy", "Contact", "Privacy", "Pillar: veterinary pet-insurance claims submission definitive guide", "Why was my pet insurance claim denied for incomplete documentation", "Claims-authorization mechanics explained", "Insurer-by-insurer completeness checklist comparison", "FAQ: veterinary insurance claims", "Trupanion Vet Portal vs ClaimTail comparison", "Healthy Paws completeness requirements", "Nationwide completeness requirements", "MetLife completeness requirements", "Pricing page", "Free Unclaimed Revenue Scan landing page", "How a Claim Submission Pack is built", "Denial-Appeal Service explainer", "Eligibility & Monitoring Retainer explainer" ], "first_10_tech_fixes": [ "XML sitemap generated at build", "robots.txt reviewed + sitemap referenced", "Self-referencing canonicals", "GSC + GA4 verified with server-side events", "Core Web Vitals baseline (LCP, INP, CLS)", "Structured breadcrumbs sitewide", "Author + editorial-policy pages published", "404 + 410 patterns defined", "Redirect audit (no chains)", "Semantic HTML + accessibility landmarks" ], "first_10_authority_actions": [ "Publish named claims-reviewer bio(s)", "Public editorial policy + correction policy", "Cite primary insurer sources with visited-on dates", "Launch the completeness-checklist cheat-sheet lead magnet", "Pitch veterinary-trade-press responses per week", "Publish 1 original data point / benchmark", "Reach out to veterinary trade-association resource pages", "Guest post on 1 industry association blog", "Podcast interview outreach (veterinary practice-management shows)", "Set up quarterly insurer rule-change post cadence" ], "final_recommendation": "Build an insurer-fluent authority site around 'veterinary pet-insurance claims submission'. Ship the first 20 pages in 90 days (product + pillar + insurer library + Unclaimed Revenue Scan), then compound with quarterly insurer rule-change posts and one annual benchmark. Refuse doorway pages, refuse mass AI content, treat named-reviewer (role-titled until owner facts close) + primary-source citations as non-negotiable, and never publish reimbursement-outcome claims without the coverage-decisions-remain-the-insurer's caveat.", "disclaimers": [ "All volume/difficulty labels are RELATIVE ESTIMATES (low/medium/high), not exact numbers. Validate with Semrush, Ahrefs, or Google Search Console before committing spend.", "This brief is deterministic per blueprint — it will not shift between renders. Any changes should be made in code, not in prompts.", "YMYL-adjacent topic: language must stay cautious; nothing here is legal, insurance, or medical advice." ] }, "microsite": { "category": "Healthcare / revenue cycle", "shortTitle": "ClaimTail", "audience": "practice managers and hospital administrators at veterinary hospitals (1–5 locations)", "problem": "Every insured client's visit generates a claim that has to be manually pulled from the medical record and itemized invoice and submitted in whatever format that specific insurer requires. Only Trupanion offers a real vet-side submission tool, and even that requires the clinic to run it. Every other major insurer — Healthy Paws, Nationwide, MetLife, Pets Best, ASPCA, Embrace, Lemonade, Fetch, Spot, Prudent Pet — leaves the pet owner to gather the paperwork. The work falls to whichever front-desk staffer has ten free minutes, at practices that are already short-staffed.", "offer": "On ClaimTail, practice managers stop chasing insurance paperwork and start shipping claims. Send the visit's medical-record export and itemized invoice; AI extracts the fields with source quotes, a maintained completeness checklist runs against that insurer's requirements, and a trained claims reviewer — with a DVM or credentialed technician on any clinical appeal language — releases a Claim Submission Pack and submits it within 24 hours under your client's own signed claims authorization.", "faq": [ { "q": "Is ClaimTail for the front desk or for billing?", "a": "Both, because at most independent and small-group practices they're usually the same overworked people: practice managers, front-desk leads, and credentialed technicians fielding 'how do I file my claim' questions with no dedicated insurance-claims staff. If your insurance paperwork currently lands in an email folder, the workflow will match your reality immediately." }, { "q": "How is a Claim Submission Pack kept audit-ready?", "a": "Every extracted field carries a verbatim source quote from your medical-record export or invoice — missing fields ship as explicit gaps, never invented data. A trained claims reviewer signs every submission; a DVM or credentialed veterinary technician approves any clinical medical-necessity language in an appeal before it's filed." }, { "q": "What arrives at the end of a claim run?", "a": "A submitted claim confirmation, a tracked status link for both the practice and the client, and — on resolution — an EOB reconciliation entry matched to the practice's own invoice and AR ledger." }, { "q": "How does ClaimTail pricing work?", "a": "Outcome-based, never hourly, never a percentage of what your client gets reimbursed. Claim Submission Packs are $12–$18 per claim submitted. The Denial-Appeal Service is $35–$60 per appeal filed. The Eligibility & Monitoring Retainer runs $199–$499 per month per location for portfolio-wide status tracking." }, { "q": "How do I get started on ClaimTail?", "a": "Two ways: send one recent insured-client visit record and invoice and get your first Claim Submission Pack in 24 hours, or run the free Unclaimed Revenue Scan — upload a batch of recent invoices and get a claim-status/risk report within 24 hours, no cost." }, { "q": "Do you sign the claim as our insurance representative?", "a": "No — and that boundary is the design. Your client remains the policyholder and you remain the practice of record. Our claims reviewer signs the release; a DVM or credentialed technician attests to clinical-language accuracy on appeals. The insurer alone decides coverage and payment." }, { "q": "How long are claim records retained?", "a": "Records are retained per the practice's own data-retention preference (default 3 years), hash-stamped on intake and mirrored to your own storage so the record is yours either way. On termination you get a full export handoff." }, { "q": "What if the invoice lands on a Friday?", "a": "The intake channel runs 24/7. Claims are submitted within 24 hours of a complete intake; if a claim is pending past that insurer's typical processing window, it shows up in your weekly digest with a proactive follow-up already opened." }, { "q": "What if our insurer asks for more documentation?", "a": "We chase it with a templated, chart-grounded response, and if clinical medical-necessity language is involved, a DVM or credentialed technician signs off before anything is filed. We never downgrade to hourly billing for a chase." } ], "process": [ { "title": "Intake: send the visit record", "body": "Forward the medical-record export and itemized invoice through your secure intake channel. It's logged, hash-stamped, and matched to the client's on-file claims authorization." }, { "title": "Extract with source quotes", "body": "AI pulls the completeness-checklist-relevant fields — diagnosis, procedures, itemized charges, dates, technician — each with a verbatim source quote and a confidence score. Anything below the confidence bar routes to reviewer confirmation instead of flowing through." }, { "title": "Check against that insurer's rules", "body": "The claim is checked against a maintained, insurer-specific completeness checklist — the exact fields and attachments that carrier requires — in deterministic code, not a language model's guess." }, { "title": "Claims-reviewer release", "body": "A trained claims reviewer signs every submission against the completeness checklist and source data. Any clinical medical-necessity appeal language requires a DVM or credentialed technician's sign-off first — no exceptions." }, { "title": "Submit and track", "body": "The packet is submitted under the client's signed claims authorization within 24 hours. Both the practice and the client get a tracked status link the same day." }, { "title": "Watch, appeal, reconcile", "body": "Every week: open claims pending past a normal window get a proactive follow-up; denials get a chart-grounded appeal; resolved claims get reconciled against the insurer's EOB and closed in your AR ledger." } ], "northStarCta": { "label": "Get my free Unclaimed Revenue Scan", "href": "/contact", "secondary_label": "See how a claim is submitted", "secondary_href": "/how-it-works" }, "ubiquitousLanguage": { "audience": "practice managers and hospital administrators at veterinary hospitals (1–5 locations)", "domain": "veterinary pet-insurance claims processing and case-acceptance support", "deliverable": "Claim Submission Pack + claims-reviewer release (clinical sign-off on appeals)", "reviewer": "trained claims reviewer", "record": "tracked status link + EOB-reconciliation audit trail", "unit_of_work": "claim run", "cta_primary": "Get my free Unclaimed Revenue Scan", "cta_secondary": "See how a claim is submitted", "regulator": "state insurance department", "regulator_full": "state department of insurance (adjuster/TPA licensing authority)", "statute": "ministerial-vs-discretionary claims-processing distinction (NY DFS OGC Opinions 01-06-36, 03-04-28)", "trigger_moment": "an insured client's visit invoice, a claim pending past a normal window, or a denial", "event_intake_started": "veterinary_insurance_claims_case_acceptance_desk_intake_started", "event_conversation_requested": "veterinary_insurance_claims_case_acceptance_desk_conversation_requested" }, "trust": { "standards": [ "Every field in a Claim Submission Pack traces to a verbatim source quote from your medical record or invoice — missing fields ship as explicit gaps, never invented data", "A trained claims reviewer signs every submission; a DVM or credentialed veterinary technician approves any clinical medical-necessity appeal language before filing", "Records are hash-stamped on intake, mirrored to your own storage, with a full export handoff on termination" ], "response_time": "We reply within one business day — a claim sitting past an insurer's normal processing window doesn't wait for a sales rep.", "data_handling": "Your practice and client documents stay in per-practice isolated folders and are never used to train models. PII is minimized to what the claim requires. ClaimTail provides claims-processing support only; it is not an insurance agent, broker, adjuster, or third-party administrator, and does not guarantee any coverage decision or reimbursement amount." }, "hook": "The next claim your front desk almost forgot to file lands on a tracked link, not a drawer — ClaimTail holds the submission trail at rest. Practice managers stop chasing insurance paperwork and start shipping claims — the claims desk is where the completeness check already runs.", "sub_headline": "ClaimTail stores every claim decision — source quote, completeness check, reviewer signature — in a tracked record a client can check without calling the front desk. Every claim run maps each field to a source at intake, a completeness checklist runs the math, a human releases the pack, and the audit trail is retained for as long as your practice needs it.", "dream_outcome": "You answer the week: every insured client's claim submitted within 24 hours, every pending claim followed up before the client asks, every denial appealed with the right sign-off. The tracked status link is the answer — reviewer-released and reproducible on the day anyone asks.", "specific_pains": [ "A client's $2,400 dental visit invoice says 'dental, meds sent home' — and by Wednesday nobody has checked whether the itemized charges and diagnosis match what Healthy Paws' claim form actually requires.", "Ask for the status of a claim submitted six weeks ago and someone opens an email thread search — that's the record a frustrated client would find first.", "A general-purpose chatbot can produce a plausible-looking claim draft; only a maintained, insurer-specific completeness checklist with a human release gate produces one that doesn't bounce back for more documentation.", "A client declines a $2,000 treatment plan because nobody could tell them, in the moment, what their insurance would likely cover — and the practice never captures the case or the follow-up revenue at all.", "An insurer reads the claim as a package: diagnosis, itemized charges, dates, prior-history documentation where required. Miss any piece and the claim sits in the additional-documentation queue instead of being paid." ], "cost_of_inaction": "A claim you can't submit complete today is reimbursement your client waits weeks longer for — and a case-acceptance conversation you can't have with confidence tomorrow. Incomplete documentation is the leading cause of the extra 5–15 business days tacked onto an already 1–30 day reimbursement range across the 12 largest pet insurers. No vendor can honestly guarantee a claim will be paid or promise a specific reimbursement amount — but a claim that was never submitted at all has a cost of its own.", "mechanism": { "name": "The ClaimTail claims-processing desk", "steps": [ { "title": "Intake: send the visit record", "body": "Forward the medical-record export and itemized invoice through your secure intake channel. It's logged, hash-stamped, and matched to the client's on-file claims authorization." }, { "title": "Extract with source quotes", "body": "AI pulls the completeness-checklist-relevant fields with a verbatim source quote and a confidence score. Anything below the confidence bar routes to reviewer confirmation." }, { "title": "Check against that insurer's rules", "body": "The claim is checked against a maintained, insurer-specific completeness checklist in deterministic code — never left to a language model to judge as 'probably fine.'" }, { "title": "Claims-reviewer release", "body": "A trained claims reviewer signs every submission. Clinical medical-necessity appeal language always requires a DVM or credentialed technician's sign-off first." }, { "title": "Submit, track, reconcile", "body": "Submitted within 24 hours under the client's signed authorization; tracked to resolution; reconciled against the insurer's EOB into your own AR ledger." } ] }, "offer_stack": [ { "item": "Claim Submission Pack per insured-client visit", "note": "medical-record and invoice extraction, insurer-matched completeness check, claims-reviewer release, submission within 24 hours, tracked status link" }, { "item": "Denial-Appeal Service", "note": "chart-grounded appeal drafting; DVM/credentialed-technician sign-off on any clinical language; filed with supporting documentation" }, { "item": "Claims-reviewer release on every pack", "note": "trained reviewer signature on every submission; clinical sign-off required for any appeal with medical-necessity language" }, { "item": "Eligibility & Monitoring Retainer", "note": "benefit-eligibility checks and portfolio-wide open-claim status tracking with a weekly digest" }, { "item": "EOB-reconciliation trail", "note": "hash-stamped originals, per-practice folder isolation, export handoff on termination" }, { "item": "Gap register + insurer chase", "note": "you get the closable missing-field list before submission, not a rejection notice after the insurer reads the claim" } ], "guarantee": "The Submitted-or-Free Guarantee: if a Claim Submission Pack is not submitted within 24 hours of a complete intake, that pack is free. Explicitly not guaranteed: the insurer's coverage decision, the reimbursement amount, the insurer's own processing timeline once submitted, or the accuracy of practice- or client-supplied information.", "urgency": "Release capacity is gated by the human chokepoint — every pack is signed by a claims reviewer, and every clinical appeal by a DVM or credentialed technician — so we cap new-practice onboarding to protect that sign-off rather than filling a pipeline.", "objections": [ { "q": "“Doesn't our PMS already handle this?”", "a": "Practice-management systems like ezyVet, Shepherd, Digitail, and Covetrus Pulse store policy fields — none of them assemble and submit a multi-insurer claim packet for you. That's still ten minutes of front-desk time per claim, times every insured visit." }, { "q": "“Isn't this what Trupanion's Vet Portal already does?”", "a": "Trupanion Express covers exactly one insurer, and your clinic still has to set it up and use it. Every other major carrier — nine of the ten most common ones we see — has no vet-side tool at all. ClaimTail handles all of them." }, { "q": "“Are we going to be defending an AI-drafted claim?”", "a": "No field in a submitted claim comes from a language model without a source quote. AI extracts with citations and drafts appeal language from structured chart input only; a named claims reviewer signs every release, and a DVM or credentialed technician signs off on any clinical language." }, { "q": "“Where does our client data live?”", "a": "In per-practice isolated folders with least-privilege access, hash-stamped originals, and no use of your documents for model training. You get a full export handoff if you leave." }, { "q": "“Are you our insurance agent?”", "a": "No. We process and submit claims on the policyholder's behalf; we never determine coverage, authorize payment, or negotiate a settlement. That boundary is disclosed on every claims-authorization form and every page of this site." }, { "q": "“How is a ClaimTail engagement priced?”", "a": "Per claim, published tiers, never hourly, never a percentage of what your client is reimbursed. Anchor it against ten minutes of front-desk time per claim and the client loyalty a fast, complete claim protects." } ], "who_this_is_not_for": [ "Individual pet owners looking to file their own claim directly — our commercial relationship is with the practice, and the pet owner is the policyholder who signs the claims authorization, not the paying customer.", "Buyers looking for a guarantee that a claim will be paid — we decline that engagement and say so plainly; no vendor can honestly sell it.", "Practices with minimal insured-client volume — the per-claim model rarely makes sense below a small handful of insured visits per month." ], "proof_pillars": [ { "title": "Source-quoted extraction, every field", "body": "Every extracted field carries a verbatim source quote from the chart or invoice you sent — missing fields ship as explicit gaps, never invented data." }, { "title": "Claims-reviewer released, every time", "body": "No packet auto-releases. A trained claims reviewer signs every submission; a DVM or credentialed technician signs off on any clinical medical-necessity appeal language before it's filed." }, { "title": "Tracked to resolution, reconciled to your ledger", "body": "Every claim carries a status link from submission through EOB reconciliation — checking status is a read operation for you, not a project." } ], "stakes_line": "The claim status link is the truth. Everything else — the front desk's memory, the email thread, the portal nobody logs into — is the story you tell yourself.", "deliverable": "Claim Submission Pack + claims-reviewer release (clinical sign-off on appeals)", "unit_of_work": "claim run", "lexicon": { "regulator": "state insurance department", "regulator_full": "state department of insurance (adjuster/TPA licensing authority)", "statute": "ministerial-vs-discretionary claims-processing distinction (NY DFS OGC Opinions 01-06-36, 03-04-28)", "statute_frame": "the intake-to-submission workflow where an unsubmitted claim is a self-inflicted client-trust risk.", "persona": "Practice Manager", "persona_moment": "You're a Practice Manager. It's the morning after an insured client's visit generated a $2,400 invoice. Someone needs to know whether the claim packet is complete enough to submit today — with every figure tied to a source you can point to.", "trigger_moment": "an insured client's visit invoice, a claim pending past a normal window, or a denial", "enforcement_stakes": "client trust and reimbursement delay, not a regulatory penalty — ClaimTail's own regulatory exposure is limited to the adjuster/TPA licensing boundary it stays inside of", "retention": "per practice preference, default 3 years", "cta_verb": "Get my free Unclaimed Revenue Scan", "intake_checklist": [ "The visit's medical-record export and itemized invoice, exactly as generated by your PMS", "The client's signed claims authorization and insurer/policy ID (collected once at signup)", "Any prior-treatment history the insurer's policy terms require (e.g., pre-existing-condition documentation)", "The internal owner name and inbox to copy on status updates and weekly digests", "Your practice's claimable-visit dollar threshold", "Any existing single-insurer direct-pay integration in active use, so those claims route around ClaimTail", "Your preferred secure intake method (encrypted email or upload form)" ], "trust_standards_specific": [ "Every field in a Claim Submission Pack traces to a verbatim source quote from the chart or invoice you sent — gaps ship explicit, never invented", "A trained claims reviewer signs every submission; a DVM or credentialed technician approves every clinical appeal before it ships", "Records — intake originals, drafts, submissions — are hash-stamped and retained per your practice's preference, keyed to the triggering visit", "The insurer's own completeness checklist is mapped to your evidence field-by-field; hard fails (no diagnosis, no itemized charge, unknown insurer) block a submission", "AI drafting is bounded to extraction and narrative from structured input, disclosed, and gated on claims-reviewer sign-off before anything leaves the workspace" ], "regulator_faqs": [ { "q": "Do you sign the claim as our insurance representative?", "a": "No — you remain the practice of record and your client remains the policyholder. Our claims reviewer signs the release; a DVM or credentialed technician attests to clinical-language accuracy on appeals. The insurer alone determines coverage." }, { "q": "How long are records retained?", "a": "Per your practice's preference, default 3 years — hash-stamped and mirrored to your own storage. If you need a longer window, the vault honors it." }, { "q": "What if the invoice lands on a Friday?", "a": "Intake runs 24/7. Claims are submitted within 24 hours of a complete intake, and status is computed from the submission date — not the discovery date — so nothing quietly ages over a weekend." }, { "q": "What if we started the claim in-house?", "a": "Send what exists. We pick up mid-workflow, keep your work product intact, and only add the pieces the completeness checklist is missing — no rework, no busywork." } ] }, "proof_angle": { "id": "claim-status-trust", "headline": "The next client status question lands on a tracked link, not a project — ClaimTail holds the submission trail at rest.", "lever": "ClaimTail stores every claim decision — source quote, completeness check, reviewer signature — in a record a client can check without calling the front desk.", "outcome_verb": "answer", "outcome_frame": "answer a claim-status question in seconds instead of an email search", "proof_promise": "The tracked status link is the client-question answer — reviewer-released, source-quoted, and reproducible any day someone asks." }, "indexable": true }, "evidence": [ { "id": "veterinary-insurance-claims-case-acceptance-desk-e1", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "area": "Identity", "claim_or_finding": "Legal entity, registered address, and jurisdiction of formation are not yet declared.", "status": "owner-action", "evidence": "No owner-supplied facts on file.", "verification_command": "Owner submits entity + jurisdiction pack.", "fix_owner": "owner", "remediation": "Provide entity name, registration number, and jurisdiction of formation.", "severity": "blocker" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-e2", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "area": "Trust boundary", "claim_or_finding": "Public page is a validation microsite for a ministerial claims-processing service; not an insurance agent, broker, adjuster, or third-party administrator.", "status": "verified", "evidence": "Microsite carries an explicit trust-boundary and ministerial-processing-only disclaimer block.", "verification_command": "Inspect /microsites/veterinary-insurance-claims-case-acceptance-desk for trust boundary.", "fix_owner": "engineering", "remediation": "None — enforced by template.", "severity": "low" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-e3", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "area": "SEO integrity", "claim_or_finding": "No fake review, rating, LocalBusiness, or Organization identity schema is emitted; no reimbursement or coverage guarantee claims anywhere in marketing copy.", "status": "verified", "evidence": "Only WebPage + FAQPage schema is generated; marketing compliance gate applied.", "verification_command": "View SEO Factory row for veterinary-insurance-claims-case-acceptance-desk", "fix_owner": "engineering", "remediation": "None — enforced by the SEO factory.", "severity": "low" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-e4", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "area": "Regulated claims", "claim_or_finding": "Elevated trust burden — claims-processing claims gated on owner facts: named claims-reviewer identity, DVM/credentialed-technician engagement, entity identity, and counsel review of the claims-authorization form and state-by-state adjuster/TPA licensing scope.", "status": "release-blocker", "evidence": "Trust burden = Medium (Rubric Gate 4 = 2.5/5, explicitly lower than this factory's typical compliance-engine candidate — see source blueprint).", "verification_command": "Complete owner-action pack for named reviewer + counsel review.", "fix_owner": "owner", "remediation": "Provide claims-reviewer identity, DVM/credentialed-technician contact, professional review, and disclosure facts.", "severity": "high" }, { "id": "veterinary-insurance-claims-case-acceptance-desk-e5", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "area": "Manifest coverage", "claim_or_finding": "Manifest-backed blueprint present in source repository (2026-07-13 build, Run #341, incl. fresh-verified NAPHIA 2025/2026 penetration figures).", "status": "assumed", "evidence": "manifest.json entry", "verification_command": "Cross-check manifest entry for veterinary-insurance-claims-case-acceptance-desk in the builds repository.", "fix_owner": "engineering", "remediation": "Attach the manifest run to the evidence register.", "severity": "medium" } ], "seo_pages": { "id": "seo-veterinary-insurance-claims-case-acceptance-desk", "business_slug": "veterinary-insurance-claims-case-acceptance-desk", "route": "/microsites/veterinary-insurance-claims-case-acceptance-desk", "title": "Veterinary Insurance Claims & Case-Accepta… · ClaimTail", "description": "ClaimTail for practice managers and hospital administrators at veterinary hospitals. Submitted, tracked pet-insurance claims within 24 hours, reconciled to your own AR ledger.", "canonical": "/microsites/veterinary-insurance-claims-case-acceptance-desk", "og_title": "ClaimTail — The Veterinary Insurance Claims & Case-Acceptance Acceleration Desk", "og_description": "ClaimTail for practice managers and hospital administrators at veterinary hospitals. Submitted, tracked pet-insurance claims within 24 hours, reconciled to your own AR ledger.", "schema_type": "FAQPage", "schema_status": "pending-owner-facts", "sitemap_include": false, "noindex": true }, "vertical_style": { "accent": "clinical-teal", "signature": "Claim-status chips with warm amber accent", "layout": "Claim desk index", "anti": "Paw-print clip-art and insurance-scare banners" }, "canva": { "slug": "veterinary-insurance-claims-case-acceptance-desk", "territory": "Claim Desk", "family": { "id": "healthcare-revenue-cycle", "name": "Healthcare / Revenue Cycle", "motion": "calm" }, "tokens": { "brand": "168 58% 22%", "brand-fg": "40 30% 97%", "surface": "40 22% 97%", "ink": "200 22% 14%", "muted": "200 10% 40%", "accent": "20 63% 37%" }, "type": { "display": "Charter", "body": "Source Sans 3", "fonts_url": "" }, "scale": { "h1": "clamp(2.5rem, 5.5vw, 4.25rem)", "h2": "clamp(1.75rem, 3vw, 2.5rem)", "h3": "clamp(1.25rem, 2vw, 1.5rem)", "body": "clamp(1rem, 1.1vw, 1.125rem)", "small": "0.8125rem", "tracking_display": "-0.01em", "tracking_body": "-0.005em", "weight_display": 700, "weight_body": 450 }, "spacing": { "card_padding": "1.5rem", "card_radius": "0.5rem", "card_shadow": "0 0 0 1px hsl(var(--ink) / 0.08)", "section_gap": "clamp(3rem, 7vw, 5.5rem)", "hero_gap": "clamp(1.25rem, 2vw, 2rem)" }, "layout": { "hero": "split-primary", "card": "elevated-soft", "cta": "solid-brand", "archetype": "magazine", "card_silhouette": "rounded-outline", "button_geometry": "rounded" }, "background": { "hero_gradient": "radial-gradient(900px 500px at 85% -10%, hsl(20 63% 37% / 0.13), transparent 60%), radial-gradient(700px 420px at 5% 0%, hsl(168 58% 22% / 0.10), transparent 55%)", "cta_gradient": "linear-gradient(135deg, hsl(168 58% 22%), hsl(20 63% 37%))", "section_wash": "linear-gradient(180deg, hsl(40 22% 97%) 0%, hsl(168 58% 22% / 0.04) 100%)" }, "motif": "Claim-status chip + tracked link" }, "capabilities": { "marketing": true, "portal": true, "ops": true, "chatbot": true, "payments": false }, "generated_at": "2026-07-13T15:39:00.000Z", "checksum": "a42ccb13b5b8b1b3" }