# CIP Credit Scoring — Full Context (from Ben's handoff, 2026-02-10)

## Repo / Workflow
- **Repo:** `symphco/customerpro-insights-5d726d` (private)
- **Trunk branch:** `development`
- **Stack:** Next.js 15, Tailwind v4, Radix UI, Lucide, React Hook Form, Zod
- **Rules:** PRs first (no auto-merge), verify builds compile before claiming done

## What CIP Is
Generic AI-powered CDP:
- Companies firehose data in, CIP provides stable identity/entity ID
- Supports: customer insights, product recommendations, credit scoring
- Credit scoring WAS an n8n LLM-based workflow (A→F grade) — risky for money decisions
- Goal: rules-based credit grading, generic, not hardcoded to one client

## What Was Built & Merged

### Phase 1: Config UI + Engine
- Admin UI at `/admin/credit-scoring`
- Endpoints: GET/PUT `/api/v1/credit-score/config`, POST `/api/v1/credit-score/config/test/:customerId`
- Config stored in `system_configuration` (keyed `credit_scoring:default`)
- Had GCP build failures (DTO typing issues) — fixed and merged

### Phase 2: Event-Sourced Scoring + Schema Autocomplete
- Factors now derived from `events` table (not legacy fields)
- Factor dataSource = aggregation query on events (count/sum/avg/min/max/distinct)
- Filter by eventType(s), JSON path into payload, optional timeWindowDays
- Schema sampler endpoint scans ~1000 events for autocomplete
- Multi-tenancy scoping parked for later

### Phase 3: Legacy Factor Support Fully Removed
- Only event-based factors remain
- No legacy/event toggle in UI
- Default ruleset = V3 event-based
- Merged to `development`

## The Core Problem Discovered After Refactor

**The insights layer is disconnected from actual flows:**

| Flow | Writes To | Reads From |
|------|-----------|------------|
| Send Money UI | `activities` (legacy) | `customers` (legacy) |
| n8n workflows | — | `customers` + `activities` (legacy) |
| New scoring engine | — | `entities` + `events` (insights) |

- Send Money does NOT write to `events` — uses `apiClient.createActivity()` → legacy `activities`
- n8n hits legacy CRM endpoints (`/customers/profile/`, `/activities/customer/`)
- `entities` table only had 2 records vs many in `customers`

## DB Table Grouping

**Insights layer (intended core):**
- `entities` — generic entity/person/business, metadata JSONB
- `events` — schemaless timeseries, eventType, occurredAt, payload JSON
- `knowledge`, `documents`, `aiChunks` — AI/embedding infra

**Legacy CRM layer (crufty/misaligned):**
- `customers`, `transactions`, `activities` — deprecated-ish
- `companies`, `businessUnits`, `apiTokens`, `products` — multi-tenant-ish, not focus

## Where Ben Left Off

Ben's thinking: maybe work with current reality — `activities` already has a `payload` column (event-like enough). But the system is janky — half the schemas aren't used and anyone entering CIP needs to know what's canonical vs dead.

## Open Decisions / Next Steps

1. **Source of truth for event-like history:**
   - Option A: Commit to `events`, rewire Send Money + n8n
   - Option B: Use `activities.payload` as interim event stream
   - Option C: Bridge/sync activities → events

2. **Schema audit:** List tables actively used vs keep vs deprecate. Ben will label what's "to-be-used" vs "sunset"

3. **Confirm endpoint naming:** Schema sampler was `/events/schema` or `/event-schema` — verify in code

4. **Build must compile** before push/merge

#cip #ben #credit-scoring
