YP3000 Identity System

Status: Active Development
Version: 1.0
Last Updated: 2026-01-06

---

1. Overview

YP3000 is RABS' self-generating, confidence-based contact resolution system. Unlike traditional contact management where records are manually maintained, YP3000 discovers identities through observation across all connected systems.

Philosophy

"We don't maintain contacts - we DISCOVER them through observation. Every sighting builds evidence. Confidence grows or decays over time. The system learns who people really are, not just what records say."

Key Principles

• Per-Detail Confidence: Each contact detail (phone, email, relationship) has its own confidence score
• Source Attribution: Every piece of information tracked back to its discovery source
• Decay & Reinforcement: Confidence decays over time unless reinforced by new sightings
• Anchor Identities: Strong relationships (staff member, participant's mother) lock identities in place
• Purgatory System: Unknown/unanchored identities held for review before promotion or archival

---

2. Data Architecture

Core Tables (in core_source schema)

Table	Purpose
yp3000_identities	Central identity index - people/entities discovered
yp3000_contact_details	Phones, emails, addresses with individual confidence
yp3000_sources	Evidence log - where/when each detail was discovered
yp3000_relationships	Links to participants, staff, venues, etc.
yp3000_sightings	Raw sighting queue for processing
yp3000_confidence_weights	Configurable confidence values per source type
yp3000_activity_log	Audit trail of identity changes

Confidence Model

Each contact detail carries:

• confidence (0-100): How sure are we this is correct?
• first_seen_at / last_seen_at: Discovery timeline
• sighting_count: How many times confirmed
• source_count: How many distinct sources

Example Display:

Susan Miller (Identity)
├── Role: Carer (80% confidence)
├── Relationship: Michael's mother (85% confidence)
├── Phone: +61412345678 (60% confidence - seen in SMS only)
├── Email: susan.m@gmail.com (100% confidence - verified)
└── Sources: Participant file, SMS thread, Emergency contacts

---

3. Source Scanners

YP3000 discovers identities by scanning connected systems:

Scanner	Source	Confidence Base
Staff Scanner	core_source.staff	90
Participant Scanner	core_source.participants	85
Carer Scanner	Participant emergency contacts	70
Directory Scanner	core_ops.org_directory	85
Email Scanner	Incoming email headers/signatures	40
SMS Scanner	Twilio/TextMagic messages	50
Dialpad Scanner	Call logs	45

Scanner Deduplication Logic

Before creating a new identity, scanners check:

1. Exact staff_id / participant_id match
2. Email match (case-insensitive)
3. Exact first + last name match
4. Phone number match (E.164 normalized)

---

4. UI Views

Cards View (Default)

Grid of identity cards showing:

• Name and primary role
• Confidence indicators
• Primary phone/email
• Source badges
• Quick actions (verify, merge, archive)

Solar System View (LCARS-styled)

Orbital visualization representing organizational hierarchy:

Orbit	Contains	Visual
Core	Organization center	Invisible/subtle glow
Orbit 1	Executives (Brett, Sean, Ami, Richelle)	Inner ring
Orbit 2	Management (Ash, Jen, Yanni, Bridey)	Second ring
Orbit 3	Admin team	Third ring
Orbit 4	Support workers	Outer ring
Orbit 5	Participants	External ring
Purgatory	Unanchored identities	Scattered outer zone

Identity Detail Modal

Full breakdown showing:

• All contact details with individual confidence bars
• Source attribution per detail
• Relationship map
• Activity timeline
• Merge/verify/archive actions

---

5. Do-Not-Track System

Some contacts should be excluded from discovery (personal contacts, spam, etc.):

Location: App Settings → YP3000 → Do Not Track

Exclusion Types:

• Email addresses (exact or domain)
• Phone numbers
• Name patterns

Behavior:

• Excluded contacts are never created as identities
• Existing identities can be marked "do not track" to prevent further scanning
• Does not delete existing data, only prevents future discovery

---

6. Integration Points

As a Data Source

Other RABS features consume YP3000 for contact resolution:

Feature	Usage
Reggie SMS	Resolve sender identity from phone
TextMagic	Display contact names, discover new contacts
Dialpad	Caller ID resolution
Email System	Sender identification
Broadcast System	Group targeting (all staff, all carers, etc.)

As a Discovery Target

These systems feed sightings into YP3000:

• Staff records → Staff scanner
• Participant files → Participant scanner + Carer scanner
• Org directory → Directory scanner
• SMS threads → SMS scanner
• Email messages → Email scanner
• Call logs → Dialpad scanner

---

7. API Endpoints

GET  /api/v1/yp3000/identities          - List identities with filters
GET  /api/v1/yp3000/identities/:id      - Full identity detail
POST /api/v1/yp3000/identities/:id/verify - Mark as human-verified
POST /api/v1/yp3000/identities/:id/merge  - Merge with another identity
POST /api/v1/yp3000/resolve             - Resolve phone/email to identity

GET  /api/v1/yp3000/stats               - System statistics
POST /api/v1/yp3000/scan/:source        - Run specific scanner
POST /api/v1/yp3000/analyze-duplicates  - LLM-powered duplicate analysis

---

8. Files Reference

File	Purpose
backend/routes_v1p/yp3000.js	API routes and scanner logic
admin/src/js/pages/page_yp3000.js	Frontend JavaScript
admin/src/html/page_yp3000.html	Page template with LCARS styling
admin/tasks/sql/sql-current/20260104_yp3000_identity_layer.sql	Schema migration

---

9. Roadmap

Phase 1: Foundation (Current)

• Core schema and tables
• Basic scanners (staff, participants, carers, directory)
• Cards view with search/filter
• Duplicate detection + LLM analysis
• Solar system view
• Identity detail modal with confidence breakdown
• Do-not-track configuration

Phase 2: Source Integrations

• TextMagic as source
• Email scanning
• Dialpad call log scanning

Phase 3: Consumption

• Reggie SMS identity resolution
• TextMagic contact display
• Broadcast system (group messaging)

Phase 4: Voice/Video

• Dialpad caller ID
• LiveKit room identity context