# 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.