Skip to content

PayeeOnBoarding

Jump to bottom
Norman Khine edited this page May 9, 2025 · 2 revisions

Architecture Decision Record (ADR)

Title: Proposal - Functionless Payee Onboarding Architecture with Event-Driven Processing and Encrypted Document Storage

Status

Key Value
Status Proposed
Author
Informed
Required approvers
Decision record

Context

Payee Onboarding MVP aims to create a streamlined, secure, and self-service process for onboarding payees into the ecosystem. The PRD highlights key challenges, including inconsistent onboarding experiences, incomplete data capture, operational inefficiencies, and security risks arising from email-based data collection.

This proposed architecture aligns with requirements, offering a functionless, event-driven core while incorporating Lambda for:

  • Secure document upload via EFS with encryption management.
  • Field-level IAM protection in DynamoDB.
  • File size validation to enforce business rules.
  • Proxying requests to sanitise and protect backend services.

This ensures the system remains secure, extensible, and compliant with regulatory and internal requirements.

Decision

Proposed Architecture Overview

Infra

1. Invitation and Session Initiation

  • Payees receive a secure link (or manually enter an invitation code).
  • Invitation codes are stored in DynamoDB, using a Global Secondary Index (GSI) for efficient lookups.
  • Session IDs are generated using compact UUIDs, stored in DynamoDB, and set as HTTP cookies to maintain continuity across steps.

2. Mobile Number Capture and OTP Generation

  • Payees provide their mobile number.
  • An OTP is generated and stored directly in DynamoDB alongside the session record.
  • An EventBridge PutEvents action is triggered via API Gateway, emitting an OTPGenerated event onto a Global EventBus, where downstream consumers (e.g., notifications or auditing systems) can listen for it.

3. OTP Verification

  • Payees enter the OTP, which is validated directly against the stored value in DynamoDB.
  • If correct, the OTP is cleared from DynamoDB to prevent replay attacks.
  • Successful verifications trigger a PayeeVerified event onto EventBridge, enabling asynchronous downstream processing (e.g., compliance checks, notifications).

4. Document Upload and Processing (EFS Integration)

  • Document uploads are handled via Lambda functions that:
    • Mount EFS securely.
    • Check the file size and type against business rules.
    • Encrypt each file using a unique encryption key per file.
    • Store the encryption key in DynamoDB, with field-level IAM permissions applied, ensuring only authorised roles can retrieve the encryption key.
    • Emit a DocumentUploaded event to EventBridge, allowing audit logging and optional downstream processing (e.g., Textract analysis, fraud detection).

This approach ensures:

  • Files are encrypted at rest in EFS.
  • Encryption keys are protected via field-level IAM in DynamoDB.
  • Upload policies (file size, type) are enforced before writing to EFS.
  • **Audit trails are maintained via EventBridge for every upload.

Functionless Architecture Emphasis

  • Direct AWS Service Integrations (Functionless Core):

    • API Gateway directly integrates with DynamoDB (PutItem, UpdateItem, Query) using VTL (Velocity Template Language).
    • API Gateway directly triggers EventBridge (PutEvents) for all significant state changes.

  • Limited Lambda Scope (HTMX + Document Upload):

    • Lambda is limited to:
      • UI rendering (HTMX partials).
      • Session management and validation.
      • File upload, encryption, and storage (EFS).
      • File size and content validation.
      • Proxying requests to protect backend services.
      • Sanitisation and normalisation of requests.

  • Event-Driven Processing:

    • All significant actions (OTP generation, verification success, document upload) are captured as events onto the Global EventBus, enabling:
      • Audit Logging.
      • Compliance/FinCrime processing (sanctions screening, etc.).
      • Notification triggers (email/SMS confirmations).
      • Real-time operational monitoring.

Security and Data Protection

  • Session Management:

    • Sessions are tied to a Session ID stored in DynamoDB.
    • Sessions are represented as secure HTTP cookies.
    • Sessions are short-lived, with automatic expiry.
    • Session records are periodically cleaned up (either through TTL or explicit process).

  • Data Sanitisation and Proxying:

    • All requests (including session initiation, mobile capture, and OTP verification) are validated and sanitised at the Lambda layer before being passed to backend services.
    • Lambda acts as a proxy layer, protecting all direct access to DynamoDB and EventBridge, ensuring no sensitive backend services are exposed directly to external users.

  • Document Encryption and Field-Level IAM:

    • Each uploaded document is:
      • Encrypted with a unique key per file.
      • Stored in EFS (encrypted).
      • Its encryption key stored in DynamoDB, with IAM policies limiting which roles can access it.
      • This ensures even if the document is exposed, it is useless without the associated key.

  • File Size and Format Validation:

    • During uploads, Lambda checks file size, format, and content type, rejecting uploads that:
      • Exceed size limits.
      • Have unsupported formats.
      • Fail any business-specific validation rules (e.g., only PDFs allowed for a given jurisdiction).

