Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
167
docs/specs/banking/account-ledger.md
Normal file
167
docs/specs/banking/account-ledger.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Account & Ledger Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This document specifies the customer ledger system using double-entry bookkeeping principles for banking operations.
|
||||
|
||||
## Double-Entry Ledger Schema
|
||||
|
||||
### Ledger Entry
|
||||
|
||||
```sql
|
||||
CREATE TABLE ledger_entries (
|
||||
id UUID PRIMARY KEY,
|
||||
customer_id UUID NOT NULL,
|
||||
transaction_id UUID NOT NULL,
|
||||
entry_type VARCHAR(20) NOT NULL, -- 'debit', 'credit'
|
||||
account_type VARCHAR(50) NOT NULL, -- 'cash', 'crypto', 'fiat', etc.
|
||||
amount NUMERIC(78, 0) NOT NULL,
|
||||
currency VARCHAR(10) NOT NULL,
|
||||
description TEXT,
|
||||
reference_id VARCHAR(255), -- External transaction reference
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
FOREIGN KEY (customer_id) REFERENCES customers(id),
|
||||
FOREIGN KEY (transaction_id) REFERENCES transactions(id)
|
||||
);
|
||||
```
|
||||
|
||||
### Transaction Table
|
||||
|
||||
```sql
|
||||
CREATE TABLE transactions (
|
||||
id UUID PRIMARY KEY,
|
||||
customer_id UUID NOT NULL,
|
||||
transaction_type VARCHAR(50) NOT NULL, -- 'deposit', 'withdrawal', 'transfer', etc.
|
||||
status VARCHAR(20) NOT NULL, -- 'pending', 'completed', 'failed'
|
||||
amount NUMERIC(78, 0) NOT NULL,
|
||||
currency VARCHAR(10) NOT NULL,
|
||||
from_account UUID,
|
||||
to_account UUID,
|
||||
blockchain_tx_hash VARCHAR(66), -- If blockchain transaction
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
completed_at TIMESTAMP,
|
||||
FOREIGN KEY (customer_id) REFERENCES customers(id)
|
||||
);
|
||||
```
|
||||
|
||||
### Double-Entry Rule
|
||||
|
||||
**Constraint**: Sum of debits = Sum of credits for each transaction
|
||||
|
||||
**Implementation**: Two entries per transaction (debit and credit)
|
||||
|
||||
## Wallet Mapping
|
||||
|
||||
### Customer-Wallet Mapping
|
||||
|
||||
```sql
|
||||
CREATE TABLE customer_wallets (
|
||||
id UUID PRIMARY KEY,
|
||||
customer_id UUID NOT NULL,
|
||||
chain_id INTEGER NOT NULL,
|
||||
address VARCHAR(42) NOT NULL,
|
||||
wallet_type VARCHAR(20) NOT NULL, -- 'external', 'custodial'
|
||||
verified BOOLEAN DEFAULT false,
|
||||
verified_at TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
UNIQUE (customer_id, chain_id, address),
|
||||
FOREIGN KEY (customer_id) REFERENCES customers(id)
|
||||
);
|
||||
```
|
||||
|
||||
### Wallet Verification
|
||||
|
||||
**Process**:
|
||||
1. Customer provides address
|
||||
2. Request signature verification
|
||||
3. Verify signature matches address
|
||||
4. Link address to customer account
|
||||
5. Mark as verified
|
||||
|
||||
## Reconciliation Jobs
|
||||
|
||||
### Reconciliation Process
|
||||
|
||||
**Purpose**: Ensure ledger matches actual blockchain/custodial balances
|
||||
|
||||
**Frequency**: Daily or real-time (depending on account type)
|
||||
|
||||
**Steps**:
|
||||
1. Query actual balances (blockchain or custodial wallet)
|
||||
2. Calculate expected balance from ledger
|
||||
3. Compare and identify discrepancies
|
||||
4. Create reconciliation entries if needed
|
||||
5. Alert on discrepancies
|
||||
|
||||
### Reconciliation Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE reconciliations (
|
||||
id UUID PRIMARY KEY,
|
||||
customer_id UUID NOT NULL,
|
||||
account_type VARCHAR(50) NOT NULL,
|
||||
currency VARCHAR(10) NOT NULL,
|
||||
expected_balance NUMERIC(78, 0) NOT NULL,
|
||||
actual_balance NUMERIC(78, 0) NOT NULL,
|
||||
discrepancy NUMERIC(78, 0) NOT NULL,
|
||||
status VARCHAR(20) NOT NULL, -- 'matched', 'discrepancy', 'resolved'
|
||||
reconciled_at TIMESTAMP DEFAULT NOW(),
|
||||
resolved_at TIMESTAMP,
|
||||
FOREIGN KEY (customer_id) REFERENCES customers(id)
|
||||
);
|
||||
```
|
||||
|
||||
## Audit Trails
|
||||
|
||||
### Audit Log Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE audit_logs (
|
||||
id UUID PRIMARY KEY,
|
||||
customer_id UUID,
|
||||
action VARCHAR(100) NOT NULL,
|
||||
resource_type VARCHAR(50) NOT NULL,
|
||||
resource_id VARCHAR(255),
|
||||
old_value JSONB,
|
||||
new_value JSONB,
|
||||
actor_id UUID NOT NULL, -- User/system that performed action
|
||||
ip_address VARCHAR(45),
|
||||
user_agent TEXT,
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### Immutable Log Storage
|
||||
|
||||
**Storage**: Append-only log (immutable)
|
||||
**Retention**: Per regulatory requirements (typically 7 years)
|
||||
**Access**: Audit team only
|
||||
**Integrity**: Cryptographic hashing for tamper detection
|
||||
|
||||
## Balance Calculations
|
||||
|
||||
### Account Balance
|
||||
|
||||
**Formula**: Sum of credits - Sum of debits for account
|
||||
|
||||
**Implementation**:
|
||||
```sql
|
||||
SELECT
|
||||
SUM(CASE WHEN entry_type = 'credit' THEN amount ELSE 0 END) -
|
||||
SUM(CASE WHEN entry_type = 'debit' THEN amount ELSE 0 END) AS balance
|
||||
FROM ledger_entries
|
||||
WHERE customer_id = ? AND account_type = ? AND currency = ?;
|
||||
```
|
||||
|
||||
### Real-Time Balance
|
||||
|
||||
**Caching**: Cache balances with TTL
|
||||
**Updates**: Invalidate on new ledger entries
|
||||
**Accuracy**: Reconcile with actual balances periodically
|
||||
|
||||
## References
|
||||
|
||||
- Identity & Compliance: See `identity-compliance.md`
|
||||
- Payment Rails: See `payment-rails.md`
|
||||
- Database Schema: See `../database/postgres-schema.md`
|
||||
|
||||
87
docs/specs/banking/compliance-dashboards.md
Normal file
87
docs/specs/banking/compliance-dashboards.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Compliance Dashboards Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Compliance dashboards for case management, SAR/STR workflows, and reporting.
|
||||
|
||||
## Case Management
|
||||
|
||||
### Case Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE compliance_cases (
|
||||
id UUID PRIMARY KEY,
|
||||
case_type VARCHAR(50) NOT NULL, -- 'suspicious_activity', 'sanctions_match', etc.
|
||||
customer_id UUID,
|
||||
severity VARCHAR(20) NOT NULL, -- 'low', 'medium', 'high', 'critical'
|
||||
status VARCHAR(20) NOT NULL, -- 'open', 'under_review', 'resolved', 'escalated'
|
||||
assigned_to UUID, -- Compliance officer
|
||||
description TEXT,
|
||||
evidence JSONB,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW(),
|
||||
resolved_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### Case Workflow
|
||||
|
||||
1. Case created (automated or manual)
|
||||
2. Assigned to compliance officer
|
||||
3. Investigation
|
||||
4. Resolution or escalation
|
||||
5. Documentation and closure
|
||||
|
||||
## SAR/STR Workflows
|
||||
|
||||
### Suspicious Activity Reports (SAR)
|
||||
|
||||
**Trigger Conditions**:
|
||||
- Unusual transaction patterns
|
||||
- High-value transactions
|
||||
- Sanctions/PEP matches
|
||||
- Manual flagging
|
||||
|
||||
**Workflow**:
|
||||
1. Detect suspicious activity
|
||||
2. Create case
|
||||
3. Investigate
|
||||
4. File SAR if confirmed
|
||||
5. Monitor for follow-up
|
||||
|
||||
### Suspicious Transaction Reports (STR)
|
||||
|
||||
Similar to SAR, jurisdiction-specific
|
||||
|
||||
## Evidence Export
|
||||
|
||||
### Export Format
|
||||
|
||||
**Package Contents**:
|
||||
- Case details
|
||||
- Transaction history
|
||||
- Customer information
|
||||
- Screening results
|
||||
- Investigation notes
|
||||
- Supporting documents
|
||||
|
||||
**Format**: PDF report + supporting data files
|
||||
|
||||
## Reporting APIs
|
||||
|
||||
### Case Management API
|
||||
|
||||
`GET /api/v1/compliance/cases`
|
||||
`POST /api/v1/compliance/cases`
|
||||
`GET /api/v1/compliance/cases/{id}`
|
||||
`PUT /api/v1/compliance/cases/{id}`
|
||||
|
||||
### Reporting API
|
||||
|
||||
`GET /api/v1/compliance/reports`
|
||||
`POST /api/v1/compliance/reports/generate`
|
||||
|
||||
## References
|
||||
|
||||
- Identity & Compliance: See `identity-compliance.md`
|
||||
|
||||
197
docs/specs/banking/identity-compliance.md
Normal file
197
docs/specs/banking/identity-compliance.md
Normal file
@@ -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`
|
||||
|
||||
95
docs/specs/banking/payment-rails.md
Normal file
95
docs/specs/banking/payment-rails.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Payment Rails Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Payment rails for on-ramp/off-ramp, ACH, wire, and card processing integration.
|
||||
|
||||
## On-Ramp Integration
|
||||
|
||||
### Providers
|
||||
|
||||
**Crypto On-Ramp**:
|
||||
- MoonPay
|
||||
- Ramp
|
||||
- Transak
|
||||
- Others
|
||||
|
||||
### Integration Pattern
|
||||
|
||||
**Flow**:
|
||||
1. User initiates on-ramp
|
||||
2. Redirect to provider or embed widget
|
||||
3. User completes purchase
|
||||
4. Provider webhook notifies completion
|
||||
5. Credit customer account
|
||||
|
||||
## Off-Ramp Integration
|
||||
|
||||
### Providers
|
||||
|
||||
Similar to on-ramp providers
|
||||
|
||||
### Flow
|
||||
|
||||
1. User initiates withdrawal
|
||||
2. Verify balance and limits
|
||||
3. Initiate withdrawal with provider
|
||||
4. Provider processes withdrawal
|
||||
5. Debit customer account
|
||||
6. Monitor completion
|
||||
|
||||
## ACH/Wire/Card Rails
|
||||
|
||||
### ACH Processing
|
||||
|
||||
**Integration**: Banking partner or payment processor
|
||||
**Use Cases**: Fiat deposits/withdrawals
|
||||
**Processing Time**: 1-3 business days
|
||||
|
||||
### Wire Transfers
|
||||
|
||||
**Integration**: Banking partner
|
||||
**Use Cases**: Large fiat transfers
|
||||
**Processing Time**: Same day or next day
|
||||
|
||||
### Card Processing
|
||||
|
||||
**Integration**: Payment processor (Stripe, etc.)
|
||||
**Use Cases**: Card purchases
|
||||
**Processing Time**: Instant (authorization), 1-3 days (settlement)
|
||||
|
||||
## Settlement Monitoring
|
||||
|
||||
### Monitoring Process
|
||||
|
||||
**Track**:
|
||||
- Transaction status
|
||||
- Settlement status
|
||||
- Failed transactions
|
||||
- Disputes/chargebacks
|
||||
|
||||
### Alerts
|
||||
|
||||
**Trigger Conditions**:
|
||||
- Settlement failures
|
||||
- Unusual delays
|
||||
- Disputes
|
||||
- Chargebacks
|
||||
|
||||
## Payment Status Tracking
|
||||
|
||||
### Status States
|
||||
|
||||
- `initiated`: Payment initiated
|
||||
- `pending`: Pending processing
|
||||
- `processing`: Being processed
|
||||
- `completed`: Successfully completed
|
||||
- `failed`: Processing failed
|
||||
- `refunded`: Refunded
|
||||
- `disputed`: Under dispute
|
||||
|
||||
## References
|
||||
|
||||
- Account & Ledger: See `account-ledger.md`
|
||||
- Compliance: See `compliance-dashboards.md`
|
||||
|
||||
Reference in New Issue
Block a user