Skip to main content

Overview

This guide provides comprehensive sample data for testing Risk Legion end-to-end. All data structures align with the current implementation and can be used for API testing, demonstrations, and development.
For a complete demo scenario using Brazilian banking context, see the DEMO_DATA_INPUT_GUIDE.md in the repository.

Key Data Model Notes

Products are now defined by their attributes only: customer types, geographic operations, distribution channels, and transaction types. The category field has been removed.
Sub-Controls are created in Governance with only name and description. The ToD/ToE effectiveness ratings are assessed separately in Control Assurance. This separates control definition from control assessment.
When a BRA transitions to in_progress, the current risk appetite level is captured as snapshot_appetite_level. This ensures changes to enterprise risk appetite don’t affect assessments already in progress.

Quick Start

1. Create Test Users

Use the provided script to create test users with different roles:
cd backend

# Create a Super Admin
python scripts/create_test_user.py \
  --email superadmin@test.com \
  --password SuperAdmin123! \
  --role super_admin

# Create a Client Admin
python scripts/create_test_user.py \
  --email admin@acme.com \
  --password Admin123! \
  --role admin \
  --enterprise "ACME Corporation"

# Create an Assessor
python scripts/create_test_user.py \
  --email assessor@acme.com \
  --password Assessor123! \
  --role assessor \
  --enterprise "ACME Corporation"

# Create a Reviewer
python scripts/create_test_user.py \
  --email reviewer@acme.com \
  --password Reviewer123! \
  --role reviewer \
  --enterprise "ACME Corporation"

2. Get JWT Tokens

Retrieve JWT tokens for API testing:
# Get token for admin user
python scripts/get_token.py \
  --email admin@acme.com \
  --password Admin123!

# Copy the token and use in Postman/curl

Sample Enterprises

-- Create test enterprises
INSERT INTO enterprises (id, name, country, registration_number, status, subscription_tier, mrr_cents, active)
VALUES
  ('550e8400-e29b-41d4-a716-446655440001', 'ACME Corporation', 'US', 'REG-001', 'active', 'enterprise', 199900, true),
  ('550e8400-e29b-41d4-a716-446655440002', 'Global Tech Inc', 'UK', 'REG-002', 'active', 'professional', 99900, true),
  ('550e8400-e29b-41d4-a716-446655440003', 'Startup Labs', 'CA', 'REG-003', 'active', 'starter', 49900, true)
RETURNING id, name, status;

Sample Organization Structure

-- Create legal entities with hierarchy
INSERT INTO legal_entities (id, enterprise_id, name, legal_name, entity_type, registration_number, country_of_incorporation, parent_id, archived)
VALUES
  -- Parent entity
  ('le-001', '550e8400-e29b-41d4-a716-446655440001', 'ACME Bank Brasil S.A.', 'ACME Bank Brasil S.A.', 'Bank', '33.234.567/0001-89', 'Brazil', NULL, false),
  -- Child entities
  ('le-002', '550e8400-e29b-41d4-a716-446655440001', 'ACME Seguros Ltda.', 'ACME Seguros Ltda.', 'Insurance', '44.345.678/0001-90', 'Brazil', 'le-001', false),
  ('le-003', '550e8400-e29b-41d4-a716-446655440001', 'ACME Investimentos DTVM', 'ACME Investimentos DTVM', 'Investment Firm', '55.456.789/0001-01', 'Brazil', 'le-001', false);

Business Units

-- Create business units
INSERT INTO business_units (id, enterprise_id, legal_entity_id, name, description, archived)
VALUES
  ('bu-001', '550e8400-e29b-41d4-a716-446655440001', 'le-001', 'Retail Banking', 'Consumer banking products and services', false),
  ('bu-002', '550e8400-e29b-41d4-a716-446655440001', 'le-001', 'Corporate Banking', 'Enterprise lending and treasury services', false),
  ('bu-003', '550e8400-e29b-41d4-a716-446655440001', 'le-001', 'Digital Channels', 'Mobile and internet banking', false);

Products

