Overview

This document defines the Client Processing system architecture—how all financial operations for clients are modeled, calculated, and tracked across domains.

It covers:

• Goals and principles — clear ownership through microservices, one RDS PostgreSQL database with schema-per-domain, full audit, RBAC, and traceability from client deal to general ledger.

• Core domains — Deal, Booking, Settlement, Payments, Invoicing, AR, Revenue Recognition, and GL — each representing a stage in the client earnings lifecycle.

• Data integration — connections to authoritative client data, banks, tax systems, credit sources, and GL/ERP for end-to-end flow.

• Event-driven orchestration — standardized events (DealApproved, CashReceived, SettlementFinalized, etc.) and sagas that automate client revenue, payment, and reporting processes.

• AWS foundation — Fargate/EKS for compute, RDS PostgreSQL for data, EventBridge/SQS for messaging, and Snowflake for analytics.

• Controls and compliance — GAAP/SOX-style change management, audit-ready data, multi-entity and multi-currency support, and secure access governance.

• Non-functional targets — sub-300 ms reads, RPO < 5 min, RTO < 15 min, daily analytics syncs under 60 min.

In essence, it’s the Client Processing architecture blueprint, defining how client deals, cash, settlements, and financial records flow securely and deterministically across all services

Goals, conditions, and constraints

• Microservices for clear ownership.
• One operational database (RDS PostgreSQL) with separate schemas per domain.
• Strong audit, RBAC, approvals, segregation of duties.
• Multi-currency, multi-entity, global banking.
• GAAP, SOX-style change control.
• Deterministic calculations. Full traceability from GL to source.
• Near-real-time exports to Snowflake/Power BI for reporting.

Core bounded contexts → services (own code, shared DB schema)

• Authoritative Data Adapter (read-only mirror of people/orgs; pulls from master data)
• Finance Data Enhancement
• Deal Management
• Booking Management
• Settlement Engine
• Cash Receipts
• Invoicing
• Payments
• AR & Bad Debt
• Revenue Recognition
• Financial Transactions (GL Interface)
• User Access & Entitlements
• Document Service (contracts, cash backup ,invoice, tax docs, LODs - Letter of Direction)
• Notifications & Tasks (queues, alerts, approvals)
• Orchestration (sagas/workflows across domains)
  • each steps run independently
  • If a later step fails, the system runs compensating actions to undo the earlier steps.

Single database strategy (RDS PostgreSQL)

• One cluster.- Multi, Replication

• Schemas per domain: finance_data, deal, booking, settlement, cash, invoice, payments, ar, revrec, gl, authz, docs.

• Strict DB roles to enforce write boundaries (service X can only write its schema; read across as needed).

• Immutable audit: append-only change tables + pgaudit; KMS at rest; row-level security where needed.

• CDC stream (DMS or Debezium on MSK) → Snowflake for analytics/Power BI.

Right external data sources (by function)

• Authoritative data: HR/CRM/Client master (read-only API); buyer/participant registries.
• Credit: D&B (buyer credit pulls).
• Milestones/performance: IMDbPro, Studio System, Box Office Mojo, ticketing feeds.
• Banking: SFTP/host-to-host, SWIFT; card processor APIs.
• Buyer portals: scrape/API for remittance and status.
• Tax/withholding: IRS/CSA data, VAT/GST tables (managed reference).
• GL/ERP: journal import API (NetSuite).

Event model (examples)

• DealApproved, DealAmended
• BookingCreated, BookingUpdated
• MilestoneAchieved, PerformanceMetricsUpdated
• CashReceived, CashIdentified, CashApplied
• SettlementPrepared, SettlementFinalized
• InvoiceIssued, InvoicePaid, WriteOffApproved, RecoveryPosted
• PaymentQueued, PaymentReleased, PaymentOnHold
• RevenueRecognized, RevenueAdjusted
• GLEntriesPosted

AWS reference architecture (high level)

[[Client Framework Diagram]]

Service responsibilities (pin to requirements)

• Finance Data Enhancement

  • Onboard/offboard financial data, loan-outs, payment prefs, tax/withholding.
  • RBAC on sensitive fields, approval workflows, full audit.

• Deal Management

  • Capture guaranteed/milestone/variable comp.
  • Schedules, service dates/locations, amendments, approvals.
  • Pull external performance signals for milestones.

• Booking Management

  • Payment routing (trust vs direct), tax setups, commission structures.
  • Loans/advances lifecycle and recoupment rules.
  • Agent attribution, classification, guild, packages.
  • Docs, notes, status, protected deals.

• Settlement Engine

  • Central calculation: AR, commissions, splits, taxes, rebates, pass-throughs, over/under, loan recoupment.

  • Pre-settlement and final settlement runs; multi-booking support.

  • Statement generation (client/participant/commission).

