{ "version": "1.8.0", "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "title": "SlipLienClear — Florida Marina Possessory Lien Notice Completeness Pack Engine", "vertical": "Legal-ops / regulatory documentation", "seed": { "s": "fl-marina-possessory-lien-notice-completeness-pack-engine", "t": "SlipLienClear — Florida Marina Possessory Lien Notice Completeness Pack Engine", "v": "Legal-ops / regulatory documentation", "r": "Medium-high", "m": "M" }, "product": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "project_name": "SlipLienClear", "project_type": "regulator-fluent compliance documentation workflow application", "vertical": "Legal-ops / regulatory documentation", "audience": "office managers, owners, and harbor masters at independent Florida marinas (50–300 slips)", "geography": "Florida (US), beachhead in high-density coastal counties", "scale_expectation": "8-20 retainer logos in year one; per-event pack volume with a The publication window seasonal spike; high artifact fidelity", "core_workflows": [ "Invoice intake & field extraction", "Vessel registry & vessel-identity evidence", "Lien-rate computation & notice-clock tracking", "Pack release & The publication window aging reporting" ], "discovery": { "one_line_purpose": "On SlipLienClear, marina staff stop guessing at §328.17 and start releasing packs. The vessel's ledger and identity are extracted at intake, a four-source lien search runs in parallel, deterministic rules check the five notice elements, and every Notice Completeness Pack releases with a specialist signature and an audit trail.", "primary_users": [ "office managers, general managers, and harbor masters at independent Florida marinas", "Notice specialist / Florida-licensed maritime attorney reviewer", "Title examiner, insurer, or acquirer diligence team (read-only)" ], "jobs_to_be_done": [ "Produce the §328.17 possessory-lien notice pack for a delinquent vessel without retaining counsel for every clerical step", "Prove a good-faith DHSMV/USCG/UCC/judgment search so a later title transfer doesn't explode", "Start the 60-day clock cleanly and clear a dead slip without creating title liability" ], "value_prop": "SlipLienClear turns a scattered marina delinquency file into a release-ready, specialist-released §328.17 Notice Completeness Pack — reconstructable on demand, defensible under a title examiner's read, with the marina always the lien claimant of record.", "competitors": [ "Marina billing SaaS (Molo, DockMaster) that ages receivables but never assembles the notice", "Maritime counsel priced for disputes, not for a recurring documentation factory", "The folder of PDFs where delinquency files currently go to die" ], "differentiation": "Done-for-you packs, not a dashboard: a verified four-source lien search, deterministic checks on the five notice elements (never an LLM), specialist release on every pack, Florida-attorney review on high-value or documented vessels, and explicit exception lists instead of invented data.", "positioning_statement": "For office managers at independent Florida marinas who fear a defective §328.17 notice will void a nonjudicial sale, SlipLienClear is the done-for-you documentation service that turns a delinquent vessel's ledger into a release-ready, audit-ready Notice Completeness Pack — unlike marina billing software that expects your team to run compliance, or counsel priced for litigation." }, "assumptions": [ { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-a1", "statement": "The target audience will pay for evidence-linked, human-reviewed outputs over unverified AI generation.", "confidence": "medium", "impact_if_wrong": "severe", "revisit_trigger": "First 5 design-partner sales calls — reject if willingness-to-pay signal is absent." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-a2", "statement": "The workflow can be reconstructed from an owner-supplied evidence pack within one week per design partner.", "confidence": "low", "impact_if_wrong": "high", "revisit_trigger": "First real customer onboarding cycle." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-a3", "statement": "The vertical tolerates AI-assisted drafts when human review is explicit and audit-traceable.", "confidence": "medium", "impact_if_wrong": "high", "revisit_trigger": "First regulator or auditor interaction." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-a4", "statement": "Single-tenant per customer 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." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-a5", "statement": "Manifest-backed blueprint reflects real customer workflow, not a synthetic scenario.", "confidence": "medium", "impact_if_wrong": "medium", "revisit_trigger": "First customer walkthrough of the intended workflow." } ], "unknowns": [ { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-u1", "question": "Which specific licensed professional will sign off on outbound artifacts?", "blocks": "Any commercial claim; regulator-facing delivery.", "resolution_path": "Named reviewer + engagement letter on file before commercial engagement." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-u2", "question": "Which vessel categories and regimes are in scope for launch?", "blocks": "Compliance vessel events; data-residency posture; canonical/hreflang.", "resolution_path": "Owner confirms in-scope vessel categories (commercial refrigeration, IPR, comfort cooling) in the owner-action pack." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-u3", "question": "What is the actual willingness-to-pay?", "blocks": "Pricing hypothesis; unit economics.", "resolution_path": "5 design-partner discovery calls with explicit pricing conversation." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-u4", "question": "Which existing systems must this integrate with day-one?", "blocks": "Architecture module boundaries; data-in/out contracts.", "resolution_path": "Design-partner tech-inventory questionnaire." }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-u5", "question": "Is there a data-residency or on-prem constraint?", "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 a single ICP segment (multi-site food retail / foodservice) 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": "Flat per-pack (per released Notice Completeness Pack), free Delinquency Gap Scan, optional add-ons; never hourly, never contingency", "revenue_streams": [ "Notice Completeness Pack (flat, per vessel event)", "Sale Continuity Add-on", "Portfolio Lien Register subscription", "Optional Florida-attorney review (fixed pass-through)" ], "moat": [ "Verified multi-source lien-search operations", "Statute-gated QA with an audit trail", "Marina-specific SOPs and gold-standard packs", "AMI / MIAF channel relationships" ], "gtm": [ "Founder-led statute-teardown content + answer-engine FAQ", "AMI / MIAF trade-association webinars", "Personalized harbor-master outbound + maritime-counsel white-label" ], "pricing_hypothesis": "Founding pack $399; standard $499; documented/complex $599–$799 — priced under a 2–4 hour maritime-attorney bill (validate pack frequency with 8 pilot logos before scaling).", "kill_criteria": [ "No signed pilot marina in 4 weeks", "Specialist median exceeds 90 min/pack after Phase 1", "No paid conversion by week 20", "A released pack causes a documented title-dispute finding" ] }, "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 lien 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": [ "§328.17 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": [ "Pack released without human review", "Cross-regime rule lienage (maritime counsel ODS vs §328.17 dockage)", "Regulator-facing errors attributed to AI" ], "ethical_guardrails": [ "Human reviewer required before regulator submission", "Per-regime prompt + template isolation (maritime counsel ODS vs §328.17 dockage)", "AI-usage disclosure in pack metadata where required" ] }, "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": "fl-marina-possessory-lien-notice-completeness-pack-engine-r1", "risk": "Regulator-facing claim proves incorrect", "likelihood": "medium", "impact": "severe", "mitigation": "Every claim linked to a cited source + reviewer signoff", "contingency": "Retraction workflow; customer-notification template; audit-log export within 24 hours", "owner": "legal" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-r2", "risk": "AI hallucination in a delivered artifact", "likelihood": "medium", "impact": "high", "mitigation": "Retrieval-first pipeline + structured output validation + reviewer gate", "contingency": "Reviewer-triggered rollback + regeneration; incident postmortem published to customer", "owner": "engineering" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-r3", "risk": "Cross-tenant data lien", "likelihood": "low", "impact": "severe", "mitigation": "Row-level auth + per-tenant retrieval indices + log-scrubbing", "contingency": "Breach-notification runbook; forced credential rotation; scoped tenant kill switch", "owner": "engineering" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-r4", "risk": "Design partner churns before contract", "likelihood": "medium", "impact": "high", "mitigation": "Weekly working-session cadence; documented value moments; owner-action ledger", "contingency": "Structured exit interview; write learnings into ICP + pricing hypothesis", "owner": "owner" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-r5", "risk": "Compliance framework demand exceeds team capacity", "likelihood": "high", "impact": "high", "mitigation": "SOC 2 Type I year one; map controls once, evidence continuously", "contingency": "Contract framework carve-out with legal review; delay enterprise segment", "owner": "ops" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-r6", "risk": "Single-region outage takes production down", "likelihood": "low", "impact": "high", "mitigation": "Multi-AZ managed database; nightly cross-region backup", "contingency": "Documented restore-to-DR runbook; RTO 8h / RPO 1h during pilot", "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 Notice Completeness 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 SlipLienClear. 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 lien" ], "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": "fl-marina-possessory-lien-notice-completeness-pack-engine", "app_name": "SlipLienClear release desk", "archetype": "filing-dossier", "archetype_label": "pack binder desk", "reader_role": "Marina Office Manager", "one_sentence_app": "SlipLienClear Desk is a pack binder desk for marina office managers who need every dockage vessel event tied to a §328.17-complete record before an auditor or diligence reviewer, insurer, or acquirer asks for the binder.", "homepage_sequence": [ "scene", "workflow", "instrument", "offer", "proof", "qualification", "objections" ], "hero": { "frame_label": "Legal-ops · §328.17 notice pack desk", "eyebrow": "Marina office manager / vessel 60+ days past due", "interface_title": "SlipLienClear release desk", "primary_panel_title": "Slip B-14 · vessel HIN FLZ-1187-C4 · 74 days past due · 4-source search open", "primary_panel_body": "Open pack run: normalize the ledger and vessel identity, order the DHSMV/USCG/UCC/judgment search, draft the five §328.17 notice elements, then stage the Notice Completeness Pack for specialist release.", "side_panel_title": "Before this ships", "side_panel_items": [ "Vessel identity confirmed on 2+ documents", "Four-source lien search checked or exception-coded", "Five notice elements present · 60-day window set" ], "status_metric": "REVIEW", "status_label": "release gate active" }, "language": { "problem_heading": "The marina office manager's moment", "mechanism_heading": "Inside the SlipLienClear release desk", "proof_heading": "Why this survives a title examiner", "offer_heading": "What leaves the room", "objection_heading": "The hard questions", "qualification_heading": "Who should not use this", "cta_close": "Open a pack run from your oldest delinquent vessel — released by a real notice specialist, escalated to a Florida-licensed maritime attorney when the vessel is high-value or documented." }, "modules": [ { "name": "Invoice intake", "job": "Turns a forwarded vessel ledger into a named pack run with an vessel match, extracted fields, and a missing-field list.", "artifact": "triage record" }, { "name": "Vessel registry", "job": "Holds every delinquent vessel’s vessel-identity determination, regulatory category, dockage/GWP mapping, and locked calculation method — with the evidence behind each.", "artifact": "vessel-identity worksheet" }, { "name": "Notice Completeness Pack", "job": "Packages the completeness scoring, requirement compare, notice-clock status, lien-search checklist, and exception list into the record an inspector can walk without a meeting.", "artifact": "release package" } ], "checkpoints": [ { "label": "§328.17 required field", "pass": "extracted with source quote", "fail": "chased or shipped as explicit gap" }, { "label": "completeness scoring", "pass": "deterministic code, dual-method compared", "fail": "blocked before release" }, { "label": "Notice Completeness Pack", "pass": "analyst releases (attorney reviewer on red)", "fail": "stays draft" } ], "signature_scene": "You're a Marina Office Manager. It's the morning after a tech added 9 pounds of dockage to the Slip B-14 vessel. Someone needs to know — today — whether that trips the 20% requirement and starts a 60-day statutory notice clock, and the only evidence is an invoice that says 'topped off vessel.' This page is built like the pack binder desk that person needed before the clock started." }, "ddd": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "project_name": "SlipLienClear", "business_understanding": { "summary": "SlipLienClear — marina staff stop guessing at §328.17 and start releasing packs. A delinquent vessel's ledger and identity are extracted at intake, a four-source lien search runs in parallel, deterministic rules check the five notice elements, and every Notice Completeness Pack releases with a specialist signature and an audit trail.", "customer_profile": "office managers, general managers, and harbor masters at independent Florida marinas (50–300 slips, fragmented search sources, no in-house maritime counsel)", "customer_pain": "Ledgers missing the fields a §328.17 notice needs; the five notice elements never drafted; lienholders across DHSMV/USCG/UCC/judgment never searched; the 60-day clock never started cleanly; no audit-ready file when a title examiner, insurer, or acquirer asks.", "paid_outcome": "A reliably delivered, specialist-released (attorney-escalated on high-value or documented vessels) Notice Completeness Pack per vessel event, plus a living Portfolio Lien Register — reconstructable on demand, defensible under a title examiner's read.", "value_creation": "AI compresses invoice classification, field extraction, and pack drafting; deterministic code owns every completeness score, clock date, and delinquency-age metric; humans own release, red review, and anything sent to FLHSMV; the platform binds them with an append-only audit trail and per-logo isolation.", "why_ai_native": "The extract-compute-draft-chase loop is only economical with a bounded AI layer feeding deterministic rules. A pure-manual service cannot hit $149-$399 pack pricing; a pure-automated SaaS cannot chase vendors, hold the release gate, or absorb the judgment calls that keep the record defensible.", "operational_risks": [ "Reviewer bottleneck on red packs and The publication window season", "Prompt injection via vessel ledger content", "Cross-logo retrieval lien", "Full-charge data unobtainable at scale (packs stuck yellow)", "Silent delivery failure on a running notice clock" ], "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.", "Single-tenant per customer is not required for the first cohort — logical isolation with row-level auth is acceptable.", "Manifest-backed blueprint reflects real customer workflow, not a synthetic scenario." ], "validation_questions": [ "Which specific licensed professional will sign off on outbound artifacts?", "Which vessel categories and regimes are in scope for launch?", "What is the actual willingness-to-pay?", "Which existing systems must this integrate with day-one?", "Is there a data-residency or on-prem constraint?" ] }, "domain_discovery": { "actors": [ { "actor": "Customer operator", "role": "office managers, general managers, and harbor masters at independent Florida marinas", "goals": [ "Deliver Notice Completeness Packs on schedule", "Reduce cycle time without losing defensibility" ], "decisions": [ "Submit intake", "Accept or revise draft", "Approve outbound delivery" ], "pain_points": [ "Scattered evidence across tools", "Manual re-typing", "Reviewer bottleneck" ] }, { "actor": "attorney reviewer", "role": "Signs and takes accountability for outbound artifacts", "goals": [ "Sign only what is defensible", "Keep audit trail intact" ], "decisions": [ "Approve / reject / request revisions", "Escalate on ambiguity" ], "pain_points": [ "Incomplete evidence", "Ambiguous AI outputs", "No visible source-of-truth" ] }, { "actor": "Regulator", "role": "Inspects artifacts on demand", "goals": [ "Reconstruct decisions from evidence" ], "decisions": [ "Accept, question, or request more of the record" ], "pain_points": [ "Missing citations", "Non-reconstructable state" ] }, { "actor": "AI Orchestrator", "role": "Bounded AI agent that drafts + validates", "goals": [ "Produce grounded, cited drafts", "Escalate on low confidence" ], "decisions": [ "Draft vs escalate", "Which retrieval sources to cite" ], "pain_points": [ "Ambiguous intake", "Sparse evidence" ] }, { "actor": "Platform admin", "role": "Runs the tenant, manages users + integrations", "goals": [ "Keep the system safe and observable" ], "decisions": [ "Provision users", "Rotate secrets" ], "pain_points": [ "Change management across tenants" ] } ], "glossary": [ { "term": "vessel event", "definition": "One delinquency event, repair, retrofit, or disposal on a delinquent vessel — the unit of work SlipLienClear turns into a pack.", "used_by": "Customer, Operator", "context": "Sales & Intake", "example": "\"Open a vessel event for the vessel delinquency at Slip B-14\"", "notes": "Do not confuse with 'engagement' in Billing (contract term)." }, { "term": "field evidence", "definition": "An extracted invoice or registry value carrying a verbatim source quote, attached to a line inside the Notice Completeness Pack.", "used_by": "Analyst, Reviewer, Auditor", "context": "Service Fulfillment", "example": "\"Every quantity-added figure must carry field evidence\"", "notes": "Distinct from 'note' (internal, non-cited). Missing = explicit gap, never invented." }, { "term": "Notice Completeness Pack", "definition": "The analyst-released deliverable SlipLienClear produces per vessel event: vessel-identity worksheet, completeness score, requirement compare, clock status, verification checklist, exception list, audit trail.", "used_by": "Customer, Analyst, Reviewer, Auditor", "context": "Client Delivery", "example": "\"Ship the Notice Completeness Pack once the analyst releases\"", "notes": "Immutable once released; corrections go through the Re-issue workflow." }, { "term": "Release", "definition": "Signed attestation by the analyst (green/yellow) or Florida-licensed maritime attorney reviewer (red) that the pack is complete and its math verified.", "used_by": "Analyst, Reviewer, Platform", "context": "Quality Assurance", "example": "\"Release bound to session + timestamp\"", "notes": "Not the same as customer acceptance to binder." }, { "term": "Owner action", "definition": "Discrete fact the customer must supply before a pack can go green — above all the attested vessel-identity determination.", "used_by": "Owner, Platform", "context": "Compliance & Governance", "example": "\"Full-charge attestation, vessel category, vendor contact\"", "notes": "Caps the pack at yellow while open." }, { "term": "Repair clock", "definition": "The 30-day (120-day IPR-shutdown) window that starts at a delinquency event exceeding the category requirement.", "used_by": "Analyst, Customer, Reviewer", "context": "Service Fulfillment", "example": "\"Clock started 6/14, deadline 7/14, verification pending\"", "notes": "Clock dates come from deterministic code, never an LLM." }, { "term": "Aging watchline", "definition": "Calendar-year cumulative additions ÷ vessel identity; at ≥60-day FLHSMV requires a customer-submitted sale-continuity filing by The publication window of the following year.", "used_by": "Analyst, Reviewer, Customer", "context": "Service Fulfillment", "example": "\"WI-03 at 96% cumulative in October → watch\"", "notes": "Recomputed portfolio-wide every December and February." }, { "term": "Escalation", "definition": "Automatic routing of a pack from AI drafting or analyst release to the Florida-licensed maritime attorney reviewer.", "used_by": "AI Orchestrator, Analyst, Reviewer", "context": "AI Orchestration ↔ Human Review", "example": "\"Escalate on exception, method switch, documented-vessel, aging watch\"", "notes": "Escalation ≠ rejection; it is a hand-off." } ], "decisions": [ { "decision": "Accept intake", "who": "Sales & Intake context (rule + operator override)", "inputs": [ "Customer identity", "Scope statement", "service-event completeness" ], "rule": "Reject if scope statement missing or customer not on-boarded", "output": "service-event accepted event", "risk": "Accepting out-of-scope work degrades reviewer trust." }, { "decision": "Draft vs escalate", "who": "AI Orchestrator", "inputs": [ "field evidence coverage", "Confidence score", "Prior-similar-case pattern" ], "rule": "Escalate below confidence requirement or on ambiguous vessel match", "output": "Draft-ready OR escalation event", "risk": "Silent low-confidence drafts erode reviewer trust." }, { "decision": "Release the Notice Completeness Pack", "who": "Release analyst (green/yellow) or Florida-licensed maritime attorney reviewer (red)", "inputs": [ "Draft pack", "Full field-evidence trail", "Deterministic calc results + dual-method delta" ], "rule": "Release only if every field cites a source or an explicit gap AND hard-fail list is clear (vessel identity, quantity, category)", "output": "Pack released event", "risk": "Over-broad release erodes the audit trail and customer trust." }, { "decision": "Release publicly", "who": "Compliance & Governance", "inputs": [ "Owner-action ledger status", "Evidence closure", "Legal review flag" ], "rule": "Blocked if any owner-action open OR unresolved release-blocker evidence", "output": "Public-release event OR blocked-release event", "risk": "Premature public claims are unretractable in perception." }, { "decision": "Retract delivered artifact", "who": "Legal + attorney reviewer", "inputs": [ "Newly discovered fact", "Impact assessment" ], "rule": "Retract if any signed claim is materially wrong OR unsupported by evidence", "output": "Retraction event + customer notification", "risk": "Delayed retraction compounds legal exposure." } ], "events": [ { "event": "serviceEventAccepted", "meaning": "Work is now committed to fulfillment", "trigger": "Operator or auto-rule accepts intake", "downstream": [ "Onboarding kicked off", "AI orchestrator scheduled" ] }, { "event": "EvidenceCollected", "meaning": "Enough evidence exists to draft", "trigger": "Retrieval + upload passes coverage rule", "downstream": [ "Drafting authorized" ] }, { "event": "DraftReady", "meaning": "AI draft with cited evidence is available for reviewer", "trigger": "AI orchestrator finishes drafting run", "downstream": [ "Reviewer notification" ] }, { "event": "EscalationRaised", "meaning": "AI could not complete safely", "trigger": "Confidence below requirement OR ambiguous input", "downstream": [ "Reviewer queue" ] }, { "event": "ReviewerSigned", "meaning": "attorney reviewer took accountability", "trigger": "Reviewer signature captured", "downstream": [ "Delivery authorized", "Audit-log snapshot" ] }, { "event": "ArtifactDelivered", "meaning": "Notice Completeness Pack handed to the customer / downstream party", "trigger": "Delivery adapter confirms transmit", "downstream": [ "Billing event", "Customer notification" ] }, { "event": "OwnerActionResolved", "meaning": "A blocking owner-supplied fact is now on file", "trigger": "Owner updates the ledger", "downstream": [ "Release-decision recomputation" ] }, { "event": "RetractionFiled", "meaning": "A delivered artifact is formally withdrawn or corrected", "trigger": "Reviewer + legal jointly file", "downstream": [ "Customer notification", "Audit-log append" ] } ] }, "subdomains": [ { "name": "Service Fulfillment (evidence-linked drafting + review)", "type": "core", "description": "The end-to-end path from vessel event to analyst-released, reviewer-escalated Notice Completeness Pack, with every claim cited.", "reason": "This is what customers pay for and what regulators inspect.", "business_value": "Direct revenue and legal defensibility.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "high", "risks": [ "Hallucinated claims", "Reviewer bottleneck", "Un-reconstructable audit trail" ], "validation_questions": [ "Can the reviewer sign in <5 business days?", "Can we reconstruct any past artifact on demand?" ] }, { "name": "AI Orchestration (bounded agents + retrieval)", "type": "core", "description": "The bounded AI layer that drafts, cites, validates, and escalates — never authors final decisions unassisted.", "reason": "The AI-native competitive edge lives here; misuse here creates every high-severity risk.", "business_value": "Cycle-time and margin advantage.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "medium", "risks": [ "Prompt injection", "Grounding drift", "Silent low-confidence output" ], "validation_questions": [ "What is the acceptance rate of AI drafts by reviewers?", "What percent of runs escalate correctly?" ] }, { "name": "Quality Assurance (reviewer signoff + retraction)", "type": "core", "description": "attorney reviewer workflow, signature capture, retraction workflow, and audit-log snapshots.", "reason": "Signoff is the trust primitive of the whole business.", "business_value": "Defensibility; premium pricing.", "recommendation": "build", "ai_involvement": "medium", "human_involvement": "high", "risks": [ "Signature spoofing", "Repudiation", "Delayed retraction" ], "validation_questions": [ "Is every signature cryptographically bound?", "Can we replay any signoff on demand?" ] }, { "name": "Sales & Intake", "type": "supporting", "description": "Lead capture through accepted engagement + scope statement.", "reason": "Feeds Fulfillment; not the differentiator, but if broken, nothing else runs.", "business_value": "Feeds pipeline.", "recommendation": "build", "ai_involvement": "medium", "human_involvement": "high", "risks": [ "Out-of-scope acceptance" ], "validation_questions": [ "Do we reject work outside the ICP?" ] }, { "name": "Client Onboarding & Profile", "type": "supporting", "description": "Tenant provisioning, contact matrix, evidence-pack import, engagement letter.", "reason": "One-time high-touch step per customer.", "business_value": "Reduces first-artifact time.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "high", "risks": [ "Contract terms not represented in the system" ], "validation_questions": [ "Is the reviewer named per tenant?" ] }, { "name": "Client Delivery & Success", "type": "supporting", "description": "Delivery adapter, customer portal, revision loop, renewal signal.", "reason": "Customer-visible surface; drives retention.", "business_value": "Retention.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Delivery failure not surfaced" ], "validation_questions": [ "Do we alert the customer within 1h of any delivery failure?" ] }, { "name": "Compliance & Governance", "type": "supporting", "description": "Owner-action ledger, release-decision engine, policy attestation, DSAR / retraction runbooks.", "reason": "Cross-cuts every context; owns 'can we publicly claim this?'.", "business_value": "Prevents category-level failure.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "high", "risks": [ "Premature public claim" ], "validation_questions": [ "Are all owner actions closed before public release?" ] }, { "name": "Billing & Revenue", "type": "generic", "description": "Subscription + usage-based invoicing, dunning, revenue reporting.", "reason": "Solved category; do not build.", "business_value": "Cash collection.", "recommendation": "buy", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Tax jurisdictional errors" ], "validation_questions": [ "Is Stripe Tax sufficient for the launch jurisdictions?" ] }, { "name": "Identity & Access", "type": "generic", "description": "SSO, MFA, RBAC, session management.", "reason": "Solved category.", "business_value": "Table stakes.", "recommendation": "integrate", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Role escalation" ], "validation_questions": [ "Are roles stored in a dedicated table?" ] }, { "name": "Knowledge Base & Retrieval", "type": "supporting", "description": "Per-tenant retrieval indices, source-of-truth documents, prompt library.", "reason": "Feeds AI Orchestration; poor retrieval = poor drafts.", "business_value": "Drives AI quality.", "recommendation": "build", "ai_involvement": "high", "human_involvement": "medium", "risks": [ "Cross-tenant lienage", "Stale sources" ], "validation_questions": [ "Is retrieval partitioned per tenant?" ] }, { "name": "Analytics & Reporting", "type": "supporting", "description": "Activation, cycle time, acceptance rate, reviewer load, outcome reports.", "reason": "Drives every operational decision.", "business_value": "Feedback loop.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "low", "risks": [ "Vanity metrics" ], "validation_questions": [ "Is the north-star wired?" ] }, { "name": "External Integrations (Anti-Corruption Layer)", "type": "supporting", "description": "Adapters to Vendor invoice inboxes, search work-order / CMMS platforms, Customer AP / document portals and other tools with translation to internal domain terms.", "reason": "External schemas must never lien into the core.", "business_value": "Enables integration without corrupting the model.", "recommendation": "build", "ai_involvement": "low", "human_involvement": "medium", "risks": [ "Silent schema drift" ], "validation_questions": [ "Do all external calls pass through an ACL translator?" ] } ], "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 vessel events into reviewer-signed Notice Completeness Packs.", "subdomain": "Service Fulfillment (core)", "type": "core", "owned_language": [ "vessel event", "field evidence", "Notice Completeness Pack", "Draft", "Escalation", "Signoff" ], "owns": [ "vessel event lifecycle", "Draft state", "Evidence links", "Delivery packet composition" ], "does_not_own": [ "Reviewer identity", "Billing", "Public claim decision" ], "primary_actors": [ "Customer operator", "AI Orchestrator", "attorney reviewer" ], "entities": [ "vessel event", "Draft", "Notice Completeness Pack", "Delivery" ], "value_objects": [ "Confidence score", "Evidence citation", "Delivery address" ], "aggregates": [ "ServiceEventAggregate", "CompletenessPackAggregate" ], "domain_services": [ "Draft composer", "Delivery adapter" ], "application_services": [ "OpenServiceEvent", "RequestDraft", "AttachEvidence", "RequestSignoff", "DeliverCompletenessPack" ], "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 Notice Completeness 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", "attorney reviewer" ], "data_owned": [ "vessel event", "Draft", "Notice Completeness Pack", "Delivery" ], "inputs": [ "Intake payload", "Uploaded evidence", "Retrieval hits" ], "outputs": [ "Signed artifact packet", "Delivery confirmation" ], "external_integrations": [ "Vendor invoice inboxes", "search 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 requirements" ], "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 < requirement", "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 requirements" ], "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 lienage 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": [ "Notice Completeness Pack content", "Public release decision" ], "primary_actors": [ "attorney 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 attorney 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": [ "attorney 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": [ "Notice Completeness Pack content", "Reviewer identity" ], "primary_actors": [ "Business owner", "Legal", "attorney 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 lien", "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": "Sales & Intake", "downstream": "Service Fulfillment", "pattern": "customer-supplier", "business_reason": "Fulfillment cannot start without an accepted engagement.", "data_exchanged": [ "Engagement", "Scope statement" ], "events_exchanged": [ "EngagementAccepted" ], "contract_type": "Published language (Engagement record)", "failure_risks": [ "Silent scope mismatch" ], "acl_notes": "Fulfillment consumes only fields it needs; no direct DB coupling.", "ownership_boundary": "Sales owns engagement lifecycle." }, { "upstream": "Service Fulfillment", "downstream": "Quality Assurance", "pattern": "customer-supplier", "business_reason": "Signoff is a hard gate on delivery.", "data_exchanged": [ "Draft", "Evidence trail" ], "events_exchanged": [ "DraftReady", "ArtifactSigned" ], "contract_type": "Published language", "failure_risks": [ "Reviewer bottleneck" ], "acl_notes": "QA never mutates draft content; only appends signoff.", "ownership_boundary": "QA owns signature log." }, { "upstream": "AI Orchestration", "downstream": "Service Fulfillment", "pattern": "customer-supplier", "business_reason": "Draft is produced by AI; Fulfillment consumes it.", "data_exchanged": [ "Draft payload", "Confidence score" ], "events_exchanged": [ "DraftProduced", "EscalationRaised" ], "contract_type": "Published language (validated schema)", "failure_risks": [ "Draft failing OutputValidator reaches Fulfillment" ], "acl_notes": "OutputValidator sits inside AI Orchestration.", "ownership_boundary": "AI owns run log; Fulfillment owns draft state." }, { "upstream": "Knowledge Base & Retrieval", "downstream": "AI Orchestration", "pattern": "open-host-service", "business_reason": "Retrieval is a stable interface used by all agents.", "data_exchanged": [ "Retrieval hits", "Source citations" ], "events_exchanged": [ "DocIngested", "IndexRebuilt" ], "contract_type": "Open-host published API", "failure_risks": [ "Cross-tenant lien" ], "acl_notes": "Every call carries tenant + partition claim.", "ownership_boundary": "Knowledge owns indices." }, { "upstream": "Client Onboarding & Profile", "downstream": "Service Fulfillment", "pattern": "customer-supplier", "business_reason": "No intake without a provisioned tenant + reviewer.", "data_exchanged": [ "Tenant profile", "Reviewer identity" ], "events_exchanged": [ "TenantProvisioned", "ReviewerRegistered" ], "contract_type": "Published language", "failure_risks": [ "Expired reviewer credential" ], "acl_notes": "Fulfillment reads a projection; does not query Onboarding tables.", "ownership_boundary": "Onboarding owns tenant + reviewer records." }, { "upstream": "Service Fulfillment", "downstream": "Client Delivery & Success", "pattern": "customer-supplier", "business_reason": "Delivery is downstream of signoff.", "data_exchanged": [ "Signed artifact" ], "events_exchanged": [ "ArtifactDelivered", "DeliveryConfirmed" ], "contract_type": "Published language", "failure_risks": [ "Silent delivery failure" ], "acl_notes": "Delivery adapter is inside Fulfillment; Delivery context tracks the receipt.", "ownership_boundary": "Delivery context owns receipts." }, { "upstream": "Quality Assurance", "downstream": "Compliance & Governance", "pattern": "customer-supplier", "business_reason": "Retractions feed compliance workflows.", "data_exchanged": [ "Retraction record" ], "events_exchanged": [ "RetractionFiled" ], "contract_type": "Published language", "failure_risks": [ "Retraction not surfaced" ], "acl_notes": "Compliance subscribes to the event stream.", "ownership_boundary": "QA owns retraction record; Compliance owns downstream runbook." }, { "upstream": "Compliance & Governance", "downstream": "Service Fulfillment", "pattern": "conformist", "business_reason": "Fulfillment must respect release decisions.", "data_exchanged": [ "Release decision" ], "events_exchanged": [ "ReleaseDecisionChanged" ], "contract_type": "Read-only projection consumed by Fulfillment", "failure_risks": [ "Fulfillment ignoring a blocked release" ], "acl_notes": "Fulfillment conforms to Compliance's release model.", "ownership_boundary": "Compliance owns release model." }, { "upstream": "Client Delivery & Success", "downstream": "Billing & Revenue", "pattern": "customer-supplier", "business_reason": "Delivery is the meter for per-artifact pricing.", "data_exchanged": [ "Delivery receipt" ], "events_exchanged": [ "DeliveryConfirmed" ], "contract_type": "Published language", "failure_risks": [ "Missed usage record" ], "acl_notes": "Billing subscribes to delivery events.", "ownership_boundary": "Billing owns invoicing." }, { "upstream": "Identity & Access", "downstream": "every other context", "pattern": "shared-kernel", "business_reason": "Auth primitives are shared.", "data_exchanged": [ "Session claim", "Role" ], "events_exchanged": [], "contract_type": "Shared kernel (tiny, versioned)", "failure_risks": [ "Kernel bloat" ], "acl_notes": "Kernel kept intentionally small.", "ownership_boundary": "Identity owns the primitives." }, { "upstream": "every context", "downstream": "Analytics & Reporting", "pattern": "conformist", "business_reason": "Analytics conforms to whatever events contexts publish.", "data_exchanged": [ "Domain events (read-only)" ], "events_exchanged": [ "all" ], "contract_type": "Read-only event subscription", "failure_risks": [ "Event schema drift" ], "acl_notes": "Analytics stores its own read model.", "ownership_boundary": "Analytics owns rollups." } ], "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 liens 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": "search 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 liens 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 liens 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": "QualifyLead", "event": "LeadQualified", "actor": "Sales / Qualifier Copilot", "context": "Sales & Intake", "aggregate": "EngagementAggregate", "policy": "Reject out-of-ICP", "downstream": "Engagement offer", "risk": "Out-of-scope acceptance" }, { "seq": 2, "command": "AcceptEngagement", "event": "EngagementAccepted", "actor": "Owner", "context": "Sales & Intake", "aggregate": "EngagementAggregate", "policy": "Engagement letter required", "downstream": "Onboarding starts", "risk": "Missing engagement letter" }, { "seq": 3, "command": "ProvisionTenant", "event": "TenantProvisioned", "actor": "Onboarding lead", "context": "Client Onboarding", "aggregate": "TenantAggregate", "policy": "Named reviewer required", "downstream": "Reviewer registration", "risk": "Reviewer credential expired" }, { "seq": 4, "command": "OpenIntake", "event": "ServiceEventAccepted", "actor": "Customer operator", "context": "Service Fulfillment", "aggregate": "ServiceEventAggregate", "policy": "Scope-fit spec", "downstream": "AI drafting scheduled", "risk": "Scope drift" }, { "seq": 5, "command": "AttachEvidence", "event": "EvidenceCollected", "actor": "Customer + Retrieval", "context": "Service Fulfillment", "aggregate": "ServiceEventAggregate", "policy": "Evidence coverage spec", "downstream": "Drafting authorized", "risk": "Insufficient evidence" }, { "seq": 6, "command": "StartAgentRun", "event": "DraftProduced", "actor": "AI Orchestrator", "context": "AI Orchestration", "aggregate": "AgentRunAggregate", "policy": "Confidence requirement", "downstream": "Reviewer queue OR escalation", "risk": "Prompt injection" }, { "seq": 7, "command": "SubmitForSignoff", "event": "DraftReady", "actor": "Service Fulfillment", "context": "Service Fulfillment", "aggregate": "CompletenessPackAggregate", "policy": "Coverage complete", "downstream": "Reviewer notified", "risk": "Reviewer overload" }, { "seq": 8, "command": "ApproveArtifact", "event": "ArtifactSigned", "actor": "attorney reviewer", "context": "Quality Assurance", "aggregate": "SignoffAggregate", "policy": "Reviewer authority spec", "downstream": "Delivery authorized", "risk": "Signature spoof" }, { "seq": 9, "command": "DeliverCompletenessPack", "event": "ArtifactDelivered", "actor": "Delivery adapter", "context": "Service Fulfillment", "aggregate": "CompletenessPackAggregate", "policy": "Deliverability spec", "downstream": "Billing meter, customer notified", "risk": "Silent delivery failure" }, { "seq": 10, "command": "ConfirmDelivery", "event": "DeliveryConfirmed", "actor": "Client Delivery", "context": "Client Delivery & Success", "aggregate": "DeliveryAggregate", "policy": "Ack within SLA", "downstream": "Success cadence", "risk": "Missed ack" }, { "seq": 11, "command": "RecordUsage", "event": "InvoicePaid", "actor": "Billing", "context": "Billing & Revenue", "aggregate": "SubscriptionAggregate", "policy": "Chargeability spec", "downstream": "Revenue rollup", "risk": "Tax misapplication" }, { "seq": 12, "command": "ResolveOwnerAction", "event": "OwnerActionResolved", "actor": "Business owner", "context": "Compliance & Governance", "aggregate": "OwnerActionLedgerAggregate", "policy": "Release readiness spec", "downstream": "Release-decision recompute", "risk": "Public claim while blocker open" }, { "seq": 13, "command": "FileRetraction", "event": "RetractionFiled", "actor": "Legal + attorney reviewer", "context": "Quality Assurance", "aggregate": "RetractionAggregate", "policy": "Retraction preconditions", "downstream": "Customer notification, audit log", "risk": "Delayed retraction" } ], "critical_path": [ "ServiceEventAccepted → EvidenceCollected → DraftReady → ArtifactSigned → ArtifactDelivered → DeliveryConfirmed" ], "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": "OpenIntake", "issued_by": "Customer operator", "preconditions": [ "Engagement accepted", "Tenant provisioned" ], "aggregate": "ServiceEventAggregate", "success_event": "ServiceEventAccepted", "failure_event": "IntakeRejected", "authorization": "Tenant member with Operator role", "validation": "Scope statement present; no duplicate open intake", "audit": "Command + payload hash logged with tenant + user" }, { "name": "AttachEvidence", "issued_by": "Customer operator / Retrieval", "preconditions": [ "Intake open", "File type allowed" ], "aggregate": "ServiceEventAggregate", "success_event": "EvidenceCollected", "failure_event": "EvidenceRejected", "authorization": "Same tenant", "validation": "Virus scan clean; PII policy respected", "audit": "Every attachment hashed and logged" }, { "name": "StartAgentRun", "issued_by": "AI Orchestrator", "preconditions": [ "Evidence coverage complete", "Prompt version active" ], "aggregate": "AgentRunAggregate", "success_event": "DraftProduced", "failure_event": "EscalationRaised", "authorization": "Service role", "validation": "OutputValidator schema passes", "audit": "Prompt version + retrieval hits + cost captured" }, { "name": "ApproveArtifact", "issued_by": "attorney reviewer", "preconditions": [ "Draft ready", "Reviewer session live", "No unresolved escalation" ], "aggregate": "SignoffAggregate", "success_event": "ArtifactSigned", "failure_event": "ArtifactRejected", "authorization": "Reviewer role bound to tenant", "validation": "Every claim cites evidence", "audit": "Signature manifest + timestamp" }, { "name": "DeliverCompletenessPack", "issued_by": "Delivery adapter", "preconditions": [ "Artifact signed", "Compliance release allows delivery" ], "aggregate": "CompletenessPackAggregate", "success_event": "ArtifactDelivered", "failure_event": "DeliveryFailed", "authorization": "Service role", "validation": "Delivery method valid; receipt captured", "audit": "Delivery receipt archived" }, { "name": "ResolveOwnerAction", "issued_by": "Business owner", "preconditions": [ "Owner-action open" ], "aggregate": "OwnerActionLedgerAggregate", "success_event": "OwnerActionResolved", "failure_event": "OwnerActionRejected", "authorization": "Owner role", "validation": "Supplied fact matches action schema", "audit": "Actor + before/after captured" }, { "name": "FileRetraction", "issued_by": "Legal + attorney reviewer", "preconditions": [ "Artifact previously delivered", "Impact statement present" ], "aggregate": "RetractionAggregate", "success_event": "RetractionFiled", "failure_event": "RetractionRejected", "authorization": "Legal AND Reviewer co-sign", "validation": "Retraction preconditions spec", "audit": "Full retraction packet archived" } ], "policies": [ { "name": "Auto-request signoff on coverage complete", "trigger": "EvidenceCollected", "condition": "Evidence coverage spec passes", "action": "Enqueue SubmitForSignoff", "context": "Service Fulfillment", "ai_involvement": "none", "human_approval": false }, { "name": "Escalate on low confidence", "trigger": "DraftProduced", "condition": "Confidence < requirement OR OutputValidator warning", "action": "Emit EscalationRaised, route to reviewer queue", "context": "AI Orchestration", "ai_involvement": "author", "human_approval": false }, { "name": "Block delivery on open compliance blocker", "trigger": "DeliverArtifact command", "condition": "Compliance release decision != 'ready-with-owner-actions' or 'ready'", "action": "Reject delivery, emit DeliveryBlocked", "context": "Service Fulfillment ↔ Compliance", "ai_involvement": "none", "human_approval": true }, { "name": "Retract on material finding", "trigger": "MaterialFindingReported", "condition": "Signed claim materially wrong", "action": "Open Retraction workflow with legal co-sign", "context": "Quality Assurance", "ai_involvement": "assist", "human_approval": true }, { "name": "Alert on delivery failure", "trigger": "DeliveryFailed", "condition": "Any", "action": "Notify customer within 1h + open Success ticket", "context": "Client Delivery & Success", "ai_involvement": "none", "human_approval": false } ], "aggregates": [ { "name": "ServiceEventAggregate", "root": "ServiceEvent", "context": "Service Fulfillment", "purpose": "Guard intake + evidence + draft state transitions.", "entities": [ "ServiceEvent", "EvidenceLink", "Draft" ], "value_objects": [ "ConfidenceScore", "EvidenceCitation" ], "invariants": [ "Every claim in a delivered artifact cites evidence", "A vessel event in state 'delivered' is immutable" ], "commands": [ "OpenIntake", "AttachEvidence", "RequestDraft", "SubmitForSignoff" ], "events": [ "ServiceEventAccepted", "EvidenceCollected", "DraftReady" ], "repository": "ServiceEventRepository", "transaction_boundary": "One vessel event per transaction" }, { "name": "CompletenessPackAggregate", "root": "Notice Completeness Pack", "context": "Service Fulfillment", "purpose": "Own the Notice Completeness Pack lifecycle from signed to delivered.", "entities": [ "Notice Completeness Pack", "Delivery" ], "value_objects": [ "DeliveryAddress" ], "invariants": [ "A Notice Completeness Pack cannot be delivered without a valid Signoff" ], "commands": [ "DeliverCompletenessPack" ], "events": [ "ArtifactDelivered" ], "repository": "CompletenessPackRepository", "transaction_boundary": "One Notice Completeness Pack per transaction" }, { "name": "SignoffAggregate", "root": "Signoff", "context": "Quality Assurance", "purpose": "Bind reviewer identity + timestamp + artifact hash immutably.", "entities": [ "Signoff" ], "value_objects": [ "SignatureManifest" ], "invariants": [ "Signature bound to a live authenticated session, not a form field", "Signed artifacts are immutable" ], "commands": [ "ApproveArtifact" ], "events": [ "ArtifactSigned" ], "repository": "SignoffRepository", "transaction_boundary": "One signoff per transaction" }, { "name": "RetractionAggregate", "root": "Retraction", "context": "Quality Assurance", "purpose": "Handle formal correction/withdrawal of a signed artifact.", "entities": [ "Retraction" ], "value_objects": [ "RetractionReason", "ImpactStatement" ], "invariants": [ "A retraction requires Legal + Reviewer co-signature" ], "commands": [ "FileRetraction" ], "events": [ "RetractionFiled" ], "repository": "RetractionRepository", "transaction_boundary": "One retraction per transaction" }, { "name": "AgentRunAggregate", "root": "AgentRun", "context": "AI Orchestration", "purpose": "Track a single bounded AI run with prompt version, cost, and output validation.", "entities": [ "AgentRun", "RetrievalHit" ], "value_objects": [ "ConfidenceScore", "TokenBudget", "ModelCost" ], "invariants": [ "No output emitted without OutputValidator pass", "Retrieval scoped to a single tenant partition" ], "commands": [ "StartAgentRun" ], "events": [ "DraftProduced", "EscalationRaised" ], "repository": "AgentRunRepository", "transaction_boundary": "One run per transaction" }, { "name": "OwnerActionLedgerAggregate", "root": "OwnerActionLedger", "context": "Compliance & Governance", "purpose": "Own the set of owner-supplied facts blocking public claims.", "entities": [ "OwnerAction" ], "value_objects": [ "BlockerReason", "Jurisdiction" ], "invariants": [ "Release cannot flip to 'ready' with open blocking owner actions" ], "commands": [ "RaiseOwnerAction", "ResolveOwnerAction" ], "events": [ "OwnerActionResolved", "ReleaseDecisionChanged" ], "repository": "OwnerActionRepository", "transaction_boundary": "One ledger per tenant" }, { "name": "TenantAggregate", "root": "Tenant", "context": "Client Onboarding & Profile", "purpose": "Own tenant provisioning + reviewer registration.", "entities": [ "Tenant", "ReviewerIdentity" ], "value_objects": [ "ContactMatrix", "RegimeSet" ], "invariants": [ "Every tenant has at least one named reviewer with valid credential" ], "commands": [ "ProvisionTenant", "RegisterReviewer" ], "events": [ "TenantProvisioned", "ReviewerRegistered" ], "repository": "TenantRepository", "transaction_boundary": "One tenant per transaction" }, { "name": "DeliveryAggregate", "root": "Delivery", "context": "Client Delivery & Success", "purpose": "Own delivery receipts and revision requests.", "entities": [ "Delivery", "RevisionRequest" ], "value_objects": [ "DeliveryMethod" ], "invariants": [ "Every DeliveryConfirmed has a linked Signoff" ], "commands": [ "ConfirmDelivery", "RecordRevisionRequest" ], "events": [ "DeliveryConfirmed", "RevisionRequested" ], "repository": "DeliveryRepository", "transaction_boundary": "One delivery per transaction" } ], "invariants": [ { "invariant": "A Notice Completeness Pack cannot be delivered without a valid Reviewer signoff.", "context": "Service Fulfillment ↔ Quality Assurance", "aggregate": "CompletenessPackAggregate", "why": "Legal defensibility; brand-risk", "enforcement": "Aggregate command handler rejects delivery without a signoff reference" }, { "invariant": "Every claim in a delivered artifact cites at least one evidence item.", "context": "Service Fulfillment", "aggregate": "ServiceEventAggregate", "why": "Audit reconstructability", "enforcement": "EvidenceCoverageSpec on submit-for-signoff" }, { "invariant": "A signature is bound to a live authenticated session, not a form field.", "context": "Quality Assurance", "aggregate": "SignoffAggregate", "why": "Anti-spoofing, anti-repudiation", "enforcement": "Signature service validates session claim server-side" }, { "invariant": "Signed artifacts are immutable; corrections go through Retraction.", "context": "Quality Assurance", "aggregate": "SignoffAggregate + RetractionAggregate", "why": "Preserves audit chain", "enforcement": "Repository denies mutation after signoff" }, { "invariant": "No AI output leaves AI Orchestration without OutputValidator pass.", "context": "AI Orchestration", "aggregate": "AgentRunAggregate", "why": "Grounding + hallucination control", "enforcement": "AgentRun terminates as EscalationRaised on validator failure" }, { "invariant": "Retrieval is scoped to a single tenant partition per call.", "context": "Knowledge Base ↔ AI Orchestration", "aggregate": "IndexShardAggregate", "why": "Prevent cross-tenant lien", "enforcement": "TenantIsolationSpec at retrieval router" }, { "invariant": "Release cannot flip to 'ready' with open blocking owner actions.", "context": "Compliance & Governance", "aggregate": "OwnerActionLedgerAggregate", "why": "Prevent premature public claim", "enforcement": "ReleaseReadinessSpec on ResolveOwnerAction" }, { "invariant": "Every tenant has at least one named reviewer with valid credential.", "context": "Client Onboarding & Profile", "aggregate": "TenantAggregate", "why": "No unattributed signoffs", "enforcement": "ReviewerCredentialSpec on tenant provisioning" }, { "invariant": "Roles are stored in a dedicated table and checked server-side.", "context": "Identity & Access", "aggregate": "UserAggregate", "why": "Prevent privilege escalation", "enforcement": "RoleAuthoritySpec + RLS on protected tables" } ], "ai_agents": [ { "name": "Drafter Agent", "context": "AI Orchestration", "responsibility": "Produce a cited draft of a Notice Completeness Pack section from validated retrieval context.", "inputs": [ "Intake summary", "Retrieval hits (tenant-scoped)", "Prompt version" ], "outputs": [ "Structured draft payload", "Confidence score", "Citations" ], "tools": [ "Retrieval API", "Structured-output validator", "Cost meter" ], "forbidden_actions": [ "Call external tools not in its allowlist", "Access another tenant's retrieval index", "Emit output that skips the OutputValidator", "Author final legal / clinical / financial decisions" ], "memory_scope": "Per-run only; no cross-run memory; prompt-injection scrubber on all customer inputs.", "retrieval_sources": [ "Tenant-scoped knowledge base", "Public regulator sources (read-only cache)" ], "validations": [ "Structured-output schema", "Citation-coverage rule", "PII-scrub rule on prompt inputs" ], "confidence_scoring": "Model-reported logprobs + citation-coverage combined into a bounded [0..1] score.", "escalation_triggers": [ "Score < requirement", "Ambiguous vessel category", "Missing citation on any claim" ], "human_approval": true, "failure_modes": [ "Prompt injection", "Hallucinated citation", "Retrieval-tenant lien" ], "audit_logs": [ "Prompt version", "Retrieval hits (ids only)", "Cost + latency", "Validator verdict" ], "metrics": [ "Draft acceptance rate", "Escalation rate", "Cost per artifact", "p95 latency" ], "versioning": "Prompt versions immutable; published via PromptRegistryAggregate; rollout via feature flag." }, { "name": "Classifier Agent", "context": "AI Orchestration", "responsibility": "Route a vessel event to the right pack template, vessel category, and reviewer queue.", "inputs": [ "Intake payload" ], "outputs": [ "Route decision + confidence" ], "tools": [ "Prompt registry" ], "forbidden_actions": [ "Make final legal / clinical / financial decisions", "Bypass Reviewer queue routing" ], "memory_scope": "Per-run only", "retrieval_sources": [ "Templates + vessel-category reference" ], "validations": [ "Structured-output schema", "Known-route allowlist" ], "confidence_scoring": "Model logprobs.", "escalation_triggers": [ "Score < requirement", "Unknown vessel category" ], "human_approval": false, "failure_modes": [ "Wrong route → wrong reviewer" ], "audit_logs": [ "Route decision + rationale" ], "metrics": [ "Routing accuracy vs reviewer corrections" ], "versioning": "Same as Drafter" }, { "name": "Evaluator Agent", "context": "AI Orchestration", "responsibility": "Run offline evals on prompt versions before rollout.", "inputs": [ "Golden dataset", "Prompt candidate" ], "outputs": [ "Pass/fail per case + drift report" ], "tools": [ "Golden dataset" ], "forbidden_actions": [ "Touch production tenant data" ], "memory_scope": "Per-eval only", "retrieval_sources": [ "Golden dataset only" ], "validations": [ "Regression requirements" ], "confidence_scoring": "Aggregate over dataset", "escalation_triggers": [ "Regression > requirement" ], "human_approval": true, "failure_modes": [ "Overfit to golden dataset" ], "audit_logs": [ "Full eval report archived" ], "metrics": [ "Pass rate", "Regression rate" ], "versioning": "Every prompt release requires a passing eval" } ], "prompt_chain_map": [ "Intake → Classifier (route + vessel 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 requirements 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": "attorney reviewer", "responsibilities": [ "Approve / reject / request revisions on drafts", "Co-sign retractions" ], "contexts": [ "Quality Assurance", "Service Fulfillment" ], "decisions_owned": [ "Signoff", "Rejection", "Escalation acceptance" ], "ai_support": [ "Cited drafts", "Confidence-ranked findings" ], "approval_authority": "Full artifact signoff", "escalation_authority": "Escalate to Legal", "quality_metrics": [ "Cycle time to signoff", "Signoff-to-retraction ratio" ], "workload_risks": [ "Single-reviewer bottleneck" ] }, { "role": "Business owner", "responsibilities": [ "Resolve owner actions", "Decide public-release readiness", "Own commercial claims" ], "contexts": [ "Compliance & Governance", "Sales & Intake" ], "decisions_owned": [ "Release decision", "Owner-action ledger" ], "ai_support": [ "Blocker summary" ], "approval_authority": "Release readiness", "escalation_authority": "Escalate to Legal", "quality_metrics": [ "Blocker close time" ], "workload_risks": [ "Single-owner queue" ] }, { "role": "Legal reviewer", "responsibilities": [ "Retraction co-sign", "DSAR + regulator response" ], "contexts": [ "Quality Assurance", "Compliance & Governance" ], "decisions_owned": [ "Retraction approval", "Regulator response" ], "ai_support": [ "Precedent surfacing (assist only)" ], "approval_authority": "Retraction, regulator response", "escalation_authority": "External counsel", "quality_metrics": [ "Retraction latency" ], "workload_risks": [ "Retainer capacity" ] }, { "role": "Success lead", "responsibilities": [ "Delivery health, revision loop, renewal signal" ], "contexts": [ "Client Delivery & Success" ], "decisions_owned": [ "Escalate silent failures" ], "ai_support": [ "Delivery health digest" ], "approval_authority": "Customer-visible remediation", "escalation_authority": "Owner", "quality_metrics": [ "Time-to-alert on delivery failure" ], "workload_risks": [ "Alert fatigue" ] }, { "role": "Onboarding lead", "responsibilities": [ "Provision tenants, register reviewers, import evidence pack" ], "contexts": [ "Client Onboarding & Profile" ], "decisions_owned": [ "Tenant readiness" ], "ai_support": [ "Checklist coverage" ], "approval_authority": "Go-live per tenant", "escalation_authority": "Owner", "quality_metrics": [ "Time-to-first-artifact" ], "workload_risks": [ "Sequential onboarding queue" ] }, { "role": "Ops (prompt owner)", "responsibilities": [ "Prompt version registry + eval sign-off" ], "contexts": [ "AI Orchestration" ], "decisions_owned": [ "Prompt rollout" ], "ai_support": [ "Evaluator Agent" ], "approval_authority": "Prompt rollout", "escalation_authority": "Engineering", "quality_metrics": [ "Regression rate at rollout" ], "workload_risks": [ "Version drift" ] } ], "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": "vessel 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 (§328.17 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": "Notice Completeness 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 §328.17 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 §328.17 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 reviewer-signed Notice Completeness Pack", "actor": "Customer operator + Reviewer", "context": "Service Fulfillment + Quality Assurance + AI Orchestration", "goal": "Produce and deliver a reviewer-signed Notice Completeness Pack", "preconditions": [ "Tenant provisioned", "Reviewer registered", "Engagement accepted" ], "main_flow": [ "Operator opens vessel event", "Evidence attached / retrieved", "AI Orchestrator drafts with citations", "Reviewer approves", "Delivery adapter delivers", "Success lead confirms delivery" ], "alternative_flows": [ "Confidence below requirement → 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", "DeliverCompletenessPack" ], "events": [ "ServiceEventAccepted", "EvidenceCollected", "DraftProduced", "ArtifactSigned", "ArtifactDelivered" ], "aggregates": [ "ServiceEventAggregate", "AgentRunAggregate", "SignoffAggregate", "CompletenessPackAggregate" ], "success": "Notice Completeness Pack delivered + 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 + attorney 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 → Notice Completeness Pack lifecycle", "owned_domain": [ "ServiceEvent", "Draft", "Notice Completeness Pack", "Delivery" ], "application_services": [ "OpenIntake", "AttachEvidence", "SubmitForSignoff", "DeliverCompletenessPack" ], "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 lien", "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": "attorney 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 requirement" ] }, { "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": "CompletenessPackAggregate 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 requirement" }, { "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": [ "[PLACEHOLDER] owner to complete" ], "human_workflows": [ "Reviewer signoff" ], "data_needs": [ "vessel event", "field evidence", "Notice Completeness 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": "Regulator-facing claim proves incorrect", "likelihood": "medium", "impact": "severe", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Every claim linked to a cited source + reviewer signoff", "owner": "legal", "context": "Compliance & Governance" }, { "risk": "AI hallucination in a delivered artifact", "likelihood": "medium", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Retrieval-first pipeline + structured output validation + reviewer gate", "owner": "engineering", "context": "AI Orchestration / Knowledge Base" }, { "risk": "Cross-tenant data lien", "likelihood": "low", "impact": "severe", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Row-level auth + per-tenant retrieval indices + log-scrubbing", "owner": "engineering", "context": "AI Orchestration / Knowledge Base" }, { "risk": "Design partner churns before contract", "likelihood": "medium", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Weekly working-session cadence; documented value moments; owner-action ledger", "owner": "owner", "context": "Service Fulfillment" }, { "risk": "Compliance framework demand exceeds team capacity", "likelihood": "high", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "SOC 2 Type I year one; map controls once, evidence continuously", "owner": "ops", "context": "Compliance & Governance" }, { "risk": "Single-region outage takes production down", "likelihood": "low", "impact": "high", "signal": "See ProductBlueprintDNA / risk register for tuned early-warning signals", "mitigation": "Multi-AZ managed database; nightly cross-region backup", "owner": "engineering", "context": "Service Fulfillment" } ], "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, search 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 lien 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 current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Ubiquitous language quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Subdomain classification quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Bounded context clarity", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Core domain focus", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Context map quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Aggregate design quality", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Invariant quality", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "AI-agent responsibility design", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Human review safety", "score": 9, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Data ownership clarity", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Integration protection", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs land real data." }, { "category": "Implementation feasibility", "score": 8, "weakness": "None material at this stage.", "improvement": "Maintain current standard; re-audit after the first 8 pilot marinas and 20 released Packs 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 current standard; re-audit after the first 8 pilot marinas and 20 released Packs 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 current standard; re-audit after the first 8 pilot marinas and 20 released Packs 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": [ "Florida-licensed maritime attorney reviewer to validate release-gate ergonomics", "Refrigeration SME on invoice-field and vessel-identity 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 SlipLienClear. Preserve the invariant that no Notice Completeness Pack leaves the system without a signed human release — analyst on green/yellow, Florida-licensed maritime attorney reviewer on red. Do not launch commercially until owner-action facts close and at least one human-released Notice Completeness 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 SlipLienClear 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": [ "[PLACEHOLDER] owner to complete" ] }, "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": "SlipLienClear 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 lienage", "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 requirements 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 lien 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": "FLHSMV finalizes a rule change touching §328.17 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": "CompletenessPackAggregate", "scenario": "Concurrent command on CompletenessPackAggregate", "invariant_at_risk": "A Notice Completeness 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 requirements", "verdict": "holds" } ], "regulated_domain_handling": [ { "regime": "FLHSMV Fla. Stat. §328.17 ER&R (Fla. Stat. §328.17) with CAA maritime counsel documented-vessel handling", "applies_because": "Owner-side lien-notice records are inspectable by FLHSMV on demand; sale-continuity filings go to FLHSMV (always customer-submitted).", "controls": [ "Cited rule provision per claim", "attorney reviewer release on red packs" ], "evidence_required": [ "rule-to-record map", "Pack release records + register rows" ] } ], "unit_economics": { "price_model": "Per-pack complexity tiers (green/yellow/red) + per-vessel monthly register retainer", "unit_of_value": "Released fl-marina-possessory-lien-notice-completeness-pack-engine Notice Completeness 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": [ "[PLACEHOLDER] owner to complete" ] }, { "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-DeliverCompletenessPack-DeliveryFailed", "severity": "info", "message": "Command DeliverCompletenessPack references event 'DeliveryFailed' not present in domain_events", "refs": [ "DeliverCompletenessPack", "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", "CompletenessPackAggregate", "SignoffAggregate", "RetractionAggregate", "AgentRunAggregate", "OwnerActionLedgerAggregate", "TenantAggregate", "DeliveryAggregate" ], "events": [ "serviceEventAccepted", "EvidenceCollected", "DraftReady", "EscalationRaised", "ReviewerSigned", "ArtifactDelivered", "OwnerActionResolved", "RetractionFiled" ], "commands": [ "OpenIntake", "AttachEvidence", "StartAgentRun", "ApproveArtifact", "DeliverCompletenessPack", "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 Notice Completeness 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", "search 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": "fl-marina-possessory-lien-notice-completeness-pack-engine", "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": [ "[PLACEHOLDER] owner to complete" ] }, "architecture": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "archetypes": [ "regulated system", "CRUD/workflow application", "internal operations platform" ], "archetype_impact": "Vessel regime is a global query parameter — every read/write is scoped by vessel, regulatory category, and notice-clock window, 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 (agency lien-notice records, attestation signers, 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 (SlipProvider)", "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 when its throughput or a distinct scaling profile (e.g. search-vendor volume) justifies an independent deployment; 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 when its throughput or a distinct scaling profile (e.g. search-vendor volume) justifies an independent deployment; 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 when its throughput or a distinct scaling profile (e.g. search-vendor volume) justifies an independent deployment; 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 when its throughput or a distinct scaling profile (e.g. search-vendor volume) justifies an independent deployment; 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, search-result, and Pack-delivery payload schemas tested per consumer; the notice/lienholder JSON contract between AI layers is schema-pinned." }, "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, provider-agnostic prompt contracts; second vendor configured for failover so a released Notice Completeness Pack never depends on one model.", "prompt_mgmt": "Extraction, notice-drafting, and lienholder-matrix prompts held in versioned files; eval-gated deploys; one-step rollback.", "rag": "Versioned Fla. Stat. §328.17 rule pack + FLHSMV procedure notes retrieved with statute-scoped filters; drafting is grounded and citation-anchored to statute text, never free-form legal generation.", "vector": "Not pre-revenue; the §328.17 rule pack is small and structured, so keyword/section lookups suffice until a larger corpus justifies similarity search.", "embeddings": "Deferred with the vector store; rule-pack keys are structured (element, search source, subsection), not semantic.", "eval": "Gold set of specialist-released Packs: notice-element extraction F1 and completeness-gate agreement per model release; identity-match accuracy vs specialist labels reviewed monthly.", "hitl": "Notice-specialist release and the Florida-attorney gate on high-value/documented vessels are never automated; sampling QA on 10% of Packs plus counsel red-team on the first 20.", "guardrails": "Field-locked five-element templates, amount-ties-to-ledger rule, four-source search-completeness rule, and SCRA screen — a draft missing a statutory field emits MISSING_ELEMENT rather than inventing content.", "prompt_injection": "Ledger and search-result text is treated as data, never instructions; the red-team suite includes injected-instruction PDFs disguised as ledgers.", "leakage": "Marina and vessel-owner identifiers scoped per case; retrieval scoped per marina; provider training-use disabled; no cross-marina corpus.", "fallback": "Manual specialist workbench runbook plus the second LLM vendor keep Pack production moving if the primary model is unavailable.", "latency_cost": "Inference cost per Pack ≤ ~$8 at launch → ≤ ~$4 by year 1; the 5-business-day SLA leaves generous headroom over model latency.", "memory": "Agents are stateless per case; durable knowledge lives in the versioned §328.17 rule pack and SOP library, not model memory.", "tool_permissions": "The prompt runner has no tool access beyond returning JSON; search ordering, PDF 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 notice element carries the §328.17 subsection it satisfies, and every matrix lienholder carries its source search." }, "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 (agency lien-notice records, attestation signers, 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 + useSyncExternalSlip 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 fl-marina-possessory-lien-notice-completeness-pack-engine]\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 Slip[(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[Slip: 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; LEDGER[Ledger + vessel data as DATA]-->P1[Extract + normalize identity]-->SRCH[Order 4-source lien search]-->MTX[Build lienholder matrix]-->DRAFT[Draft 5-element notices]-->GATE[Deterministic completeness gates]-->SPEC[Notice specialist release]-->DEL[Deliver Pack]; GATE-.exception.->SPEC; SPEC-.high-value/documented.->ATT[Florida attorney 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 (agency lien-notice records, attestation signers, 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 lien" ], "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 lien 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 (agency lien-notice records, attestation signers, 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-binder tabs with regime chip) and accent (register-slate) are network invariants — respect them." ] } } }, "design": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "archetypes": [ "compliance/regulatory tool", "workflow tool", "operations system" ], "user_mindset": { "goals": "Produce a defensible §328.17 record while a 60-day notice clock may already be running.", "session_length": "Bursty around delinquency events and the December–March aging season; otherwise weekly-digest review.", "confidence": "Expert users; will not accept opaque AI output.", "interface_needs": "Print-parity layouts, citation chains, freeze/approval states." }, "posture": [ "authoritative", "trustworthy", "operational" ], "density": "compact", "trust_level": { "tier": "high", "sensitive_domains": [ "dockage service records", "vessel registry data", "FLHSMV sale-continuity filings" ], "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 signer on any outbound artifact.", "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é: snowflake clip-art and alarm-red penalty banners" ], "strategy": "Anchor on the pack-binder tabs with regime chip as the recurring signature element; every page must include it at least once. Reserve the register-slate accent for evidence/status signals only." }, "territories": [ { "name": "Pack Binder", "color_mood": "register slate + parchment", "typography": "Söhne + Serif Display", "density": "tabbed binder", "component_feel": "government form set", "motion": "tab-first", "fits": "inspector parity", "risks": "bureaucratic feel" }, { "name": "Portfolio Atlas", "color_mood": "map ink + civic navy", "typography": "Neue Haas Grotesk", "density": "map-driven", "component_feel": "store atlas + vessel pins", "motion": "map pan", "fits": "multi-site portfolios", "risks": "requires site geo data" }, { "name": "Repair-Clock Timeline", "color_mood": "slate + amber", "typography": "Inter", "density": "timeline", "component_feel": "gantt of duties", "motion": "scroll-sync", "fits": "recurring delinquencys and clocks", "risks": "gantt fatigue" } ], "chosen_territory": "Pack Binder", "chosen_rationale": "The pack is the deliverable; the binder metaphor keeps every screen artifact-shaped, the way an inspector would ask for it.", "prioritized_components": [ { "name": "Regime chip", "why": "every vessel is scoped by regulatory category and dockage/ODS regime" }, { "name": "Repair-clock card w/ deadline", "why": "primary time-critical work unit" }, { "name": "Notice Completeness Pack assembler", "why": "output is a bundle with a hard-fail checklist" } ], "patterns": [ { "name": "Regime switcher", "description": "Global vessel-regime selector; every query respects it." }, { "name": "Pack release sign-off", "description": "Named analyst or attorney reviewer with attestation copy; red packs cannot release without the reviewer." } ], "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": [ "Binder tab motif", "Gap-register-not-invented-data copy discipline" ], "cliches_avoided": [ "Snowflake clip-art", "Green-check compliance theatre", "Penalty-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": "203 71% 19%", "brand-fg": "205 44% 97%", "surface": "210 20% 97%", "ink": "200 41% 12%", "muted": "200 16% 34%", "accent": "36 100% 30%" }, "type": { "display": "'Georgia', ui-serif, serif", "body": "system-ui, -apple-system, 'Segoe UI', sans-serif", "fonts_url": "" }, "signature": { "motif": "Pack cover + lienholder matrix row", "render": "dossier-tabs" } }, "seo": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "archetype": "regulator-fluent authority site", "archetype_impact": "Search fit is a regulator-fluent authority site. That means depth over breadth: each page cites the specific rule/section it addresses, and thin variants are refused.", "authority_dna": { "site_archetype": "regulator-fluent authority site", "monetization_model": "B2B lead → validation call → paid engagement (not ad revenue; not affiliate).", "main_search_intents": [ "informational", "commercial" ], "topical_authority_opportunity": "Own the \"Florida marina §328.17 lien-sale notice\" topic cluster by covering the entire owner-side duty — possessory-lien attachment, the five notice elements, the DHSMV/USCG/UCC/judgment search, posting at the marina and vessel, the 60-day window, the newspaper advertisement, and title-transfer exhibits — better than any single-post law-firm alert.", "local_seo_opportunity": "Not justified: buyers search by regulator/rule, not by city. Do not build /city/ pages.", "global_national_opportunity": "National (US-first) is the primary market. International only if the regulator itself is cross-border (e.g., EU AI Act, VAT, CBP).", "easiest_ranking_path": "Long-tail, statute-specific queries (\"Florida marina unpaid dockage lien notice requirements\", \"§328.17 newspaper advertisement timing\", \"how to put a lien on a boat in Florida\") where the SERP is dominated by out-of-date law-firm alerts and agency PDFs.", "hardest_ranking_path": "Head terms like \"marina management software\" — dominated by aged SaaS vendor domains. Defer until authority is established.", "trust_credibility_requirements": [ "Named human authors with role + credentials", "Rule / statute / agency citations on every claim", "Last-reviewed date + change log on regulatory pages", "Direct links to primary agency source (not aggregators)", "Expert reviewer attribution on YMYL pages" ], "ymyl": true, "expert_review_needed": true, "site_structure": "Authority hub + narrow high-intent service page + linkable evidence assets. Not a directory. Not a marketplace.", "seo_moat": "always-current §328.17 rule-mapped pages with change-log timestamps (incl. the May 2026 TRU exclusion)" }, "search_market": { "primary_markets": [ "Fla. Stat. §328.17 §328.17 lien-notice workflow", "FLHSMV dockage possessory-lien notice production" ], "secondary_markets": [ "lien records inspection-readiness", "lien-notice evidence", "lien-notice records checklist" ], "low_competition_subtopics": [ "§328.17 edge cases", "missing invoice-field handling", "Fla. Stat. §328.17 lien repair for grocery and foodservice" ], "high_commercial_intent": [ "dockage compliance service for grocery chains", "done-for-you dockage lien-notice records", "lien-notice documentation services", "dockage compliance documentation consultant" ], "informational": [ "what is the Fla. Stat. §328.17 15 lb rule", "FLHSMV dockage lien repair requirements explained", "§328.17 recordkeeping guide" ], "local_intent": [ "[PLACEHOLDER] owner to complete" ], "transactional": [ "Fla. Stat. §328.17 compliance service demo", "lien-notice pack pricing", "book a lien records consultation" ], "comparison": [ "done-for-you lien-notice packs vs marina billing software", "dockage compliance service alternatives" ], "problem_solution": [ "how to survive a lien records inspection", "lien-notice evidence gap", "30-day repair deadline missed" ], "near_me": [ "[PLACEHOLDER] owner to complete" ], "long_tail": [ "Fla. Stat. §328.17 lien repair for vessel coolers", "dockage completeness score calculation state-titled method example", "aging repeat-delinquency report The publication window requirements" ], "questions": [ "what records does §328.17 require?", "who owns §328.17 lien-notice records?", "when does the 60-day notice clock end?", "how long does a Notice Completeness Pack take?" ], "emerging": [ "AI-assisted lien recordkeeping", "automated lien-notice evidence" ], "seasonal": [ "The publication window sale-continuity filing deadline", "calendar-year aging cumulative review" ], "underserved_serps": [ "§328.17 edge cases", "missing invoice-field handling" ], "weak_serps": [ "lien-notice records checklist", "dockage completeness score requirements 30 20 10" ], "forum_dominated_serps": [ "what happens if you miss the 30-day repair window", "dockage lien-notice penalty amounts" ], "winnable_authoritative_serps": [ "Fla. Stat. §328.17 lien repair definitive guide", "§328.17 lien-notice evidence requirements" ], "avoid_initially": [ "marina billing software", "dockage compliance platform", "best dockage tracking tools" ], "easy_wins": [ "§328.17 edge cases", "lien-notice records checklist", "dockage notice-clock and The publication window deadlines" ], "moderate": [ "Fla. Stat. §328.17 lien repair definitive guide", "lien records inspection-readiness" ], "long_term_plays": [ "marina billing software", "portfolio lien registers for large operators" ], "do_not_pursue": [ "generic \"how to start a compliance business\" content", "celebrity or trend-jacking posts", "AI-generated listicles" ] }, "keyword_clusters": [ { "primary": "§328.17 lien-notice evidence requirements", "related": [ "Fla. Stat. §328.17 audit-ready lien records", "lien-notice evidence checklist" ], "intent": "commercial", "user_problem": "Inspection, insurer, or diligence request is coming and dockage evidence is scattered across vendor inboxes", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "SERP dominated by outdated law-firm alerts and FLHSMV PDFs", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Pillar / evidence guide", "reason": "High buyer intent + weak SERP + our unique proof", "priority_score": 17, "priority": "P0", "bucket": "easy-win" }, { "primary": "done-for-you lien-notice packs vs marina billing software", "related": [ "dockage compliance service alternatives", "marina billing software comparison" ], "intent": "commercial", "user_problem": "Evaluating a SaaS seat nobody will operate vs a documentation service", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "medium", "conversion_potential": "high", "content_effort": "medium", "serp_weakness": "Weak — mostly self-serving SaaS 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": "lien-notice records checklist", "related": [ "§328.17 owner checklist", "lien records audit checklist" ], "intent": "informational", "user_problem": "Wants a concrete one-page artifact covering the five records an inspector asks for", "funnel": "MOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Weak — thin listicles", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Resource / lead magnet page", "reason": "Easy win + strong lead-magnet fit", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "dockage notice-clock and The publication window deadlines", "related": [ "60-day notice clock §328.17", "aging repeat-delinquency report deadline" ], "intent": "informational", "user_problem": "Needs authoritative deadline info for notice clocks and the The publication window aging report", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "low", "conversion_potential": "medium", "content_effort": "low", "serp_weakness": "Weak — outdated pages ranking", "local_relevance": "low", "global_relevance": "high", "suggested_page_type": "Data table page (updated quarterly)", "reason": "Recurring seasonal traffic + easy freshness moat", "priority_score": 14, "priority": "P0", "bucket": "easy-win" }, { "primary": "§328.17 edge cases", "related": [ "documented-vessel R-22 and dockage sites", "method switch state-titled path vs documented path", "TRU exclusion May 2026" ], "intent": "informational", "user_problem": "Facing a scenario the standard guides do not cover (documented-vessel store, method switch, mid-year vessel-identity change)", "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 product page", "priority_score": 13, "priority": "P0", "bucket": "easy-win" }, { "primary": "marina billing software", "related": [ "dockage compliance platform", "best dockage tracking tools" ], "intent": "commercial", "user_problem": "Ready to buy", "funnel": "BOFU", "business_value": "high", "ranking_difficulty": "high", "conversion_potential": "high", "content_effort": "high", "serp_weakness": "Strong — aged SaaS 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": "Fla. Stat. §328.17 lien repair definitive guide", "related": [ "FLHSMV dockage lien repair requirements explained", "what is the Fla. Stat. §328.17 15 lb rule" ], "intent": "informational", "user_problem": "Just inherited dockage compliance responsibility and needs to orient", "funnel": "TOFU", "business_value": "medium", "ranking_difficulty": "medium", "conversion_potential": "low", "content_effort": "high", "serp_weakness": "Moderate — mostly generic vendor 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": [ "Fla. Stat. §328.17 §328.17 lien repair — definitive guide", "Lien-notice evidence & inspection-readiness", "Rule library (§328.17, maritime counsel, state overlays)" ], "pillars": [ { "name": "Fla. Stat. §328.17 §328.17 lien repair — definitive guide", "core_intent": "informational", "audience": "marina office managers, ops leaders, and controllers", "conversion_goal": "Newsletter / checklist download → later validation call", "supporting_pages": [ "The 15-lb rule explained", "Lien-rate methods: state-titled path vs documented path, worked examples", "§328.17 edge cases (documented-vessel, method switch, TRU exclusion)", "§328.17 FAQs" ], "internal_links": [ "/product", "/rules/flhsmv/328-17/", "/resources/checklist" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (where genuine)" ], "evidence_needed": [ "Named reviewer", "Primary-source citations", "Worked example" ], "local_variants": [ "[PLACEHOLDER] owner to complete" ], "national_variants": [ "US-national (default)" ] }, { "name": "Lien-notice evidence & inspection-readiness", "core_intent": "commercial", "audience": "marina office managers, ops leaders, and controllers", "conversion_goal": "Book validation call", "supporting_pages": [ "§328.17 lien-notice evidence requirements", "Lien records audit checklist", "Common lien-notice evidence gaps (the invoice with no quantity)" ], "internal_links": [ "/product", "/guides/fl-328-17-lien-notice/", "/resources/evidence-checklist" ], "schema": [ "Article", "FAQPage", "BreadcrumbList", "HowTo (only for real workflow)" ], "evidence_needed": [ "Worked evidence artifact", "Regulator citation", "Reviewer credential" ], "local_variants": [], "national_variants": [ "US-national" ] }, { "name": "Rule library", "core_intent": "informational", "audience": "marina office managers, ops leaders, and controllers", "conversion_goal": "Assisted conversion via internal linking", "supporting_pages": [ "FLHSMV Fla. Stat. §328.17 — dockage lien repair, rules and citations", "CAA maritime counsel / Fla. Stat. Part 82 — ODS regime, rules and citations", "Repeat-delinquency reporting (≥60-day, The publication window) — rules and citations", "Verification tests (initial + follow-up) — rules and citations", "Full-charge determination methods — rules and citations", "TRU exclusion (final rule, May 2026) — rules and citations", "CARB / state dockage overlays — rules and citations" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/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", "rule-change explainer", "worked example", "FAQ", "comparison (only when honest)", "case study (only with permission)", "evidence artifact / template", "regulator update log" ] }, "site_architecture": { "homepage_strategy": "Above-the-fold: one-sentence purpose + primary CTA (validation call). Below: 3 problem-cards linking to pillars, 1 evidence-asset teaser, 1 authority statement with named reviewer.", "main_nav": [ "Product", "How it works", "Pillars", "Resources", "About", "Contact" ], "footer_nav": [ "Editorial policy", "Contact", "Privacy", "Terms", "Sitemap", "Changelog" ], "hubs": [ { "name": "Product / service", "url": "/product", "purpose": "High-intent commercial page" }, { "name": "Guides pillar", "url": "/guides", "purpose": "Topical authority hub" }, { "name": "Rule library", "url": "/rules", "purpose": "Entity/regulation reference" }, { "name": "Resources", "url": "/resources", "purpose": "Linkable assets (templates, checklists)" }, { "name": "Changelog", "url": "/changelog", "purpose": "Freshness + trust signal" } ], "url_patterns": [ "/product", "/guides/[topic]/", "/guides/[topic]/[subtopic]/", "/rules/[regulator]/[rule]/", "/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)", "Any duplicate /service/ and /solutions/ trees" ] }, "global_national": { "national_clusters": [ "Fla. Stat. §328.17 §328.17 lien repair — definitive guide", "FLHSMV dockage lien-notice compliance workflow", "§328.17 evidence checklist", "lien records inspection-readiness" ], "linkable_assets": [ "One-page §328.17 owner checklist (downloadable, gated by email is OK)", "Rule-to-record mapping table (HTML + PDF)", "Change-log / FLHSMV rule update tracker (incl. TRU exclusion)", "Worked completeness-score examples (state-titled path + documented path, fixture data labeled illustrative)" ], "original_research_ideas": [ "Annual multi-site lien records readiness benchmark (survey of ~50 operators)", "Invoice completeness index: share of vessel ledgers missing §328.17 fields (anonymized intake data)", "State dockage overlay variation index (where applicable)" ], "international_needed": false, "international_notes": "Not needed. US-first. Do not build hreflang variants." }, "local_seo": { "justified": false, "reason": "Buyers search by regulator/rule, not by city. Local pages would be doorway pages.", "gbp_categories_primary": [ "[PLACEHOLDER] owner to complete" ], "gbp_categories_secondary": [ "[PLACEHOLDER] owner to complete" ], "location_page_rules": [ "Do not build location pages for this blueprint." ], "citations": [ "[PLACEHOLDER] owner to complete" ], "review_strategy": "Reviews are not a Local ranking factor here; use G2/Capterra + case studies instead.", "local_schema": [ "[PLACEHOLDER] owner to complete" ] }, "programmatic": { "recommended": false, "reason": "Programmatic pages almost always become doorway pages in regulated niches. Prefer a small number of deeply-researched pages.", "rules": [ "Only allowed for genuinely differentiated data (e.g., a state-by-state rule table where each state truly differs)", "Every programmatic page must include: unique data field + unique local/regulatory content + human review before publish", "noindex until minimum quality requirement met", "Rel=canonical to the pillar when a page falls below requirement" ], "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": [ "Editorial review before indexation", "Quarterly re-review or noindex", "Automated thin-content detector (<300 words unique) blocks publish" ] }, "page_templates": [ { "page_type": "Homepage", "purpose": "State the offer + route to validation call.", "target_intent": "commercial", "url_pattern": "/", "h1_pattern": "[One-sentence purpose]", "title_pattern": "[Brand] — [One-sentence purpose]", "meta_description_pattern": "One sentence outcome + CTA verb. ≤ 155 chars.", "above_the_fold": [ "H1", "Sub-headline (audience + outcome)", "Primary CTA (validation call)", "1 trust chip (reviewer / cite)" ], "outline": [ "Problem framing", "3 pillar cards", "Evidence asset teaser", "Named reviewer statement", "Contact" ], "internal_links": [ "/product", "/guides", "/resources", "/about" ], "conversion_elements": [ "Calendar CTA", "Checklist download secondary" ], "schema": [ "Organization", "WebSite", "SearchAction" ], "trust_elements": [ "Reviewer name", "Editorial policy link" ], "media": [ "Original workflow diagram (SVG)" ], "faq_opportunities": [ "Top 3 buyer questions" ], "cta_strategy": "Above-the-fold soft + end-of-page primary", "quality_requirements": [ "Loads < 2.5s LCP", "Named reviewer visible" ], "anti_thin_rules": [ "No stock hero", "No generic 'we help X do Y' filler" ] }, { "page_type": "Pillar page", "purpose": "Anchor a topic cluster with a definitive explanation.", "target_intent": "informational", "url_pattern": "/guides/[topic]/", "h1_pattern": "[Topic] — Definitive Guide", "title_pattern": "[Topic] — Definitive Guide | [Brand]", "meta_description_pattern": "Definition + what the reader will learn + reviewer credential.", "above_the_fold": [ "H1", "40–60 word definition block", "TOC", "Last-reviewed date + reviewer" ], "outline": [ "Definition", "Who this applies to", "Workflow", "Rules & citations", "Edge cases", "FAQs", "Related pages" ], "internal_links": [ "Cluster sub-pages", "Rule library", "Product" ], "conversion_elements": [ "End-of-page checklist download", "Sidebar validation call CTA" ], "schema": [ "Article", "BreadcrumbList", "FAQPage (only real FAQs)" ], "trust_elements": [ "Named author + reviewer", "Primary source cites" ], "media": [ "Original diagrams", "Rule comparison table" ], "faq_opportunities": [ "Real questions from practitioners" ], "cta_strategy": "Assist conversion via internal link to product; primary CTA end-of-page.", "quality_requirements": [ "≥ 1500 words unique", "≥ 3 primary sources cited", "Reviewer credential visible" ], "anti_thin_rules": [ "No listicles padded with keyword variants", "No AI-generated body" ] }, { "page_type": "How-to cluster page", "purpose": "Answer a specific workflow question inside a cluster.", "target_intent": "informational", "url_pattern": "/guides/[topic]/[subtopic]/", "h1_pattern": "[Specific action or question]", "title_pattern": "[Specific action] — [Pillar topic] | [Brand]", "meta_description_pattern": "Concrete outcome + who it applies to + one caveat.", "above_the_fold": [ "H1", "Direct answer paragraph", "Numbered steps preview" ], "outline": [ "Direct answer", "Steps", "Edge cases", "Common mistakes", "Related pages" ], "internal_links": [ "Pillar page", "Sibling clusters", "Product" ], "conversion_elements": [ "End-of-page checklist download", "Related tool link" ], "schema": [ "Article", "HowTo (only if real workflow)", "BreadcrumbList" ], "trust_elements": [ "Named author", "Reviewer for YMYL" ], "media": [ "Screenshots of the actual workflow" ], "faq_opportunities": [ "Follow-up questions" ], "cta_strategy": "Contextual link to product mid-page; primary CTA end-of-page.", "quality_requirements": [ "Unique steps not duplicated from pillar", "Reviewer date visible" ], "anti_thin_rules": [ "No spun variants of the pillar" ] }, { "page_type": "Product / service page", "purpose": "Convert commercial intent.", "target_intent": "commercial", "url_pattern": "/product", "h1_pattern": "[Outcome-focused headline]", "title_pattern": "[Brand] — [Outcome]", "meta_description_pattern": "State the outcome + primary CTA verb.", "above_the_fold": [ "H1", "Sub-headline", "Primary CTA", "Trust chip" ], "outline": [ "Problem", "How we solve it", "Proof / worked example", "Objection handling", "FAQ", "CTA" ], "internal_links": [ "Case study", "Pillar guide", "Evidence checklist" ], "conversion_elements": [ "Calendar", "Secondary checklist" ], "schema": [ "Service or SoftwareApplication (whichever fits)", "Organization", "FAQPage" ], "trust_elements": [ "Named reviewer", "Primary-source cites", "Contact info" ], "media": [ "Screenshot of the actual workflow, not marketing composites" ], "faq_opportunities": [ "Buyer objections" ], "cta_strategy": "Above-the-fold + repeated end-of-page", "quality_requirements": [ "Unique per audience segment (no doorway variants)" ], "anti_thin_rules": [ "No thin '/services/X/' spin-offs of the same page" ] }, { "page_type": "Rule / regulation reference page", "purpose": "Serve as the site's citation-grade reference for a specific rule.", "target_intent": "informational", "url_pattern": "/rules/[regulator]/[rule]/", "h1_pattern": "[Regulator] — [Rule] explained", "title_pattern": "[Rule] — [Regulator] Requirements | [Brand]", "meta_description_pattern": "What the rule requires + last-reviewed date.", "above_the_fold": [ "H1", "Definition", "Last-reviewed + reviewer" ], "outline": [ "What the rule says", "Who it applies to", "Deadlines", "Evidence required", "Change log" ], "internal_links": [ "Pillar guide", "Product" ], "conversion_elements": [ "Subscribe to change-log", "Sidebar validation call" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Primary-source link", "Visited-on date", "Reviewer credential" ], "media": [ "Rule comparison table" ], "faq_opportunities": [ "Real practitioner questions" ], "cta_strategy": "Assist conversion via internal link", "quality_requirements": [ "Primary source link required", "Quarterly re-review" ], "anti_thin_rules": [ "No auto-generated rule scraping without human review" ] }, { "page_type": "Comparison page", "purpose": "Serve genuine BOFU comparison intent.", "target_intent": "commercial", "url_pattern": "/compare/[a]-vs-[b]/", "h1_pattern": "[A] vs [B] — Honest Comparison", "title_pattern": "[A] vs [B] | [Brand]", "meta_description_pattern": "Honest side-by-side + when to pick which.", "above_the_fold": [ "H1", "TL;DR verdict", "When-to-pick block" ], "outline": [ "Criteria", "Side-by-side table", "Where each wins", "Where each loses", "Recommendation" ], "internal_links": [ "Product", "Pillar guide" ], "conversion_elements": [ "Calendar CTA", "Evidence checklist" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Disclose the reviewer's relationship to each option" ], "media": [ "Feature comparison table" ], "faq_opportunities": [ "'Which should I choose?' style" ], "cta_strategy": "End-of-page primary CTA to the fitting option", "quality_requirements": [ "Honest even when it hurts", "Disclose relationship" ], "anti_thin_rules": [ "No manufactured 'X vs Y' pages for every pair" ] }, { "page_type": "FAQ page", "purpose": "Aggregate genuine practitioner questions.", "target_intent": "informational", "url_pattern": "/faq", "h1_pattern": "FAQ", "title_pattern": "[Topic] FAQ | [Brand]", "meta_description_pattern": "Answers to the questions we hear most.", "above_the_fold": [ "H1", "Table of contents" ], "outline": [ "Grouped questions", "Each answer 40–120 words" ], "internal_links": [ "Relevant pillars and rule pages" ], "conversion_elements": [ "End-of-page CTA" ], "schema": [ "FAQPage (only for genuine FAQs visible on-page)" ], "trust_elements": [ "Named reviewer" ], "media": [], "faq_opportunities": [ "Real questions only — never invented" ], "cta_strategy": "Related-block links, not inline mid-answer", "quality_requirements": [ "No invented questions" ], "anti_thin_rules": [ "No 'is X the best' padding" ] }, { "page_type": "Glossary term page", "purpose": "Definition-grade authority for a single term.", "target_intent": "informational", "url_pattern": "/glossary/[term]/", "h1_pattern": "[Term]", "title_pattern": "[Term] — Definition | [Brand]", "meta_description_pattern": "Concise definition + who uses the term.", "above_the_fold": [ "H1", "40-word definition" ], "outline": [ "Definition", "Related terms", "Where it applies", "Common misuses" ], "internal_links": [ "Pillar", "Rule pages" ], "conversion_elements": [ "Sidebar related-tool link" ], "schema": [ "Article", "BreadcrumbList", "DefinedTerm" ], "trust_elements": [ "Cite the primary source of the definition" ], "media": [], "faq_opportunities": [], "cta_strategy": "Assist via internal link", "quality_requirements": [ "Never duplicate the pillar's intro" ], "anti_thin_rules": [ "No glossary spam" ] }, { "page_type": "Case study page", "purpose": "Concrete outcome-based proof.", "target_intent": "commercial", "url_pattern": "/case-studies/[slug]/", "h1_pattern": "[Outcome achieved for [customer type]]", "title_pattern": "Case Study — [Outcome] | [Brand]", "meta_description_pattern": "Concrete outcome + timeframe + method.", "above_the_fold": [ "H1", "Outcome metric", "Approved-for-publication chip" ], "outline": [ "Context", "Approach", "Outcome", "Reviewer quote" ], "internal_links": [ "Product", "Pillar guide" ], "conversion_elements": [ "End-of-page CTA" ], "schema": [ "Article", "BreadcrumbList" ], "trust_elements": [ "Named customer contact (with permission)" ], "media": [ "Redacted artifact screenshots" ], "faq_opportunities": [], "cta_strategy": "End-of-page primary CTA", "quality_requirements": [ "Written approval on file" ], "anti_thin_rules": [ "No fabricated case studies" ] } ], "on_page_rules": { "title_tag": "Pattern: [Primary keyword] — [Angle] | SlipLienClear. ≤ 60 chars. Front-load the keyword. No clickbait.", "meta_description": "≤ 155 chars. State the specific outcome. Include a verb + a rule citation when applicable. No stuffing.", "headings": "One H1. H2s follow the workflow steps or the searcher's questions. H3s for edge cases. No decorative headings.", "intro": "First 100 words: define the topic in the searcher's language + name the specific rule/agency + preview what the page delivers.", "snippet_targeting": "Add a 40–60 word definition block and a numbered how-to block near the top for featured snippet + AI overview eligibility.", "tables_lists": "Use tables for rule comparisons, deadlines, and requirements. Lists for steps. Never use tables for layout.", "images": "Original diagrams/screenshots preferred. Descriptive alt text. WebP. Explicit width/height. Never AI slop stock art.", "internal_links": "Every page: ≥3 contextual links up to pillar, ≥2 to sibling cluster pages, ≥1 to a commercial page.", "external_citations": "Cite the primary source (agency PDF / statute) — not aggregators — with the visited-on date.", "author_attribution": "Named author + role + linked bio page. Reviewer for YMYL.", "freshness": "Last-reviewed date at top; change log at bottom for regulator pages; quarterly review cadence.", "cta_placement": "Above the fold (soft), mid-page (contextual to the section), end-of-page (primary).", "mobile": "Single-column, tap targets ≥44px, no interstitials, no autoplay video.", "avoid": [ "Keyword stuffing", "AI-generated body copy without human edit", "Doorway variants", "Unsupported superlatives ('best', 'top-rated') without evidence", "Meta descriptions duplicated across pages", "Marking up invisible content in schema" ] }, "entity_seo": { "main_entities": [ "Fla. Stat. §328.17", "Fla. Stat. §328.17", "FLHSMV", "unpaid dockages", "completeness score", "notice clock", "aging repeat-delinquency report", "vessel identity" ], "related_entities": [ "GWP > 53", "15-lb requirement", "60-day completeness-score requirements", "lien-search verification", "3-year records" ], "people": [ "Named practitioners (role-titles)", "Florida-licensed maritime attorney reviewers", "FLHSMV officials referenced" ], "orgs": [ "FLHSMV", "FMI", "state grocers associations", "restaurant associations", "CARB" ], "tools": [ "Rule library", "Lien-rate worksheets", "Change-log tracker" ], "regulations": [ "Fla. Stat. §328.17 (Fla. Stat. §328.17 ER&R)", "CAA maritime counsel / Fla. Stat. Part 82", "Fla. Stat. §19.4 penalty adjustments", "TRU exclusion final rule (May 2026)", "CARB dockage rules" ], "problems": [ "§328.17 recordkeeping risk", "Inspection failure", "Missed 60-day notice clock", "Unnoticed 60-day aging requirement", "Evidence gap" ], "solutions": [ "Notice Completeness Pack workflow", "Portfolio Lien Register", "Rule-mapped checklists" ], "processes": [ "Invoice intake", "Vessel resolution", "Lien-rate computation", "Release review", "Deliver & register", "Aging watch" ], "alternatives": [ "marina billing software", "bundled search compliance managers", "law firm alerts" ], "synonyms": [ "dockage lien repair records", "dockage completeness score documentation", "dockage compliance binder", "audit-ready" ] }, "schema_strategy": [ { "type": "Organization", "where": "Site-wide in head", "required_fields": [ "name", "url", "logo", "sameAs" ], "caution": "Keep in sync with visible About / contact." }, { "type": "WebSite + SearchAction", "where": "Homepage", "required_fields": [ "name", "url", "potentialAction" ], "caution": "Only if on-site search actually exists." }, { "type": "BreadcrumbList", "where": "All hub / cluster / rule / glossary pages", "required_fields": [ "itemListElement" ], "caution": "Order must match visible breadcrumbs." }, { "type": "Article", "where": "Guides, pillars, rule pages", "required_fields": [ "headline", "author", "datePublished", "dateModified" ], "caution": "Author must exist as a real person." }, { "type": "FAQPage", "where": "Genuine FAQ pages only", "required_fields": [ "mainEntity[]" ], "caution": "Only mark up FAQs visible on the page." }, { "type": "HowTo", "where": "Real step-by-step workflows only", "required_fields": [ "name", "step[]" ], "caution": "Google narrowed HowTo eligibility; use sparingly." }, { "type": "Person", "where": "Author bio pages", "required_fields": [ "name", "jobTitle", "sameAs" ], "caution": "Credentials must be real and verifiable." } ], "internal_linking": { "pillar_to_cluster": "Pillar links to every direct cluster page in a curated section (not a mega-menu dump).", "cluster_to_pillar": "Every cluster page links back to its pillar in the intro and in-context.", "cluster_to_cluster": "Link between sibling clusters only where the user's next question naturally leads there.", "service_to_location": "Not applicable.", "faq_to_commercial": "Answer the question first, then link to the commercial page in a 'related' block — never inline mid-answer.", "breadcrumbs": "Structured breadcrumbs on all guide, rule, and glossary pages.", "anchor_text_rules": [ "Descriptive — match the target page's H1 concept", "Vary phrasing across links to the same target", "Never exact-match keyword stuffing", "Anchor must make sense read aloud" ] }, "technical_seo": { "crawlability": "Flat depth (≤3 clicks from homepage). No orphan pages. HTML sitemap on /sitemap.", "indexability": "Index all real content. noindex utility pages, thank-you pages, and gated-asset landing pages.", "sitemaps": "XML sitemap generated at build time. Split by section if > 5k URLs.", "robots": "robots.txt allows all; disallow /admin/, /api/. Reference sitemap.", "canonicals": "Self-referencing canonical on every page. Filter/sort variants canonical to the base.", "pagination": "Prefer 'load more' or a single long page; if paginated, use rel=next/prev semantics via internal linking.", "faceted_nav": "Not applicable for this blueprint (no product catalog).", "duplicate_control": "One URL per topic. Consolidate before publishing new variants. No www/non-www split.", "redirects": "301 for permanent moves; audit chains monthly; never 302 for SEO redirects.", "core_web_vitals": "LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1. Test with real-user monitoring.", "mobile": "Mobile-first design. No tap-target failures. No horizontal scroll.", "accessibility": "WCAG AA. Semantic HTML. Landmarks. Focus states. Alt text.", "js_seo": "Content in the initial HTML. Client hydration for interactivity only.", "rendering": "Static generation preferred; SSR only where personalized. Never client-only for indexable pages.", "gsc_setup": "Verify both www and apex; submit sitemap; monitor Coverage and Enhancements weekly.", "analytics_setup": "GA4 + server-side event stream. Consent Mode v2. Event schema documented.", "rank_tracking": "Semrush or Ahrefs project set to US database; track pillar + top-20 clusters weekly." }, "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 expert with disclosed credentials.", "editorial_policy": "Public /editorial-policy page: sourcing rules, review cadence, correction policy.", "fact_checking": "Every statute/rule reference has a link + visited-on date; corrections dated and disclosed.", "credentials": [ "Florida Bar admission (reviewer)", "Relevant professional licensure where public" ], "citations": "Cite primary sources (agency PDF, statute text). No citation of aggregator blogs.", "first_hand_proof": [ "Screenshots of the actual workflow", "Redacted worked examples", "Signed reviewer statement" ], "update_cadence": "Regulatory pages reviewed quarterly; commercial pages reviewed twice yearly.", "monetization_disclosure": "Public disclosure that leads convert to paid engagements; no undisclosed affiliate content.", "ymyl_notes": "This is YMYL. Language stays cautious (\"may\", \"depends on facts\"); documentation support only — no legal-advice framing, no penalty-avoidance promises; disclaimer near CTA." }, "ai_search": { "principles": [ "Answer the exact question in the first paragraph", "Provide a 40–60 word extractable definition near the top", "Structured lists and tables for facts", "Cite named primary sources", "Author + reviewer names on-page" ], "tactics": [ "FAQPage schema for genuine FAQs (not stuffed)", "HowTo schema for real workflow pages", "Consistent entity naming across the site", "Concise summaries at the top of long guides" ], "do_not": [ "Write pages targeting AI systems instead of humans", "Insert hidden 'AI-only' content", "Create bespoke llms.txt / manifests that bypass normal quality", "Mass-generate answers to invented questions" ] }, "conversion": { "primary_cta": "Start a pack run from your most recent vessel ledger (or book a validation call).", "secondary_cta": "Run the free AIM Exposure Diagnostic / download the §328.17 owner checklist (email capture).", "lead_magnets": [ "Free AIM Exposure Diagnostic (human-reviewed Gap Score in 24h)", "One-page §328.17 owner checklist (PDF)", "Quarterly FLHSMV rule change-log subscription" ], "trust_elements": [ "Named reviewer + credentials", "Rule citations visible on-page", "Change-log timestamps", "Contact + address in footer" ], "per_page_paths": [ { "page_type": "Homepage", "path": "Hero CTA → validation call. Secondary → guides pillar." }, { "page_type": "Pillar", "path": "TOC → deep sub-pages. End-of-page → validation call." }, { "page_type": "Cluster / how-to", "path": "In-content 'related tool' link → product. End-of-page → checklist download." }, { "page_type": "Product / service", "path": "Above-the-fold CTA → calendar. Objection-handling block → FAQ." }, { "page_type": "Rule page", "path": "Sidebar → related workflow (product). Bottom → subscribe to change-log." } ], "tracking": "GA4 events: cta_click, checklist_download, calendar_book. Server-side dedupe. Weekly funnel review." }, "link_earning": { "digital_pr_ideas": [ "Annual \"Fla. Stat. §328.17 §328.17\" lien records readiness benchmark report", "Invoice completeness index with a shareable result page", "FLHSMV rule-change tracker with an RSS feed" ], "original_research": [ "Small operator survey (n≥30) once per year", "State-by-state dockage overlay variation index" ], "directories": [ "G2 / Capterra category pages", "Industry association member lists", "Regulator resource pages when eligible" ], "expert_contributions": [ "HARO / Qwoted / Featured expert responses", "Bylined articles in industry trade press", "Podcast interviews with practitioners" ], "partnerships": [ "Association CLE / CPE sponsorships", "Co-authored guides with adjacent (non-competing) vendors" ], "avoid": [ "Paid link schemes", "PBNs", "Mass guest posting", "Fake reviews", "Reciprocal link exchanges" ] }, "roadmap_90d": [ { "phase": "Days 0–30: Foundation", "goal": "Establish trust + ship product page + first pillar.", "pages": [ "Homepage", "Product page", "Pillar: Fla. Stat. §328.17 §328.17 lien repair — definitive guide", "About + reviewer bio (role-titles)", "Editorial policy", "Contact" ], "keywords_targeted": [ "Fla. Stat. §328.17 lien repair", "Fla. Stat. §328.17 15 lb rule guide" ], "why_first": "Without a trust surface + a real product page, everything else is unmoored.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Reviewer bio", "Editorial policy", "One workflow diagram" ], "internal_links": [ "Homepage ↔ Product ↔ Pillar" ], "conversion_goal": "First validation calls booked" }, { "phase": "Days 31–60: Topical authority core", "goal": "Publish the first cluster of 5–7 supporting pages under the pillar + evidence checklist lead magnet.", "pages": [ "§328.17 edge cases", "Lien-rate calculation step by step (state-titled path + documented path)", "§328.17 FAQs", "§328.17 owner checklist (lead magnet)", "Repair-clock and The publication window deadlines" ], "keywords_targeted": [ "§328.17 edge cases", "lien-notice records checklist", "dockage notice clock deadlines" ], "why_first": "Easy-win SERPs that assist conversion to the product page.", "difficulty": "low", "business_value": "medium", "required_assets": [ "Checklist PDF", "Rule table" ], "internal_links": [ "All clusters ↔ pillar ↔ product" ], "conversion_goal": "Checklist downloads + assisted conversions" }, { "phase": "Days 61–90: Reference & freshness", "goal": "Ship the rule library + first regulator change-log post + first comparison page.", "pages": [ "Rule page: Fla. Stat. §328.17", "Rule page: CAA maritime counsel documented-vessel", "Rule page: sale-continuity filinging (The publication window)", "Comparison: done-for-you lien-notice packs vs marina billing software", "Q1 FLHSMV rule change-log" ], "keywords_targeted": [ "Fla. Stat. 328.17", "possessory-lien vs Fla. Stat. §328.17", "aging repeat-delinquency report The publication window" ], "why_first": "Reference pages compound in authority; change-log establishes freshness signal.", "difficulty": "medium", "business_value": "medium", "required_assets": [ "Primary-source citations", "Reviewer sign-off" ], "internal_links": [ "Rule pages ↔ pillar ↔ product; comparison → product" ], "conversion_goal": "BOFU comparison conversions" } ], "roadmap_12m": [ { "phase": "Months 4–6: Linkable assets", "goal": "Ship the annual benchmark, the cost-of-non-compliance calculator, and the state variation index (if applicable).", "pages": [ "Annual lien records readiness benchmark", "Invoice completeness index", "State dockage overlay variation index" ], "keywords_targeted": [ "lien records benchmark", "dockage compliance cost", "state dockage rules comparison" ], "why_first": "Linkable assets drive referring domains and topical authority signals.", "difficulty": "medium", "business_value": "high", "required_assets": [ "Survey data", "Named methodology", "Reviewer sign-off" ], "internal_links": [ "From every pillar + product" ], "conversion_goal": "Calculator → validation call handoff" }, { "phase": "Months 7–9: Depth + freshness cadence", "goal": "Expand each pillar with 3 more cluster pages + quarterly regulator change-log.", "pages": [ "Additional cluster pages (per pillar)", "Q3 regulator change-log", "First case study (with permission)" ], "keywords_targeted": [ "Long-tail cluster expansions" ], "why_first": "Compounding topical coverage + freshness moat.", "difficulty": "low", "business_value": "medium", "required_assets": [ "Customer approval for case study" ], "internal_links": [ "Sibling cluster interlinking" ], "conversion_goal": "Assisted conversions" }, { "phase": "Months 10–12: Scale + prune", "goal": "Consolidate weak pages, refresh top pages, expand into 1 adjacent topic only if authority is proven.", "pages": [ "Consolidation redirects", "Top-10 page refreshes", "Adjacent topic scoping" ], "keywords_targeted": [ "Existing top-10 clusters" ], "why_first": "Optimization > net-new after a critical mass is reached.", "difficulty": "low", "business_value": "high", "required_assets": [ "Analytics review", "Consolidation plan" ], "internal_links": [ "Redirect audit" ], "conversion_goal": "CTR + conversion-rate lift" } ], "priority_pages": [ { "rank": 1, "page_title": "§328.17 lien-notice evidence requirements", "slug": "/guides/328-17-lien-notice-evidence-requirements/", "page_type": "Pillar / evidence guide", "primary_keyword": "§328.17 lien-notice evidence requirements", "secondary_keywords": [ "Fla. Stat. §328.17 audit-ready lien records", "lien-notice evidence checklist" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P0", "why_opportunity": "High buyer intent + weak SERP + our unique proof" }, { "rank": 2, "page_title": "Done-for-you lien-notice packs vs marina billing software", "slug": "/compare/lien-notice-packs-vs-dockage-saas/", "page_type": "Comparison page (honest, evidence-based)", "primary_keyword": "lien-notice packs vs marina billing software", "secondary_keywords": [ "dockage compliance service alternatives", "marina billing software comparison" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "medium", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P0", "why_opportunity": "Late-funnel intent with weak competition" }, { "rank": 3, "page_title": "§328.17 owner records checklist", "slug": "/guides/328-17-records-checklist/", "page_type": "Resource / lead magnet page", "primary_keyword": "lien-notice records checklist", "secondary_keywords": [ "§328.17 owner checklist", "lien records audit checklist" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Easy win + strong lead-magnet fit" }, { "rank": 4, "page_title": "Lien notice-clock and The publication window deadlines", "slug": "/guides/notice-clock-march-1-deadlines/", "page_type": "Data table page (updated quarterly)", "primary_keyword": "dockage notice-clock and The publication window deadlines", "secondary_keywords": [ "60-day notice clock §328.17", "aging repeat-delinquency report deadline" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Recurring seasonal traffic + easy freshness moat" }, { "rank": 5, "page_title": "§328.17 edge cases", "slug": "/guides/328-17-edge-cases/", "page_type": "How-to cluster page", "primary_keyword": "§328.17 edge cases", "secondary_keywords": [ "documented-vessel R-22 and dockage sites", "method switch state-titled path vs documented path", "TRU exclusion May 2026" ], "intent": "informational", "scope": "national", "funnel": "MOFU", "difficulty": "low", "business_value": "medium", "conversion_potential": "medium", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P0", "why_opportunity": "Easy win + high assist to product page" }, { "rank": 6, "page_title": "Lien tracking software (deferred)", "slug": "/guides/dockage-tracking-software/", "page_type": "Product page (defer)", "primary_keyword": "marina billing software", "secondary_keywords": [ "dockage compliance platform", "best dockage tracking tools" ], "intent": "commercial", "scope": "national", "funnel": "BOFU", "difficulty": "high", "business_value": "high", "conversion_potential": "high", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Book validation call", "production_priority": "P1", "why_opportunity": "Long-term play — do not chase before authority is built" }, { "rank": 7, "page_title": "Fla. Stat. §328.17 lien repair — definitive guide", "slug": "/guides/fl-328-17-lien-notice-definitive-guide/", "page_type": "Pillar page", "primary_keyword": "Fla. Stat. §328.17 lien repair definitive guide", "secondary_keywords": [ "FLHSMV dockage lien repair requirements explained", "what is the Fla. Stat. §328.17 15 lb rule" ], "intent": "informational", "scope": "national", "funnel": "TOFU", "difficulty": "medium", "business_value": "medium", "conversion_potential": "low", "required_proof": [ "Named reviewer", "Primary-source cites", "Worked example" ], "internal_links": [ "/guides/fl-328-17-lien-notice/", "/product", "/rules/flhsmv/328-17/" ], "schema": [ "Article", "BreadcrumbList" ], "cta": "Download checklist", "production_priority": "P1", "why_opportunity": "Anchors topical authority for the whole cluster" } ], "competitor_gaps": { "typical_competitor_types": [ "marina billing software", "bundled search compliance managers", "law firm alerts" ], "common_weaknesses": [ "Outdated regulator citations", "Missing last-reviewed date", "No named author or reviewer", "Copy-paste content across state / product variants", "No worked examples", "Thin FAQ padded with generic questions", "Poor mobile Core Web Vitals" ], "how_to_beat_them": [ "Fresh citations with visited-on dates", "Named reviewer + credentials visible", "Real, redacted worked examples", "Better structured tables for rule comparisons", "Faster + more accessible pages" ] }, "metrics": { "weekly": [ "GSC impressions/clicks by pillar", "Top-20 keyword position", "New indexed pages", "Core Web Vitals regressions" ], "monthly": [ "Organic sessions by hub", "Assisted conversions", "CTR by template", "Content decay list (positions dropped)", "Backlink net-new" ], "quarterly": [ "Pillar coverage audit", "Rule freshness audit", "Consolidation / prune list", "Conversion path funnel review" ], "annual": [ "Full topical authority audit", "Benchmark report refresh", "Editorial policy refresh" ] }, "risks": [ { "risk": "Thin content", "applies": true, "mitigation": "Minimum-word + reviewer-sign-off gate before publish." }, { "risk": "Duplicate content across state/product variants", "applies": true, "mitigation": "One URL per topic; no auto-generated variants; canonical to pillar." }, { "risk": "Doorway location pages", "applies": true, "mitigation": "Local pages are refused for this vertical — buyers search by regulator, not city." }, { "risk": "Keyword cannibalization", "applies": true, "mitigation": "Topic ownership map; kill or 301 the weaker duplicate." }, { "risk": "AI-generated body without human edit", "applies": true, "mitigation": "Editorial policy forbids it; reviewer sign-off required." }, { "risk": "Unsupported YMYL claims", "applies": true, "mitigation": "Cautious language + primary-source cites + reviewer credential." }, { "risk": "Bad schema (marking up invisible content)", "applies": true, "mitigation": "Schema linter in CI; only markup what is on-page." }, { "risk": "Link spam / paid link schemes", "applies": true, "mitigation": "Editorial link-earning only; documented policy." }, { "risk": "Review manipulation", "applies": false, "mitigation": "Post-engagement organic prompts only; no incentives; no gating negatives." }, { "risk": "Index bloat from tag/archive pages", "applies": true, "mitigation": "noindex utility archives; canonical to hub." }, { "risk": "Compliance risk in claims", "applies": true, "mitigation": "Legal review of marketing claims; disclaimer near CTAs." }, { "risk": "Programmatic doorway pages", "applies": true, "mitigation": "Programmatic refused unless per-page uniqueness rules are met." } ], "first_20_pages": [ "Homepage", "Product / service page", "About + reviewer bio (role-titles)", "Editorial policy", "Contact", "Privacy", "Pillar: Fla. Stat. §328.17 §328.17 lien repair — definitive guide", "Lien-rate calculation step by step (state-titled path + documented path)", "§328.17 edge cases", "§328.17 FAQs", "Pillar: lien-notice evidence & inspection-readiness", "§328.17 lien-notice evidence requirements", "Lien records audit checklist", "Repair-clock and The publication window deadlines", "§328.17 owner checklist (lead magnet)", "Rule page: Fla. Stat. §328.17", "Rule page: CAA maritime counsel documented-vessel", "Rule page: sale-continuity filinging", "Comparison: done-for-you lien-notice packs vs marina billing software", "Q1 FLHSMV rule change-log post" ], "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 reviewer bio(s)", "Public editorial policy + correction policy", "Cite primary regulator sources with visited-on dates", "Launch checklist lead magnet", "Pitch 3 HARO / Qwoted responses per week", "Publish 1 original data point / benchmark", "Reach out to 5 non-competing directories", "Guest post on 1 industry association blog", "Podcast interview outreach (5 shows)", "Set up quarterly regulator change-log post cadence" ], "final_recommendation": "Build a regulator-fluent authority site around \"Fla. Stat. §328.17 §328.17 lien repair\". Ship the first 20 pages in 90 days (product + pillar + rule library + evidence assets), then compound with quarterly FLHSMV 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 penalty figures without the actual-penalties-vary caveat.", "disclaimers": [ "All volume/difficulty/CPC 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 topic: language must stay cautious; nothing here is legal/medical/financial advice." ] }, "microsite": { "category": "Legal-ops / regulatory documentation", "shortTitle": "SlipLienClear", "audience": "office managers, owners, and harbor masters at independent Florida marinas (50–300 slips)", "problem": "A vessel is 60+ days past due and still in its slip, and the owner has stopped answering. Under Fla. Stat. §328.17 the marina already holds a possessory lien — but to start the 60-day nonjudicial-sale clock it needs a defect-free notice: the five statutory elements, notice to every lienholder found across DHSMV, USCG, UCC, and Florida judgment-lien records, posting at the marina and on the vessel, and a certified-mail packet. Marina billing software ages the receivable; it never assembles any of that. Get one element or one search wrong and the sale can be voided.", "offer": "On SlipLienClear, marina staff stop guessing at §328.17 and start releasing packs. Send us the vessel's ledger, HIN, and slip agreement; AI extracts and normalizes the identity and amounts, we order the four-source lien search in parallel, deterministic rules check all five notice elements and the 60-day window, and a notice specialist releases a Notice Completeness Pack — mail-ready and posting-ready — in five business days. Florida-attorney review on any high-value or federally documented vessel.", "faq": [ { "q": "Is SlipLienClear for the marina office or for counsel?", "a": "For the marina office. At 50–300 slips the office manager or controller owns A/R and there's no in-house maritime counsel. We do the clerical-legal production — searches, notices, posting and mail packet — and route the legal judgment calls to a Florida attorney when they arise." }, { "q": "How is a pack run audit-ready?", "a": "Every noticed lienholder traces to a DHSMV/USCG/UCC/judgment search receipt, and every amount ties to your ledger. Missing items ship as explicit exceptions, never invented. A notice specialist signs every release; a Florida-licensed maritime attorney reviews any high-value or federally documented vessel before it ships." }, { "q": "What arrives at the end of a pack run?", "a": "A Notice Completeness Pack PDF — itemized claim, five-element §328.17 notices for the owner and each lienholder, the four-source lien-search evidence log, a posting checklist for the marina and the vessel, a certified-mail packet with prepared labels, and a 60-day calendar — plus the register row for your Portfolio Lien Register." }, { "q": "What if the boat is documented with the Coast Guard?", "a": "Then we order a USCG (NVDC) abstract to surface any preferred ship mortgage or lien claimant, on top of the DHSMV, UCC, and judgment searches. Documented and out-of-state vessels fall in the higher tier because the search work is heavier, and they trigger mandatory attorney review until we've completed 20 clean packs." }, { "q": "How fast, and what do you need from me?", "a": "Five business days from complete intake. We need the ledger/aging, the slip agreement, the vessel HIN and photos, any prior notices, and a signed limited authorization to order searches on your behalf — plus your attestation that the amounts and dates are accurate." }, { "q": "Do you run the auction or handle the money?", "a": "No. We stop at the released pack (and, with the add-on, the newspaper-ad draft and sale-day checklist). You conduct any sale, hold any surplus for the owner as §328.17(12) requires, and handle title transfer with the bill of sale we help you assemble under §328.17(13)." }, { "q": "Are you a debt collector?", "a": "No. We never contact the vessel owner or debtor. You send the notices under your own name; we only prepare the documentation and run the searches." }, { "q": "What does it cost?", "a": "Flat fee per released pack: $399 founding, $499 standard, $599–$799 for documented, out-of-state, or multi-lienholder vessels. The Delinquency Gap Scan is free. Never hourly, never a percentage of what you recover." }, { "q": "Can this work outside Florida?", "a": "Not yet. §328.17 is Florida-specific and the search stack (DHSMV, Florida judgment liens) is built for Florida. Other states come only once we've productized their playbooks." } ], "process": [ { "title": "Intake: send the ledger and vessel details", "body": "Send the ledger/aging, slip agreement, vessel HIN and photos, and sign a limited authorization so we can order searches as your agent. Each document is logged and hashed on arrival; missing items are flagged before any work starts, not after." }, { "title": "Order the four-source search", "body": "We order DHSMV ownership, a USCG abstract (if the vessel is documented), a UCC search, and a Florida judgment-lien search — in parallel to protect the five-business-day SLA — and build a lienholder matrix from the results, with every claimant tied to a source." }, { "title": "Draft and score in deterministic rules", "body": "AI drafts the five statutory notice elements into a field-locked §328.17 template for the owner and each lienholder. Deterministic code — not a language model — confirms all five elements are present, ties the itemized claim to the ledger to the dollar, sets the 60-day window, and screens for SCRA and out-of-state search duties." }, { "title": "Specialist release gate", "body": "A notice specialist certifies every release. Anything ambiguous — unconfirmed identity, an incomplete search, an SCRA indicator, or a vessel over $150k or federally documented — is held for a Florida-licensed maritime attorney to review before anything ships." }, { "title": "Deliver and calendar", "body": "The Notice Completeness Pack PDF, prepared certified-mail labels, and a 60-day calendar (ICS) land in your portal the same day it's released. You mail, post at the marina and on the vessel, and hold for 60 days; send us the green cards and we log them." } ], "northStarCta": { "label": "Start a free Delinquency Gap Scan", "href": "/contact", "secondary_label": "See what's in the pack", "secondary_href": "/how-it-works" }, "ubiquitousLanguage": { "audience": "office managers, owners, and harbor masters at independent Florida marinas (50–300 slips)", "domain": "Florida marina possessory-lien notice production (Fla. Stat. §328.17)", "deliverable": "Notice Completeness Pack + specialist release (Florida-attorney review on high-value or documented vessels)", "reviewer": "Florida-licensed maritime attorney", "record": "Portfolio Lien Register (aging watch with draft triggers)", "unit_of_work": "pack run", "cta_primary": "Start a free Delinquency Gap Scan", "cta_secondary": "See what's in the pack", "regulator": "FLHSMV", "regulator_full": "Florida Department of Highway Safety and Motor Vehicles", "statute": "Fla. Stat. §328.17", "trigger_moment": "a vessel 60+ days past due, an unresponsive owner, or a diligence request before a sale", "event_intake_started": "fl_marina_possessory_lien_notice_completeness_pack_engine_intake_started", "event_conversation_requested": "fl_marina_possessory_lien_notice_completeness_pack_engine_conversation_requested" }, "trust": { "standards": [ "Documentation-completeness service — not a law firm, debt collector, or auctioneer", "Every noticed party traces to a lien-search receipt; gaps ship as explicit exceptions", "Specialist release on every pack; Florida-attorney review on high-value or documented vessels" ], "response_time": "5 business days from complete intake", "data_handling": "Per-marina isolated files, least-privilege access, hash-stamped originals, audit trail retained for the notice and any sale" }, "hook": "Clear a dead slip without a defective §328.17 notice voiding your sale.", "sub_headline": "You send the delinquent vessel's ledger, HIN, and slip agreement. You get back a specialist-released Notice Completeness Pack — five statutory notice elements, a DHSMV/USCG/UCC/judgment lien search, a posting checklist, a certified-mail packet, and your 60-day calendar — in five business days, flat fee.", "dream_outcome": "A mail-ready, post-ready, audit-ready §328.17 pack that starts the 60-day clock cleanly — so a blocked revenue slip becomes a cleared slip without title liability.", "specific_pains": [ "A boat in Slip B-14 is 74 days past due, and nobody has drafted the five §328.17 notice elements or confirmed whether the owner even still holds title — the ledger just says 'past due, see file.'", "Ask for the lien-search record on a delinquent vessel and someone opens a folder of PDFs — that is the record a title examiner, insurer, or buyer would find first.", "A general model can draft a plausible-looking notice; only a verified DHSMV/USCG/UCC/judgment search with a specialist release produces a pack a later title transfer won't unwind.", "The vessel is documented with the Coast Guard, so a preferred ship mortgage may sit behind it — miss the USCG abstract and you've noticed the wrong parties.", "A title examiner reads the file as a package: itemized claim, four-source search, notices to every lienholder, posting proof, and the 60-day calendar. Miss any leg and the sale is exposed." ], "cost_of_inaction": "Every month the slip stays blocked is lost revenue, and a vessel left long enough becomes derelict — removal runs into the hundreds of dollars per foot (a ~$750/ft benchmark). A defective notice is worse: it can void the sale and start a title fight.", "mechanism": { "name": "The SlipLienClear §328.17 notice pack factory", "steps": [ { "title": "Intake: send the ledger and vessel details", "body": "Send the ledger/aging, slip agreement, vessel HIN and photos, and sign a limited authorization so we can order searches as your agent. Each document is logged and hashed on arrival; missing items are flagged before any work starts, not after." }, { "title": "Order the four-source search", "body": "We order DHSMV ownership, a USCG abstract (if the vessel is documented), a UCC search, and a Florida judgment-lien search — in parallel to protect the five-business-day SLA — and build a lienholder matrix from the results, with every claimant tied to a source." }, { "title": "Draft and score in deterministic rules", "body": "AI drafts the five statutory notice elements into a field-locked §328.17 template for the owner and each lienholder. Deterministic code — not a language model — confirms all five elements are present, ties the itemized claim to the ledger to the dollar, sets the 60-day window, and screens for SCRA and out-of-state search duties." }, { "title": "Specialist release gate", "body": "A notice specialist certifies every release. Anything ambiguous — unconfirmed identity, an incomplete search, an SCRA indicator, or a vessel over $150k or federally documented — is held for a Florida-licensed maritime attorney to review before anything ships." }, { "title": "Deliver and calendar", "body": "The Notice Completeness Pack PDF, prepared certified-mail labels, and a 60-day calendar (ICS) land in your portal the same day it's released. You mail, post at the marina and on the vessel, and hold for 60 days; send us the green cards and we log them." } ] }, "offer_stack": [ { "item": "Notice Completeness Pack per vessel event", "note": "itemized claim, five-element §328.17 notices for the owner and each lienholder, four-source lien search with evidence log, posting checklist, certified-mail packet, 60-day calendar, specialist release" }, { "item": "Four-source lien search", "note": "DHSMV ownership, USCG abstract (if documented), UCC, and Florida judgment liens — assembled into a lienholder matrix; a search we can't complete ships as an explicit exception, never a guess" }, { "item": "Specialist release on every pack", "note": "a notice specialist certifies completeness; a Florida-licensed maritime attorney reviews any vessel over $150k or federally documented, and any contested matter" }, { "item": "Posting & certified-mail packet", "note": "posting checklist for the marina and the vessel, plus prepared certified-mail labels for every noticed party" }, { "item": "Sale Continuity Add-on", "note": "for use only after the 60-day window: draft newspaper sale advertisement (2 consecutive weeks; sale ≥15 days after first publication), sale-day checklist, and the §328.17(13) title-transfer exhibit list" }, { "item": "Portfolio Lien Register", "note": "an aging watch for marinas with multiple delinquencies — draft triggers when a vessel crosses the 60-day mark (post-MVP)" } ], "guarantee": "If a released pack is missing any of the five statutory notice elements or a lien search we committed to run, we correct and re-release it at no charge. The guarantee covers documentation completeness against the §328.17 checklist we deliver against — not any legal outcome or that a court will uphold the sale. Cancel before release for a full refund of the pack fee (disclosed pass-through search fees already incurred are non-refundable).", "urgency": "The 60-day clock only starts once a clean notice is mailed and posted — every week of delay is another week the slip stays blocked and the vessel edges toward derelict.", "objections": [ { "q": "\"Aren't you a law firm, or giving legal advice?\"", "a": "No. SlipLienClear is a documentation-completeness service. We prepare the notice and run the searches as your clerical agent under written authorization; we don't advise whether you should sell, opine on lien priority, or represent you. For legal questions — or a high-value or federally documented vessel — we recommend and can arrange Florida-attorney review." }, { "q": "\"Aren't you debt collectors? Will you call the boat owner?\"", "a": "Never. We do not contact the vessel owner or debtor. You remain the lien claimant and the party who sends the notices under your own name. Staying on the documentation side of the line keeps you clear of FDCPA/FCCPA collector exposure." }, { "q": "\"Doesn't our marina software already handle this?\"", "a": "Aging software (Molo, DockMaster) is great at invoices and finance charges. It does not assemble the five-element §328.17 notice, run the DHSMV/USCG/UCC/judgment search, produce the posting checklist, or prepare the certified-mail packet. That's the specific gap we fill." }, { "q": "\"Will we be relying on an AI-drafted legal notice?\"", "a": "No figure or gate in a pack comes from a language model. AI extracts fields with source references and drafts the notice into a field-locked §328.17 template; deterministic code checks the five elements, ties amounts to your ledger, and sets the 60-day window; a notice specialist signs every release. If a source isn't attached, the field ships as an explicit gap." } ], "who_this_is_not_for": [ "Marinas that want us to contact the owner, run the auction, or handle sale proceeds — that's yours (or your counsel's) to conduct; we stop at the released pack.", "Buyers looking for a \"guarantee the sale won't be challenged\" — we decline that engagement and document the ask; nobody can honestly sell it.", "Mega-marina platforms with captive legal departments, pure yacht clubs without an unpaid-slip problem, or non-Florida marinas until we've built the state playbook." ], "proof_pillars": [ { "title": "Four-source search, tied to evidence", "body": "Every noticed lienholder traces to a DHSMV, USCG, UCC, or judgment-lien search receipt in the evidence log. A search we can't complete is an explicit exception, not a silent omission." }, { "title": "Specialist-released, every time", "body": "No pack auto-releases. A notice specialist certifies every pack; a Florida-licensed maritime attorney reviews any high-value or federally documented vessel and any contested matter — attesting to documentation completeness only, never as your legal representative." }, { "title": "Statute-locked, element by element", "body": "The five §328.17 notice elements, the 60-day window, and the posting requirement are checked in deterministic code against the statute text — the pack renders the checklist, it doesn't describe it." } ], "stakes_line": "Undocumented means unprovable: a title examiner reads the whole §328.17 file, and a missing leg is a voided sale.", "deliverable": "Notice Completeness Pack", "unit_of_work": "pack run", "lexicon": { "regulator": "FLHSMV", "regulator_full": "Florida Department of Highway Safety and Motor Vehicles", "statute": "Fla. Stat. §328.17", "statute_frame": "the intake-to-pack workflow where an unreleased pack is a self-inflicted title risk on any nonjudicial sale.", "persona": "Marina office manager", "persona_moment": "You're the office manager at an independent Florida marina. A vessel in Slip B-14 is 74 days past due and the owner has gone quiet. Someone needs a §328.17 notice pack that will actually start the 60-day clock — with every lienholder found and every element in place.", "trigger_moment": "a vessel 60+ days past due, an unresponsive owner, or a diligence request before a sale", "enforcement_stakes": "a defective notice can void the nonjudicial sale and expose the marina to a title dispute (outcomes vary case-by-case and are never guaranteed)", "retention": "the full audit trail of the notice and any sale", "cta_verb": "Start a free Delinquency Gap Scan", "intake_checklist": [ "The ledger or aging report showing amounts and due dates, exactly as it stands", "The slip or storage agreement for the delinquent vessel (or a note that none exists)", "Vessel identity: HIN, Florida registration or USCG documentation number, length overall, make and model, and slip number", "Photos showing the HIN plate and the vessel still in its slip", "Any prior notices or correspondence already sent to the owner", "A signed limited authorization letting us order record searches as your agent", "A signed attestation that the ledger amounts and dates are accurate" ], "trust_standards_specific": [ "Every notice element and lien-search result in a Notice Completeness Pack traces to a source you supplied or a search receipt in the evidence log — gaps ship as explicit exceptions, never invented data", "A notice specialist certifies every release; a Florida-licensed maritime attorney reviews every high-value or federally documented vessel before it ships", "Records — intake, searches, and the released pack — are held as an audit trail you can hand to a title examiner, insurer, or buyer on demand" ], "regulator_faqs": [ { "q": "Do you sign the pack as our legal representative?", "a": "No — you remain the lien claimant and duty holder under §328.17. Our notice specialist signs the release, a Florida-licensed maritime attorney reviews high-value or documented vessels, you attest the ledger amounts, and any decision to sell — plus the mailing, posting, and any sale — is made and executed by you." }, { "q": "How long is the record retained?", "a": "The full audit trail of the notice and any sale is held — hash-stamped, per-marina isolated, and mirrored to your own storage — so a title examiner, insurer, or buyer can read it on demand years later." }, { "q": "What if the ledger lands on a Friday?", "a": "Intake runs continuously. First packs release within about five business days of complete intake; searches are ordered in parallel so vendor turnaround, not our queue, sets the pace." } ] }, "proof_angle": { "id": "audit-readiness", "headline": "The next records request lands on a file, not a project — SlipLienClear holds the 3-year trail at rest.", "lever": "SlipLienClear stores every §328.17 decision — source quote, locked method, releaser — in a 3-year, vessel-indexed register an inspector can walk without your help.", "outcome_verb": "answer", "outcome_frame": "answer a lien records request in an afternoon instead of a quarter", "proof_promise": "The 3-year register is the records-request answer — read-only, hash-stamped, and reproducible on the day the letter arrives." }, "indexable": true }, "evidence": [ { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-e1", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "area": "Identity", "claim_or_finding": "Operating entity declared: Your Deputy, Obuke LLC, 924 W 23rd St., Erie, PA 16502 (support@yourdeputy.com); SlipLienClear is its service brand.", "status": "verified", "evidence": "Owner-supplied entity, registered address, and support email; reflected in the landing-page footer, disclaimers, and Organization structured data.", "verification_command": "Owner submits entity + jurisdiction pack.", "fix_owner": "owner", "remediation": "Resolved — entity, address, and contact declared. Remaining owner action: confirm any Florida foreign-qualification obligations with counsel before scaling.", "severity": "info" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-e2", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "area": "Trust boundary", "claim_or_finding": "Public page is a validation microsite for a documentation-support service; not a law firm, not a repair contractor, and not an FLHSMV representative.", "status": "verified", "evidence": "Microsite carries explicit trust-boundary and documentation-support-only disclaimer block.", "verification_command": "Inspect /microsites/fl-marina-possessory-lien-notice-completeness-pack-engine for trust boundary.", "fix_owner": "engineering", "remediation": "None — enforced by template.", "severity": "low" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-e3", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "area": "SEO integrity", "claim_or_finding": "No fabricated review, rating, or aggregateRating schema; no penalty figures without an actual-penalties-vary caveat. A Service/Organization node is emitted and is permitted because it reflects the real operating entity (Your Deputy, Obuke LLC).", "status": "verified", "evidence": "FAQPage + Service (with a real-entity Organization provider) schema generated; no review/rating/aggregateRating; marketing-compliance gate applied.", "verification_command": "View SEO Factory row for fl-marina-possessory-lien-notice-completeness-pack-engine", "fix_owner": "engineering", "remediation": "None — enforced by SEO factory.", "severity": "low" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-e4", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "area": "Regulated claims", "claim_or_finding": "Elevated trust burden — §328.17-adjacent claims gated on owner facts: named Florida-licensed maritime attorney reviewer engagement letter, entity identity, and counsel review of engagement terms and disclaimers.", "status": "release-blocker", "evidence": "Trust burden = Medium-high", "verification_command": "Complete Prompt B owner facts.", "fix_owner": "owner", "remediation": "Provide reviewer engagement letter (role-title until then), professional review, and disclosure facts.", "severity": "high" }, { "id": "fl-marina-possessory-lien-notice-completeness-pack-engine-e5", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "area": "Manifest coverage", "claim_or_finding": "Manifest-backed blueprint present in source repository (2026-07-12 build, incl. May 2026 TRU-exclusion fresh-research update).", "status": "assumed", "evidence": "manifest.json entry", "verification_command": "Cross-check manifest entry for fl-marina-possessory-lien-notice-completeness-pack-engine in the builds repository.", "fix_owner": "engineering", "remediation": "Attach the manifest run to the evidence register.", "severity": "medium" } ], "seo_pages": { "id": "seo-fl-marina-possessory-lien-notice-completeness-pack-engine", "business_slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "route": "/microsites/fl-marina-possessory-lien-notice-completeness-pack-engine", "title": "SlipLienClear — Florida marina §328.17 lien-notice packs", "description": "SlipLienClear for office managers at independent Florida marinas. Release-ready Fla. Stat. §328.17 Notice Completeness Packs from a delinquent vessel's ledger — flat fee, five business days.", "canonical": "/microsites/fl-marina-possessory-lien-notice-completeness-pack-engine", "og_title": "SlipLienClear — Florida Marina Possessory Lien Notice Completeness Pack Engine", "og_description": "SlipLienClear for office managers at independent Florida marinas. Release-ready Fla. Stat. §328.17 Notice Completeness Packs from a delinquent vessel's ledger — flat fee, five business days.", "schema_type": "FAQPage", "schema_status": "pending-owner-facts", "sitemap_include": false, "noindex": true }, "vertical_style": { "accent": "harbor-navy", "signature": "Notice-pack tabs with a lienholder-matrix chip", "layout": "Pack binder index", "anti": "Nautical clip-art, ship wheels, and alarm-red penalty banners" }, "canva": { "slug": "fl-marina-possessory-lien-notice-completeness-pack-engine", "territory": "Pack Binder", "family": { "id": "legal-ops", "name": "Legal-ops / maritime", "motion": "calm" }, "tokens": { "brand": "203 71% 19%", "brand-fg": "205 44% 97%", "surface": "210 20% 97%", "ink": "200 41% 12%", "muted": "200 16% 34%", "accent": "36 100% 30%" }, "type": { "display": "Libre Caslon Text", "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.02em", "tracking_body": "-0.005em", "weight_display": 700, "weight_body": 450 }, "spacing": { "card_padding": "1.75rem", "card_radius": "0.25rem", "card_shadow": "0 0 0 1px hsl(var(--ink) / 0.08)", "section_gap": "clamp(3.5rem, 8vw, 6.5rem)", "hero_gap": "clamp(1.25rem, 2vw, 2rem)" }, "layout": { "hero": "split-primary", "card": "elevated-soft", "cta": "solid-brand", "archetype": "magazine", "card_silhouette": "flat-outline", "button_geometry": "sharp" }, "background": { "hero_gradient": "radial-gradient(1200px 600px at 10% -10%, hsl(17 61% 33% / 0.18), transparent 60%), radial-gradient(900px 500px at 90% 10%, hsl(226 49% 19% / 0.12), transparent 55%)", "cta_gradient": "linear-gradient(135deg, hsl(226 49% 19%), hsl(17 61% 33%))", "section_wash": "linear-gradient(180deg, hsl(40 25% 97%) 0%, hsl(226 49% 19% / 0.04) 100%)" }, "motif": "Notice pack cover + lienholder matrix row" }, "capabilities": { "marketing": true, "portal": true, "ops": true, "chatbot": true, "payments": false }, "generated_at": "2026-07-13T02:19:40Z", "checksum": "sha256:ede359bd96474da5" }