Benefits Over HubSpot Approach (PRD Reference)

Criteria Proposed Architecture HubSpot Approach (PRD)
Security Full control over data handling & encryption Relies on HubSpot SaaS controls
Data Ownership All data stays within AWS environment Data stored in external HubSpot systems
Flexibility Easily adapted for new jurisdictions/processes Dependent on HubSpot form limitations
Event Capture Full audit trail through EventBridge Limited to HubSpot webhooks
Compliance Checks (COP/Fenergo) Integrated via EventBridge processing Needs additional HubSpot integration
User Journey Control Fully controlled via UI & API Gateway Dependent on HubSpot form configuration
Document Security Full encryption, field-level IAM, and audit logging Limited to HubSpot upload capabilities
File Validation Enforced in Lambda (size, type) Basic validation (if any)

Drawbacks and Risks

  • Increased AWS Complexity:

    • Teams must maintain CDK stacks, request templates, VTL mappings, and EventBridge listeners.
    • Requires deeper expertise in AWS CDK, API Gateway VTL, Lambda (EFS), and EventBridge event patterns.

  • Custom UI Development:

    • Compared to HubSpot forms, the custom UI requires more development effort to build and maintain.

  • Potential for Event Loss (Mitigation Needed):

    • As with any event-driven system, delivery guarantees for EventBridge must be considered.
    • A retry strategy or dead-letter queue (DLQ) should be configured for critical events (e.g., OTPGenerated).

Proposed Next Steps

  1. Proof of Concept (PoC):
    • Invitation creation.
    • ✅ Session handling via cookies.
    • ✅ Mobile capture and OTP generation.
    • OTP verification with EventBridge integration.
    • Document upload with encryption and EFS storage.

PoC demonstrating functionality

  1. Operational Process Definition - Agree:

    • EventBridge event schema.
    • Event consumer responsibilities (e.g., notifications, compliance processing).
    • Monitoring and alerting strategy for onboarding flow.

  2. Security & Compliance Review - Validate that:

    • Data flows meet data handling requirements.
    • EventBridge events contain all required metadata for auditability.
    • Cookie handling complies with session management best practices.

Alignment with Architectural Principles

This proposed Functionless API Gateway + EventBridge + DynamoDB architecture aligns with Architectural Design Principles in the following ways:

  • Modular Services (Principle 1):
    The separation of API Gateway for routing, EventBridge for event handling, DynamoDB for state management, and Lambda for UI orchestration ensures a highly modular architecture that aligns with preference for independently scalable and deployable services.

  • Technology Independence (Principle 2):
    By utilising AWS-native managed services, this architecture minimises technology lock-in and ensures interoperability with other AWS services and evolving technology stack.

  • Measurability and Observability (Principle 5):
    Every significant user action (session creation, OTP generation, document upload) is logged via EventBridge, enabling comprehensive tracking and monitoring, which supports both operational oversight and long-term process improvement.

  • Data as an Asset (Principle 10):
    Payee and session data are stored as structured, queryable records in DynamoDB, ensuring consistency, accessibility, and the ability to enforce data governance policies such as field-level encryption and access control.

  • Data Accessibility and Security (Principle 11 & 13):
    Sessions, payees, and documents are stored in DynamoDB and EFS with encryption at rest, and strict IAM controls on access to sensitive fields, ensuring compliance with regulatory requirements.

  • Ease of Use (Principle 14):
    Combining HTMX-based frontend interactivity with Lambda-powered partial rendering ensures the user experience is seamless, responsive, and intuitive, aligning with usability standards.

  • Business Continuity (Principle 12):
    Stateless design combined with durable data storage in DynamoDB and auditable event flows via EventBridge reduces the risk of data loss and ensures onboarding processes can resume smoothly even in the case of infrastructure failures.

By aligning with these principles, the proposed architecture supports scalability, security, regulatory compliance, and user-centric design, ensuring that the onboarding process is both efficient and resilient.

Clone this wiki locally