Products no longer have a category field. Instead, they are defined by their attributes: customer types, geographic operations, distribution channels, and transaction types.
-- Create products (category field removed per client feedback)
INSERT INTO products (id, enterprise_id, name, description, customer_types, geographic_operations, distribution_channels, transaction_types, archived)
VALUES
  (
    'prod-001', 
    '550e8400-e29b-41d4-a716-446655440001',
    'Checking Accounts (Conta Corrente)',
    'Standard checking accounts with debit cards, online banking, and overdraft facilities',
    '["Retail Customer", "Small & Medium Enterprise"]',
    '["Americas", "Brazil"]',
    '["In-Branch / Physical Office", "Mobile App", "Online / Web Platform"]',
    '["Internal Transfers (A2A)", "Cash Deposits", "Cash Withdrawals", "Domestic Payments"]',
    false
  ),
  (
    'prod-002',
    '550e8400-e29b-41d4-a716-446655440001', 
    'Corporate Credit Lines',
    'Revolving credit facilities for working capital and business expansion',
    '["Large Corporate", "Fintech"]',
    '["Asia–Pacific", "Americas"]',
    '["Online / Web Platform", "Mobile App", "API / Embedded Integration"]',
    '["Card Payments (POS)", "Card-Not-Present (E-Commerce)", "Loan Disbursements", "Loan Repayments"]',
    false
  ),
  (
    'prod-003',
    '550e8400-e29b-41d4-a716-446655440001', 
    'Investment Funds (Fundos de Investimento)',
    'Mutual funds including fixed income, equities, and multi-market strategies',
    '["Large Corporate", "High-Net-Worth Individual"]',
    '["Americas", "Brazil"]',
    '["In-Branch / Physical Office", "Broker / Intermediary"]',
    '["Direct Debits / Standing Orders", "Card-Not-Present (E-Commerce)", "Investment Transactions"]',
    false
  );

Valid Enum Values for Products

FieldValid Values
customer_typesFinancial Institution, Fintech, High-Net-Worth Individual, Large Corporate, Merchant, Public Sector Entity, Retail Customer, Small & Medium Enterprise, Sole Proprietor
geographic_operationsAmericas, Asia–Pacific, Europe, Middle East & North Africa, Sub-Saharan Africa (or specific countries)
distribution_channelsAPI / Embedded Integration, Broker / Intermediary, Call Center / Assisted, In-Branch / Physical Office, Mobile App, Online / Web Platform, Partner Platform / Marketplace, Third-Party Sales Agent
transaction_typesCard Payments (POS), Card-Not-Present (E-Commerce), Cash Deposits, Cash Withdrawals, Direct Debits / Standing Orders, Domestic Payments, Internal Transfers (A2A), International / Cross-Border Payments, Investment Transactions, Loan Disbursements, Loan Repayments, Merchant Settlements, Mortgage Disbursements, Refunds / Chargebacks

Sample Risk Library

Risk Scenarios

Risk Scenarios support multiple risk groups and categories (stored as comma-separated values or arrays). Use the valid enum values below.
-- Create risk scenarios with proper enum values
INSERT INTO risk_scenarios (id, enterprise_id, name, description, category, risk_group, archived)
VALUES
  (
    'rs-001', 
    '550e8400-e29b-41d4-a716-446655440001', 
    'Consumer Loan Default Risk', 
    'Risk of consumer loan defaults due to economic downturn or over-indebtedness', 
    'Fraud', 
    'Customer Risk', 
    false
  ),
  (
    'rs-002', 
    '550e8400-e29b-41d4-a716-446655440001', 
    'Cyberattack on Digital Banking Platform', 
    'Risk of data breach or system downtime due to sophisticated cyber attacks targeting financial infrastructure', 
    'Cybercrime', 
    'Technology & Cyber Risk', 
    false
  ),
  (
    'rs-003', 
    '550e8400-e29b-41d4-a716-446655440001', 
    'Anti-Money Laundering (AML) Control Failure', 
    'Risk of failing to detect and report suspicious transactions in compliance with regulatory requirements', 
    'Money Laundering', 
    'Operational Risk', 
    false
  ),
  (
    'rs-004', 
    '550e8400-e29b-41d4-a716-446655440001', 
    'Interest Rate Risk in Banking Book', 
    'Risk of losses due to adverse movements in interest rates affecting the banking book', 
    'Proliferation Financing', 
    'Operational Risk', 
    false
  );

