Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/specs/banking/identity-compliance.md
+++ b/docs/specs/banking/identity-compliance.md
@@ -0,0 +1,197 @@
+# Identity & Compliance Specification
+
+## Overview
+
+This document specifies the identity verification (KYC/KYB) and compliance orchestration system for banking features.
+
+## KYC/KYB Workflow Orchestration
+
+### Workflow Stages
+
+**1. Initial Registration**:
+- User registration
+- Basic information collection
+- Terms acceptance
+
+**2. Identity Verification**:
+- Document upload (ID, proof of address)
+- Biometric verification (if required)
+- Liveness check
+
+**3. Risk Assessment**:
+- Sanctions screening
+- PEP screening
+- Risk scoring
+
+**4. Approval/Rejection**:
+- Automated approval (low risk)
+- Manual review (medium/high risk)
+- Rejection with reasons
+
+### Workflow State Machine
+
+```
+[Registered] → [Identity Verification] → [Risk Assessment] → [Approved/Rejected]
+                                              ↓
+                                         [Manual Review]
+```
+
+## Sanctions/PEP Screening Integration
+
+### Screening Providers
+
+**Options**:
+- WorldCheck
+- Dow Jones Risk & Compliance
+- Chainalysis
+- Others
+
+### Screening Process
+
+**1. Data Collection**:
+- Name, date of birth, nationality
+- Address information
+- Associated addresses (blockchain addresses)
+
+**2. Screening Check**:
+- Sanctions lists (OFAC, UN, EU, etc.)
+- PEP lists (politically exposed persons)
+- Adverse media screening
+
+**3. Match Resolution**:
+- Automated false positive filtering
+- Manual review for potential matches
+- Risk scoring based on match confidence
+
+### Screening Result
+
+```json
+{
+  "user_id": "uuid",
+  "screening_status": "cleared",
+  "matches": [],
+  "risk_score": 0.1,
+  "screened_at": "2024-01-01T00:00:00Z",
+  "next_screening": "2025-01-01T00:00:00Z"
+}
+```
+
+## Risk Tier Assignment
+
+### Risk Tiers
+
+**Tier 1 - Low Risk**:
+- Verified identity
+- No sanctions/PEP matches
+- Low transaction volume
+- Limits: Standard limits
+
+**Tier 2 - Medium Risk**:
+- Verified identity
+- Minor concerns (e.g., high-risk country)
+- Medium transaction volume
+- Limits: Reduced limits, additional monitoring
+
+**Tier 3 - High Risk**:
+- Unverified or incomplete verification
+- Sanctions/PEP matches
+- High transaction volume
+- Limits: Very restricted or blocked
+
+### Risk Scoring
+
+**Factors**:
+- Identity verification status
+- Sanctions/PEP screening results
+- Transaction patterns
+- Geographic risk
+- Source of funds
+
+**Score Range**: 0.0 (low risk) to 1.0 (high risk)
+
+## Limit Management
+
+### Limit Types
+
+**Transaction Limits**:
+- Daily transaction limit
+- Monthly transaction limit
+- Single transaction limit
+
+**Account Limits**:
+- Maximum balance
+- Withdrawal limits
+
+### Limit Enforcement
+
+**Real-time Checks**:
+- Check limits before transaction
+- Reject if limit exceeded
+- Provide limit status to user
+
+**Dynamic Limits**:
+- Adjust limits based on risk tier
+- Increase limits with step-up verification
+- Temporary limit increases (pending approval)
+
+## Step-Up Verification
+
+### Trigger Conditions
+
+**Triggers**:
+- Transaction exceeds current tier limits
+- Suspicious activity detected
+- User request
+- Regulatory requirement
+
+### Verification Levels
+
+**Level 1**: Basic KYC (standard)
+**Level 2**: Enhanced due diligence (EDD)
+**Level 3**: Institutional/KYB verification
+
+### Step-Up Process
+
+1. Notify user of requirement
+2. Collect additional documentation
+3. Enhanced screening
+4. Review and approval
+5. Update risk tier and limits
+
+## Integration Points
+
+### Identity Provider Integration
+
+**Providers**:
+- Jumio
+- Onfido
+- Sumsub
+- Others
+
+**Integration Pattern**:
+- API integration
+- Webhook callbacks for status updates
+- Document storage
+
+### Compliance System Integration
+
+**Systems**:
+- Transaction monitoring
+- Reporting systems
+- Audit systems
+
+## Data Privacy
+
+### PII Handling
+
+**Storage**: Encrypted storage
+**Access**: Role-based access control
+**Retention**: Per regulatory requirements
+**Deletion**: Right to deletion support
+
+## References
+
+- Account & Ledger: See `account-ledger.md`
+- Compliance Dashboards: See `compliance-dashboards.md`
+- Security: See `../security/privacy-controls.md`
+