# Flowthrough / Paythrough Deprecation

Comprehensive documentation for the Flowthrough payment automation and Paythrough contract deprecation initiative in Abacus.

## Documents

| Document | Description |
|----------|-------------|
| [PRD](PRD.md) | Product Requirements Document - business context, goals, requirements, and scope |
| [TRD](TRD.md) | Technical Requirements Document - architecture, ERDs, data flows, system design |
| [End-to-End Walkthrough](../../runbooks/flowthrough/walkthrough.md) | Follow an adjustment file from upload to payment allocation with real AWS/Airflow/UI links |
| [Operations Runbook](../../runbooks/flowthrough/operations.md) | Severity matrix, escalation ladder, Lambda/DAG/SF operations |
| [Debugging Runbook](../../runbooks/flowthrough/debugging.md) | SQL queries, log analysis, state debugging, common failure scenarios |
| [Data Verification Runbook](../../runbooks/flowthrough/data-verification.md) | Prerequisite checks, data integrity queries, end-to-end verification |

## Quick Links

| Resource | URL |
|----------|-----|
| Jira Epic: Deprecate Contracts | [ACC-9366](https://theorchard.atlassian.net/browse/ACC-9366) |
| Jira Epic: Payment Automation | [ACC-9335](https://theorchard.atlassian.net/browse/ACC-9335) |
| Slack Channel | [#tmp-flowthrough-automation](https://sonymusic.enterprise.slack.com/archives/C09RJRL9924) |
| Program Hub | [Google Sites](https://sites.google.com/sonymusic-pde.com/flowthrough-program-hub/requirements?authuser=0) |
| Tech Spec (Notion) | [Manual Flowthrough General File Upload](https://www.notion.so/TECH-SPEC-Manual-Flowthrough-General-File-Upload-2a997177520f803abeb5f170348d9602) |

## Repos

| Repo | What it contains |
|------|------------------|
| `ows-royalties` | Backend API (Flask) - models, endpoints, business logic |
| `frontend-royalties` | React frontend - adjustment upload UI, batch management |
| `lambda-abacus` | AWS Lambda functions - file processing, validation, import, apply |
| `terraform-infra` | Infrastructure as code - step functions, IAM, monitoring |
| `ows-royalties-workflows` | Airflow DAGs - orchestration for upload and import flows |

## Feature Flags (Split.io)

| Flag | Purpose |
|------|---------|
| `abacus_flowthrough_automation` | Enables new step-function-based adjustment processing pipeline |
| `ABACUS_APPLY_FLOWTHROUGH_PAYMENT` <!-- flag torn down 2026-06; see ACC-10470 --> | Enables flowthrough payment fields in validation, import, and apply |
| `abacus_auto_generate_adjustments_flowthrough` | Enables auto-generation of flowthrough adjustment batches |

## Glossary

| Term | Definition |
|------|-----------|
| **Paythrough** | Legacy model: a boolean flag (`is_paythrough_contract`) on contracts that marks them for special payment handling. Being deprecated in favor of flowthrough. |
| **Flowthrough** | New model: configurable payment automation with rates, calculation methods, and per-adjustment payment allocation. Replaces paythrough. |
| **Statement Period** | An accounting period (typically monthly) during which adjustments are collected and processed. Has statuses: `open`, `current`, `closed`. Only the `current` period accepts new adjustments. |
| **Close Balance** | The process of finalizing a statement period's financials for a payment entity. When complete, triggers payment allocation. |
| **Payment Entity** | An organization or entity that receives payments. Each statement period has `statement_period_payment_entity` records linking them. |
| **Payment Allocation** | The process of grouping flowthrough adjustments by contract/payee/currency and creating payment records after balance close. |
| **Payment Schedule** | A configuration defining when payments are due (e.g., "30 days after quarter end"). Used as criteria for auto-generating flowthrough batches. |
| **Adjustment File** | An Excel (.xlsx) spreadsheet containing bulk adjustment entries uploaded to Abacus. Tracked via `statement_period_adjustment_file`. |
| **Adjustment Type** | A classification of the adjustment (e.g., flowthrough, manual). Referenced via `reference_adjustment_type_id`. |
| **Recoupment Cap** | A maximum limit on flowthrough payments for a contract. Once the cap is reached, the flowthrough status transitions to shutoff. |
| **Abacus State** | A state-tracking record (`abacus_state` table) that tracks each step of the adjustment pipeline (upload, validate, import, approve, apply) with states: `init`, `running`, `complete`, `error`. |
| **Abacus Event** | An event record (`abacus_event` table) that triggers actions in the system. Events are routed by `ows-abacus-event` to Airflow DAGs. |
| **Outbox Pattern** | An architectural pattern where events are written to a database table (`abacus_outbox`) in the same transaction as the data change, then published asynchronously to EventBridge by a separate processor. Provides at-least-once delivery — consumers (e.g., payment allocation) use idempotency guards to handle duplicates. |
| **CDC (Change Data Capture)** | A Kafka-based mechanism that watches the `abacus_outbox` table for new rows and triggers the outbox processor Lambda. |
| **MWAA** | Managed Workflows for Apache Airflow — the AWS-managed Airflow service used to run the adjustment processing DAGs. |
| **DLQ (Dead Letter Queue)** | An SQS queue that captures failed EventBridge-to-Step-Function deliveries for later investigation and replay. |
| **BFF (Backend for Frontend)** | The GraphQL gateway layer that bridges the React frontend to the ows-royalties REST API. |

## Team

| Role | Person |
|------|--------|
| Lead | Michael Rojas |
| Backend | Jonathan Raysor, Aarti Navalu, Serhii Laposhko |
| Frontend | Apurva Duduskar, Danielle Vu |
| QA | Xavier Meunier |
| Data | Harmanpreet Singh |