Valid Enum Values for Risk Scenarios

FieldValid Values
risk_groupCustomer Risk, Delivery Channel Risk, Employee Risk, Geographic Risk, Governance & Control Risk, Operational Risk, Product & Service Risk, Technology & Cyber Risk, Third-Party / Outsourcing Risk, Transactional Risk
categoryBribery & Corruption, Cybercrime, Fraud, Misconduct / Insider Risk, Money Laundering, Proliferation Financing, Sanctions Risk, Tax Crime / Tax Evasion, Terrorist Financing

Key Controls

-- Create key controls
INSERT INTO key_controls (id, enterprise_id, name, description, archived)
VALUES
  ('kc-001', '550e8400-e29b-41d4-a716-446655440001', 'Automated Credit Scoring and Risk Rating', 'Standardized credit scoring model using bureau data and behavioral analytics', false),
  ('kc-002', '550e8400-e29b-41d4-a716-446655440001', 'Multi-Factor Authentication (MFA)', 'Mandatory MFA for digital banking access', false),
  ('kc-003', '550e8400-e29b-41d4-a716-446655440001', 'Real-Time AML Transaction Monitoring', 'Automated system monitoring all transactions for suspicious patterns', false);

Sub-Controls

Sub-Controls are created in Governance with only name and description. The ToD/ToE ratings are assessed separately in Control Assurance after the sub-control is created. This separates the control definition from the control assessment workflow.

Step 1: Create Sub-Controls (Governance)

-- Create sub-controls with name and description only
-- ToD/ToE ratings are assessed separately in Control Assurance
INSERT INTO sub_controls (id, key_control_id, name, description, archived)
VALUES
  ('sc-001', 'kc-001', 'Bureau Data Verification', 'Automated verification of credit bureau data against major bureaus', false),
  ('sc-002', 'kc-001', 'Income and Employment Verification', 'Cross-checking of stated income against employer databases and tax records', false),
  ('sc-003', 'kc-002', 'Biometric Authentication Enrollment', 'Facial recognition or fingerprint enrollment for mobile app access', false),
  ('sc-004', 'kc-002', 'Failed Authentication Lockout', 'Automatic account lockout after 3 consecutive failed login attempts', false),
  ('sc-005', 'kc-003', 'High-Value Transaction Alerts', 'Real-time alerts for transactions exceeding R$ 50,000', false),
  ('sc-006', 'kc-003', 'PEP Screening', 'Automated screening against Politically Exposed Person databases', false);

Step 2: Assess Sub-Controls (Control Assurance)

-- Update sub-controls with ToD/ToE ratings during Control Assurance
-- ToD: A (Excellent) to E (Inadequate)
-- ToE: 1 (Highly Effective) to 5 (Ineffective)
UPDATE sub_controls SET 
  tod = 'A', 
  toe = '1', 
  total_effectiveness = 'Highly Effective',
  tod_justification = 'Comprehensive design with documented procedures and automated checks',
  toe_justification = 'Sample testing showed 98% effectiveness rate across all tested transactions',
  testing_date = '2026-01-10', 
  tested_by = 'John Smith'
WHERE id = 'sc-001';

UPDATE sub_controls SET 
  tod = 'B', 
  toe = '2', 
  total_effectiveness = 'Effective',
  tod_justification = 'Well-structured verification process with minor documentation gaps',
  toe_justification = 'Sample testing showed 92% effectiveness rate',
  testing_date = '2026-01-10', 
  tested_by = 'John Smith'
WHERE id = 'sc-002';

-- Continue for other sub-controls...

Risk Triggers

-- Create risk triggers
INSERT INTO risk_triggers (id, enterprise_id, name, description, archived)
VALUES
  ('rt-001', '550e8400-e29b-41d4-a716-446655440001', 'Rising Unemployment Rate', 'Unemployment rate exceeds 12%', false),
  ('rt-002', '550e8400-e29b-41d4-a716-446655440001', 'Increased Cyber Threat Alerts', 'Critical security alerts targeting financial institutions', false),
  ('rt-003', '550e8400-e29b-41d4-a716-446655440001', 'Regulatory Inspection Notice', 'Formal inspection notice from regulator', false);