• Cash Receipts

  • Bank ingestion (wires, ACH, checks, cards).
  • Identification/matching (AI suggestions + manual workflow).
  • Split applications; error handling; exception queues.

• Invoicing

  • Request intake, template selection, multi-currency formatting.
  • Auto distribution, contact mgmt, elapsed-time tracking, consolidation.

• Payments

  • Queues, milestones due, holds, DCA validation.
  • File creation (SWIFT), multi-party payouts, remittance.
  • Workflows and human in the loop, manual approval in place.

• AR & Bad Debt

  • Real-time AR (current + future), aging, CECL.
  • Collections, comms, write-off dual approvals, recovery

• Revenue Recognition

  • Milestone and over-time (ASC-606).
  • Late/early corrections, variable comp accruals (90% rule for next two cycles), approvals.

• Financial Transactions (GL)

  • Balanced journals, coding, FX handling, period control.
  • Batch export, reconciliation, drill-down, corrections via reversals.
  • Any Translation relies on Netsuite to do it. We perform as transactional currency. **

• User Access & Entitlements

  • SSO, roles, action-level control, data-scope by attributes (agent/client/LOB).
  • Conflict checks, certification campaigns, audit packs.

• Document Service

  • Contracts, tax forms, Invoice, remittances. Versioning, ACLs, retention.

• Orchestration & Notifications

  • Sagas across services, SLAs, reminders, escalations.

AWS building blocks (by concern)

• Compute: ECS Fargate Or EKS for each service; ALB internal, API Gateway external.
• Data: RDS PostgreSQL (serverless v2 for elasticity), RDS Proxy; S3 for docs; Glacier for retention.
• Messaging: EventBridge (business events), SQS (work queues), MSK/Debezium optional for CDC.
  • Messaging between system.
  • Very Important!!
• Identity: AWS IAM, AWS SSO/Cognito (federate with EntraID), ABAC tags for data-scope.
• Security: KMS CMKs, Secrets Manager, WAF, Shield, CloudTrail, Config, GuardDuty, Macie (PII).
• Networking: VPC with PrivateLink to banks/vendors where available; AWS Transfer Family for SFTP.
• Observability: CloudWatch, X-Ray, Datadog
• CI/CD: GitHub Actions; Terraform/CDK; blue/green (EKS).

Data contracts and shared DB rules

• Services own their schema and write only to it.

• Cross-service reads via views or read-only roles; prefer events to sync projections.

  • Heavy queries → materialized views refreshed async.

• CDC → Snowflake for BI; keep OLTP clean.

Key workflows (saga sketches)

• Cash→Settlement→Payments

  • CashReceived → identify → CashApplied → SettlementPrepared → approvals → SettlementFinalized→ payment queue → file/transfer → PaymentReleased.

• Deal→Booking→RevRec

  • DealApproved → booking defaults → milestones scheduled → on MilestoneAchieved → RevenueRecognized and, if needed, start over-time schedule.

• Write-off

  • Request → dual approvals (agent+finance) → WriteOffApproved → GL batch → reconciliation.

Open items mapped

• “Settlement” naming conflict → keep Settlement Engine (calculation) vs Payments (disbursement).
• Loan-out selection & LODs → enforced in Booking + Document Service; blocks settlement if missing.
• Commission timing (Drew/Bryce) → configurable rules table in booking.commission_rules; audited changes.
• Change tracking depth → field-level journaling (append-only) across sensitive tables.
• Agent commission calc vs Project Cowbell → externalized rule engine table + feature flag route.
• Participations/residuals → deal.variable_comp items + expected accrual logic (90% next two cycles).
• Milestone capture upstream → light UI + API in Deal/Booking; external signal adapters.
• AR aging basis → setting: invoice/due/service_end; drives AR views.
  • Calculate bad debth, reserves based on how old stuff gets
• Accounting treatments review → policy tables; restrict edits to Finance Admin role.

Non-functional targets

• RPO (Recovery Point Objective) ≤ 5 min (RDS cross-AZ + PITR). RTO ≤ 15 min. (Recoery Time)
• P95 API latency < 300 ms for read paths; calc jobs async.
• Pen-tested external surfaces; least-privilege everywhere.
• Full audit extracts by booking, period, person.
• Downstream Refresh DB Daily. and less that 60 min. (Focus on Delta)
• One Time Large Refreshes less 4 hours
  • Datical/Liquibase Source Versioning for Db Changes.

Next steps

• Confirm external systems list (GL, banks, portals, credit, performance).
• Approve the **schema-per-domain on one RDS Postgres approach.
• Lock the initial event catalog and PII field inventory.
• Stand up skeleton services, infra as code, CI/CD, and the CDC path to Snowflake.

Notes: Revenue Schedule

System archiecture design, technical documenation folder.