Skip to Content
Architecture Diagrams

Architecture Diagrams

Visual documentation of VINCTA’s system architecture, data flows, and processes.

System Architecture

High-level overview of VINCTA’s technical architecture.

Key Components:

  • Frontend: Next.js 14 with React, hosted on Vercel
  • API Layer: Next.js API routes and server actions
  • Database: Supabase PostgreSQL with RLS
  • Security: HMAC signature verification, RBAC, magic link auth
  • Infrastructure: Vercel edge network, EU data residency

Webhook Processing Flow

Detailed flow of how vendor alerts are processed.

Processing Steps:

  1. Signature Verification: HMAC-SHA256 validation
  2. Idempotency Check: Prevent duplicate processing
  3. Schema Validation: Ensure required fields present
  4. Normalization: Convert to internal format
  5. Identity Resolution: Match or create customer
  6. Risk Assessment: Apply rules, calculate priority
  7. Case Creation: Generate case with evidence
  8. Audit Logging: Immutable trail of all actions

Case Lifecycle & Status Transitions

How cases move through the compliance workflow.

Status Definitions:

  • Open: New case, awaiting analyst assignment
  • In Progress: Analyst actively investigating
  • Pending Info: Waiting for additional documentation
  • Pending Approval: Awaiting MLRO/Admin decision (maker-checker)
  • Escalated: Requires senior analyst or MLRO review
  • Expired: Approval request timed out (7 days)
  • Resolved: Investigation complete, decision made
  • Closed: Final archival state

RBAC & Maker-Checker Workflow

Role-based access control and approval process.

Maker-Checker Rules:

  1. Trigger Conditions:

    • HIGH or CRITICAL risk cases
    • ALL SAR/STR filings (any risk level)
    • Case escalations

  2. Role Requirements:

    • Maker: Analyst role
    • Checker: Admin or Compliance Officer (MLRO)
    • Must be different roles (GwG §25)
    • Must be different users

  3. Mandatory Requirements:

    • Checker must view full case before decision
    • Checker notes required (document reasoning)
    • Approval expires after 7 days
    • Rejected cases return to analyst with reason

Data Flow: Alert to Case

Complete data flow from vendor alert to case creation.

Data Transformation:

  1. Vendor Format → Internal Format

    • Unit21: alert_id → vendor_alert_id
    • HAWK AI: alertId → vendor_alert_id
    • Normalize field names and types

  2. Customer Identification

    • Extract: customer_id, entity_id, customerId
    • Match: Email, phone, ID number
    • Fuzzy matching for name variations

  3. Risk Scoring

    • Vendor risk score (0-100)
    • Internal risk assessment
    • Priority mapping: 80-100=HIGH, 40-79=MEDIUM, 0-39=LOW

Multi-Tenant Architecture

How VINCTA isolates data between clients.

Isolation Mechanisms:

  1. JWT Claims:

    • Every user token includes client_id
    • Verified on every API request
    • Cannot be spoofed or modified

  2. Row-Level Security (RLS):

    • Database-level enforcement
    • Every query automatically filtered by client_id
    • Cannot be bypassed via SQL injection
    • Enforced even for admin users

  3. Application-Level Checks:

    • Additional validation in API layer
    • User role verification
    • Permission checks per action

  4. Audit Trail:

    • All cross-client access attempts logged
    • Alerts for suspicious activity
    • Regular security audits

Database Schema Overview

Core tables and relationships.

Key Relationships:

  • Multi-Tenancy: All tables include client_id for RLS
  • Customer-Centric: Cases and alerts linked to customer profiles
  • Audit Trail: Case activities track all actions
  • Maker-Checker: Approval requests link makers and checkers
  • Evidence Chain: Vendor alerts linked as case evidence

Deployment Architecture

Infrastructure and hosting setup.

Infrastructure Details:

  • Frontend Hosting: Vercel (EU edge network)
  • Database: Supabase PostgreSQL (EU region)
  • CDN: Global edge network for low latency
  • Backups: Daily automated backups, 30-day retention
  • Monitoring: Uptime monitoring, error tracking
  • Security: HTTPS everywhere, RLS at database level

Integration Points

External systems and data exchange.

Integration Types:

  1. Inbound Webhooks:

    • Real-time alert delivery from vendors
    • HMAC-SHA256 signature verification
    • Idempotency handling
    • Automatic retry on failure

  2. Data Normalization:

    • Vendor-specific adapters
    • Convert to internal schema
    • Field mapping and validation

  3. Outbound (Future):

    • REST API for external systems
    • Webhook notifications
    • Report exports

Usage Notes

Viewing Diagrams

These diagrams use Mermaid syntax and render automatically in:

  • Nextra documentation sites
  • GitHub markdown files
  • Most modern documentation platforms

Updating Diagrams

To modify a diagram:

  1. Edit the Mermaid code block
  2. Test rendering at mermaid.live 
  3. Update this file
  4. Commit and deploy

Diagram Standards

Color Coding:

  • 🔵 Blue (#e1f5ff, #e3f2fd) - External systems
  • 🟡 Yellow (#fff4e6) - Infrastructure, security
  • 🟢 Green (#e8f5e9, #c8e6c9) - Processing, success
  • 🟣 Purple (#f3e5f5) - Client-specific data
  • 🔴 Red (#ffebee, #ffcdd2) - Errors, validation

Conventions:

  • Rectangles: Processes, components
  • Cylinders: Databases, storage
  • Diamonds: Decision points
  • Arrows: Data flow, relationships
  • Dashed lines: Optional or future features

Last Updated: 2024-12-17
Diagrams: 9 total (architecture, flows, workflows)
Format: Mermaid.js (auto-rendering)

API ReferenceSecurity & Compliance