Sample Business Risk Assessment

Create BRA

When a BRA transitions from draft to in_progress, the system captures the current risk appetite level as snapshot_appetite_level. This ensures that changes to the enterprise’s risk appetite don’t affect assessments already in progress.
-- Create a BRA (requires legal_entity_id)
-- snapshot_appetite_level is captured automatically when status changes to in_progress
INSERT INTO business_risk_assessments (
  id, enterprise_id, legal_entity_id, business_unit_id, 
  name, description, status, period, assessor, start_date,
  snapshot_appetite_level
)
VALUES (
  'bra-001',
  '550e8400-e29b-41d4-a716-446655440001',
  'le-001',  -- ACME Bank Brasil S.A.
  'bu-001',  -- Retail Banking
  'Q1 2026 Retail Banking Assessment',
  'Comprehensive risk assessment for retail operations',
  'in_progress',
  'Q1 2026',
  'assessor@acme.com',
  '2026-01-01',
  'Medium'  -- Captured from enterprise risk appetite at time of BRA creation
);

BRA Status Workflow

StatusDescriptionRisk Appetite
draftInitial creation, not startedUses current enterprise appetite
in_progressAssessment underwayUses snapshot_appetite_level (frozen)
pending_reviewSubmitted for reviewUses snapshot_appetite_level
approvedReviewed and approvedUses snapshot_appetite_level
rejectedReturned for revisionsUses snapshot_appetite_level

Add Risk Scenarios to BRA

-- Link risk scenarios to BRA
INSERT INTO bra_risk_scenarios (id, bra_id, risk_scenario_id, name, description, category, included)
VALUES
  ('brs-001', 'bra-001', 'rs-001', 'Consumer Loan Default Risk', 'Risk of consumer loan defaults', 'Credit Risk', true),
  ('brs-002', 'bra-001', 'rs-002', 'Cyberattack on Digital Banking Platform', 'Risk of cyber attacks', 'Operational Risk', true),
  ('brs-003', 'bra-001', 'rs-003', 'AML Control Failure', 'Risk of failing to detect suspicious transactions', 'Compliance Risk', true);

Create Risk Ratings

-- Create inherent and residual risk ratings
-- Risk Score = Impact × Likelihood (1-25)
-- Risk Level is determined by the 5×5 risk matrix (not by score thresholds)
-- See "Risk Matrix" section below for the complete mapping

INSERT INTO bra_risk_ratings (id, bra_id, bra_risk_scenario_id, rating_type, impact_score, likelihood_score, risk_score, risk_level, justification)
VALUES
  -- Inherent ratings (risk_level based on matrix lookup, not score)
  -- Impact 4 (High) × Likelihood 4 (Likely) = Very High
  ('brr-001', 'bra-001', 'brs-001', 'inherent', 4, 4, 16, 'Very High', 'High economic uncertainty and rising consumer debt levels'),
  -- Impact 5 (Severe) × Likelihood 4 (Likely) = Very High
  ('brr-002', 'bra-001', 'brs-002', 'inherent', 5, 4, 20, 'Very High', 'Sophisticated threat landscape targeting financial institutions'),
  -- Impact 5 (Severe) × Likelihood 3 (Possible) = Very High
  ('brr-003', 'bra-001', 'brs-003', 'inherent', 5, 3, 15, 'Very High', 'Complex transaction patterns and evolving regulatory requirements'),
  
  -- Residual ratings (after controls)
  ('brr-004', 'bra-001', 'brs-001', 'residual', 3, 2, 6, 'Medium', 'Credit scoring and collection processes reduce risk'),
  ('brr-005', 'bra-001', 'brs-002', 'residual', 3, 2, 6, 'Medium', 'MFA and security operations significantly mitigate risk'),
  ('brr-006', 'bra-001', 'brs-003', 'residual', 3, 2, 6, 'Medium', 'Real-time monitoring and PEP screening reduce risk');

Sample Risk Appetite

