Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/08 - Adapter Detailed Implementation Spec_ CRM Import and Client 360.md

CRM Import and Client 360 Adapter Detailed Implementation Spec

Date: 2026-04-18
Status: Draft
Owner: Sagnik
Reviewers: Sayan, Sourik
Scope: CRM import ingestion, canonical normalization, client-360 aggregation, and Oracle-adjacent review flow
Purpose: Define the exact adapter behavior, request and response contracts, file placements, runtime flow, and acceptance criteria for the founder-owned CRM import and client dossier layer.
Decision Boundary: This is the target adapter contract for future implementation. It does not itself add routes or services.

1. Purpose

This adapter exists to translate heterogenous source data and ongoing interactions into one canonical client graph and one usable Client 360 output for the product.

2. Adapter Strategy

Why this adapter exists:

• imported CRM data is inconsistent
• Velocity wants AI assistance without losing operator control
• Oracle and CRM need a shared truth source

What the adapter must not own:

• GPU generation or Comfy execution
• low-level Oracle canvas rendering
• inventory business logic beyond client-interest linkage

3. Mission Type

Supported mission families in the planning target:

• import batch analysis
• mapping proposal generation
• identity resolution proposal
• client 360 aggregation
• Oracle review/writeback preparation

4. Entry Points

Planned route and UI entry points:

• /api/crm/imports
• /api/crm/imports/{import_id}
• /api/crm/client-360/{client_id}
• future CRM Import Review page
• future Oracle CRM Intelligence subtab

5. Context Inputs

Required inputs:

• raw import file or stored batch reference
• source profile
• mapping manifest
• current canonical entities
• existing interaction and opportunity history
• policy and confidence thresholds

6. File Placement

Planned future files:

• backend/services/imports/ingest_service.py
• backend/services/imports/mapping_service.py
• backend/services/client_graph/aggregation_service.py
• backend/services/client_graph/identity_resolution_service.py
• backend/api/routes_crm_imports.py
• app/src/components/crm/imports/*
• app/src/components/crm/client360/*

7. Mission Creation Flow

1. operator uploads a CSV or selects a source-system import
2. raw file is stored and indexed
3. headers and rows are parsed
4. source profile is selected or inferred
5. mapping manifest is created
6. NemoClaw-assisted normalization proposes canonical records
7. identity resolution proposes create/merge/update decisions
8. operator reviews unresolved or high-risk changes
9. approved deltas write into canonical domains
10. client 360 read model refreshes

8. Output Contract

Final adapter outputs:

• import summary payload
• unresolved fields list
• proposed canonical deltas
• review-required decisions
• refreshed Client360Snapshot

9. Writeback Rules

• low-risk structured inserts may be auto-approved only if policy later allows it
• identity merges, account merges, and major data overwrites require explicit approval
• Oracle writebacks into CRM must follow the same approval model

10. Acceptance Criteria

• raw evidence, mapping, and canonical projections are all explicitly modeled
• unresolved cases degrade to review, not silent failure
• Client 360 output is clearly defined
• adapter inputs and outputs are consistent with the contracts/schema blueprint and DB spec

11. Tests

Future implementation should require:

• import replay tests
• bad-header and unmapped-column tests
• conflicting-identity tests
• client-360 aggregation tests
• Oracle writeback approval tests

12. Demo and Sales Relevance

This adapter matters because it makes the product believable for a real sales team:

• it explains how old CRM exports become Velocity-native
• it explains how communications and intelligence become part of the same client record
• it answers the customer objection that migration into Velocity would be messy

13. Bottom Line

The CRM import and Client 360 adapter is the operational bridge between raw outside data and the intelligent sales system Velocity is trying to become.