Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/07 - Contracts and Schema Blueprint_ Founder CRM and Platform Planning.md

Contracts and Schema Blueprint_ Founder CRM and Platform Planning

Date: 2026-04-18
Status: Draft
Owner: Sagnik
Reviewers: Sayan, Sourik
Scope: Canonical artifact contracts for client graph, imports, interactions, writebacks, and approvals
Purpose: Define the internal artifact contracts, schema boundaries, versioning rules, and validation strategy for the founder-side CRM and platform model.
Decision Boundary: This document defines target contracts. It does not itself create runtime validators or database migrations.

1. Purpose

This contract system exists to stop Project Velocity from passing loosely structured lead and interaction data between subsystems with no canonical artifact shape.

2. Contract Design Principles

• preserve raw evidence and normalized projections separately
• make producer and consumer ownership explicit
• version artifacts from the start
• keep provenance and confidence attached to inferred data
• require approval-aware contracts for destructive or merging operations

3. Canonical Artifact Set

• RawImportBatch
• ImportRowRecord
• ImportMappingManifest
• NormalizedEntityProposal
• ClientGraphDelta
• InteractionBundle
• TranscriptBundle
• QdSignalBundle
• OracleWritebackProposal
• ApprovalDecision
• Client360Snapshot

4. Schema Rules

Required metadata for every artifact:

• artifact_id
• artifact_type
• schema_version
• source_system
• created_at
• created_by
• confidence
• provenance

Versioning model:

• semantic schema version per artifact family
• additive evolution preferred
• breaking changes require a new version and explicit reader mapping

5. Artifact Definitions

RawImportBatch

• purpose: preserve the uploaded import exactly as received
• required fields:
  • batch_id
  • source_system
  • uploaded_filename
  • mime_type
  • storage_ref
  • row_count
  • uploaded_by
• validation rules:
  • immutable after upload

ImportMappingManifest

• purpose: define how source columns map to canonical fields
• required fields:
  • manifest_id
  • batch_id
  • source_profile
  • column_mappings
  • unmapped_columns
  • resolver_notes
• validation rules:
  • every imported column is either mapped, ignored, or unresolved

NormalizedEntityProposal

• purpose: represent AI-assisted structured projections before approval
• required fields:
  • proposal_id
  • batch_id
  • entity_type
  • canonical_payload
  • confidence
  • merge_candidate_refs
  • review_required
• validation rules:
  • cannot become committed data without an approval or low-risk auto rule

InteractionBundle

• purpose: capture messages, calls, visits, and related communication artifacts for one interaction thread or event cluster
• required fields:
  • bundle_id
  • client_ref
  • channel
  • event_refs
  • attachments
  • summary
• validation rules:
  • must preserve raw event refs even when summarized

TranscriptBundle

• purpose: group transcripts, speaker segmentation, timing metadata, and related media refs
• required fields:
  • transcript_id
  • interaction_ref
  • media_ref
  • speaker_segments
  • language
  • text
• validation rules:
  • speaker segmentation and timing metadata are first-class, not comments

QdSignalBundle

• purpose: package QD-relevant signals and time-series projections
• required fields:
  • signal_id
  • client_ref
  • source_ref
  • score_type
  • value
  • time_window
  • supporting_evidence_refs
• validation rules:
  • every score must point back to evidence refs or explicit operator input

OracleWritebackProposal

• purpose: capture an AI-suggested change from Oracle or NemoClaw before commit
• required fields:
  • proposal_id
  • target_domain
  • target_entity_ref
  • proposed_change
  • reasoning_summary
  • evidence_refs
  • approval_required
• validation rules:
  • writeback proposals never masquerade as committed state

ApprovalDecision

• purpose: represent explicit human review outcome
• required fields:
  • decision_id
  • proposal_ref
  • reviewer_ref
  • decision
  • decision_notes
  • decided_at
• validation rules:
  • immutable audit record

Client360Snapshot

• purpose: provide a stable read model for UI and Oracle
• required fields:
  • client_ref
  • identity
  • account_links
  • active_opportunities
  • recent_interactions
  • property_interests
  • tasks
  • qd_overview
  • risk_flags
• validation rules:
  • derived snapshot; never the sole source of truth

6. Storage Mapping

• raw batches and raw rows map to raw import storage plus structured index tables
• normalized proposals map to workflow/governance tables
• client graph deltas map to canonical domains
• interaction and transcript bundles map to intel_*
• snapshots map to materialized read models or service aggregation outputs

7. Validation Strategy

Service layer:

• validate schema presence and required metadata

Root layer:

• validate auth, ownership, and approval gates

Persistence layer:

• validate referential integrity and lifecycle rules

8. Compatibility Strategy

• additive extensions preferred
• preserve readers for older import manifests during transition
• all schema migrations should be tied to explicit artifact version upgrades

9. Implementation Order

1. raw import and mapping artifacts
2. normalized proposals
3. writeback and approval artifacts
4. interaction and transcript bundles
5. client 360 snapshot contracts

10. Bottom Line

Without stable artifact contracts, the future CRM/client-graph implementation will drift again. These contracts are the minimum spine required to keep AI, UI, and persistence working against the same truth.