Risk Appetite is configured at the enterprise level. When a BRA is created and transitions to in_progress, the current appetite level is captured as snapshot_appetite_level on the BRA. This ensures that subsequent changes to the enterprise’s risk appetite don’t affect assessments already in progress.
-- Configure enterprise risk appetite
-- This sets the maximum acceptable risk level for new assessments
INSERT INTO risk_appetite (id, enterprise_id, risk_level, threshold_value, description, legal_entity_id)
VALUES
  ('ra-001', '550e8400-e29b-41d4-a716-446655440001', 'Medium', 9, 'Enterprise accepts Medium risk (score ≤9) as maximum tolerance', NULL);

-- Optional: Entity-specific override for stricter requirements
INSERT INTO risk_appetite (id, enterprise_id, risk_level, threshold_value, description, legal_entity_id)
VALUES
  ('ra-002', '550e8400-e29b-41d4-a716-446655440001', 'Low', 4, 'Lower appetite for insurance subsidiary per regulatory requirement', 'le-002');

Risk Appetite Snapshot Behavior

ScenarioBehavior
Enterprise changes appetite from Medium → HighExisting in_progress BRAs keep their snapshot_appetite_level (Medium)
New BRA createdCaptures current enterprise appetite as snapshot_appetite_level
BRA in draft statusUses current enterprise appetite (not yet snapshotted)
BRA transitions to in_progresssnapshot_appetite_level is captured and frozen

Sample Mitigation Actions

-- Create mitigation actions (table is 'mitigation_actions', not 'action_plans')
INSERT INTO mitigation_actions (
  id, enterprise_id, bra_id, bra_risk_scenario_id,
  action, owner, status, priority, due_date, action_type, archived
)
VALUES
  (
    'ma-001',
    '550e8400-e29b-41d4-a716-446655440001',
    'bra-001',
    'brs-002',
    'Implement additional endpoint detection and response (EDR) solution',
    'security@acme.com',
    'in_progress',
    'high',
    '2026-03-31',
    'Technology',
    false
  ),
  (
    'ma-002',
    '550e8400-e29b-41d4-a716-446655440001',
    'bra-001',
    'brs-001',
    'Enhance credit scoring model with additional economic indicators',
    'credit.risk@acme.com',
    'created',
    'medium',
    '2026-06-30',
    'Process',
    false
  ),
  (
    'ma-003',
    '550e8400-e29b-41d4-a716-446655440001',
    'bra-001',
    'brs-003',
    'Conduct AML training for all customer-facing staff',
    'compliance@acme.com',
    'created',
    'high',
    '2026-04-30',
    'Training',
    false
  );

API Testing Examples

Create BRA via API

curl -X POST http://localhost:8000/api/v1/bras \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Corporate Banking Assessment",
    "description": "Risk assessment for corporate banking operations",
    "legal_entity_id": "le-001",
    "business_unit_id": "bu-002",
    "period": "Q1 2026",
    "assessor": "assessor@acme.com"
  }'

Add Risk Scenario via API

curl -X POST http://localhost:8000/api/v1/bras/$BRA_ID/scenarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_scenario_id": "rs-001",
    "included": true
  }'

Create Risk Rating via API

curl -X POST http://localhost:8000/api/v1/bras/$BRA_ID/ratings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bra_risk_scenario_id": "brs-001",
    "rating_type": "inherent",
    "impact_score": 4,
    "likelihood_score": 3,
    "justification": "Based on current economic conditions and portfolio analysis"
  }'

Create Product via API

# Note: Products no longer have a category field
curl -X POST http://localhost:8000/api/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile Banking App",
    "description": "Full-featured mobile banking application for retail customers",
    "customer_types": ["Retail Customer", "Small & Medium Enterprise"],
    "geographic_operations": ["Americas", "Brazil"],
    "distribution_channels": ["Mobile App"],
    "transaction_types": ["Internal Transfers (A2A)", "Domestic Payments", "Card Payments (POS)"]
  }'

Update Control Effectiveness via API (Control Assurance)

# ToD/ToE ratings are assessed in Control Assurance, not during sub-control creation
curl -X PATCH http://localhost:8000/api/v1/controls/sub-controls/sc-001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tod": "A",
    "toe": "2",
    "testing_date": "2026-01-15",
    "tested_by": "John Smith",
    "tod_justification": "Control design is comprehensive with documented procedures and automated checks",
    "toe_justification": "Sample testing showed 95% effectiveness rate across 150 transactions"
  }'

Create Sub-Control via API (Governance)

# Sub-controls are created with name and description only
# ToD/ToE ratings are assessed separately in Control Assurance
curl -X POST http://localhost:8000/api/v1/controls/kc-001/sub-controls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Debt-to-Income Ratio Check",
    "description": "Automated check ensuring borrower debt-to-income ratio is within acceptable limits"
  }'

Approve BRA via API

curl -X POST http://localhost:8000/api/v1/bras/$BRA_ID/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "final_comment": "Assessment reviewed and approved. All risks adequately assessed with appropriate controls."
  }'

Verification Queries

Check Data Counts

SELECT 
  (SELECT COUNT(*) FROM enterprises) as enterprises,
  (SELECT COUNT(*) FROM legal_entities WHERE archived = false) as legal_entities,
  (SELECT COUNT(*) FROM business_units WHERE archived = false) as business_units,
  (SELECT COUNT(*) FROM products WHERE archived = false) as products,
  (SELECT COUNT(*) FROM risk_scenarios WHERE archived = false) as risk_scenarios,
  (SELECT COUNT(*) FROM key_controls WHERE archived = false) as key_controls,
  (SELECT COUNT(*) FROM sub_controls WHERE archived = false) as sub_controls,
  (SELECT COUNT(*) FROM business_risk_assessments) as bras,
  (SELECT COUNT(*) FROM mitigation_actions WHERE archived = false) as actions;

Check BRA Status

SELECT 
  bra.name,
  bra.status,
  le.name as legal_entity,
  bu.name as business_unit,
  COUNT(brs.id) as scenario_count
FROM business_risk_assessments bra
JOIN legal_entities le ON le.id = bra.legal_entity_id
LEFT JOIN business_units bu ON bu.id = bra.business_unit_id
LEFT JOIN bra_risk_scenarios brs ON brs.bra_id = bra.id
GROUP BY bra.id, bra.name, bra.status, le.name, bu.name;

Check Control Effectiveness

SELECT 
  kc.name as key_control,
  sc.name as sub_control,
  sc.tod,
  sc.toe,
  sc.total_effectiveness,
  sc.testing_date
FROM sub_controls sc
JOIN key_controls kc ON kc.id = sc.key_control_id
WHERE sc.archived = false
ORDER BY kc.name, sc.name;

Data Model Reference

ToD Rating Scale

GradeMeaning
AExcellent - Comprehensive design
BGood - Well-structured with minor gaps
CAdequate - Meets minimum requirements
DWeak - Significant gaps
EInadequate - Fundamentally flawed

ToE Rating Scale

GradeMeaning
1Highly Effective (95%+)
2Effective (85-95%)
3Moderately Effective (70-85%)
4Less Effective (50-70%)
5Ineffective (<50%)

Risk Matrix

Risk level is determined by the combination of Impact and Likelihood using the following 5×5 matrix:
Impact ↓ / Likelihood →A (Rare)B (Unlikely)C (Possible)D (Likely)E (Frequent)
5 - SevereMediumHighVery HighVery HighVery High
4 - HighMediumHighHighVery HighVery High
3 - ModerateLowMediumHighHighVery High
2 - MinorLowLowMediumHighHigh
1 - NegligibleLowLowLowMediumMedium

Risk Level Colors

LevelColorMeaning
LowGreenAcceptable risk, monitor only
MediumYellowRequires attention, consider mitigation
HighOrangeSignificant risk, mitigation required
Very HighRedCritical risk, immediate action required

Next Steps

1

Create Test Users

Use scripts to create users with all roles
2

Seed Enterprise Data

Run SQL scripts to populate organization structure
3

Create Risk Library

Add scenarios, controls, and triggers
4

Create and Complete BRA

Walk through full BRA workflow
5

Test API Endpoints

Verify all endpoints work correctly