# Transfer of Product Ownership (Accounting)

Documentation for the Abacus / accounting portion of Transfer of Product Ownership (PORT):
moving a project's UPCs/ISRCs between accounts without a redelivery, and keeping contract
terms and revenue attribution correct across the move. Source of truth is the code on
`upstream/master` of the repos listed below.

This project doc covers the accounting scope only. The full transfer state machine (content
movement, artist resolution, analytics) is described in the Notion SFN design linked below.

## Documents

| Document | Description |
|----------|-------------|
| [TRD](TRD.md) | Technical design of the accounting portion: the `edit-attachments` step, the contract-term changes, data model, idempotency, revenue cutoff, and rollback |
| [Backend Runbook](../../runbooks/transfer-of-product-ownership/backend.md) | Operating the `edit-attachments` step: flow, monitoring, common failures, and the DB-PR rollback |
| [Frontend Runbook](../../runbooks/transfer-of-product-ownership/frontend.md) | The Abacus "Transfer Project" queuing screen, term selection, and queue monitoring |
| [Learn (Accounting view)](../../learn/transfer-of-product-ownership.md) | What happens to contracts and revenue when a product moves |

## Quick Links

| Resource | URL |
|----------|-----|
| Jira board: PORT | [PORT board](https://theorchard.atlassian.net/jira/software/c/projects/PORT/boards/1450) |
| PRD (Notion) | [Transfer Product Ownership (PORT) PRD](https://www.notion.so/f8a286b4635d4d51bb674551e5b71e14) |
| SFN Design (Notion) | [Product Transfer - SFN Design](https://www.notion.so/35097177520f8161bafbffa1049a07fb) |
| Authorization (PDP) | [PORT-69](https://www.notion.so/35997177520f81d28c06c9667efcf6ca) |

## Repos

| Repo | What it contains (accounting scope) |
|------|------------------|
| `lambda-product-transfer` | The `edit-attachments` lambda (and the sibling SFN step lambdas) |
| `ows-royalties` | Contract-term attachment endpoints (`bulk` remove, `transfer-create`) and the staged transfer-term endpoints (`/transfer-job/{id}/terms`) |
| `ows-project-manager` | Transfer job records and UPC/ISRC resolution (`/transfer/job/{id}/attachments`) |
| `frontend-royalties` | The "Transfer Project" queuing, term-selection, and monitoring UI |
| `terraform-infra` | The `{env}-product-transfer` state machine, lambdas, SQS FIFO queue, and monitoring |
| `dbt-accounting` | Revenue models. No transfer-specific cutoff filter ships; attribution derives from `DIM_RELEASE_HISTORY` |

## Glossary

| Term | Definition |
|------|-----------|
| **Originating account** | The account a project is transferred from (`originating_vendor_id`). |
| **Destination account** | The account a project is transferred to (`destination_vendor_id`). |
| **Transfer job** | A `project_transfer_job` row (in art_relations) tracking one project's move: status (`QUEUED`/`PROCESSING`/`COMPLETED`/`FAILED`/`DELETED`), vendors, and `revenue_cutoff_date`. |
| **Staged term** | A `project_transfer_term` (+ `project_transfer_term_condition`) row written at queue time, describing a contract term to recreate on the destination. |
| **Edit Attachments** | The accounting step of the state machine; moves UPC/ISRC attachments off the originating account's terms and creates them on the destination. |
| **transfer-create** | The ows-royalties endpoint that creates one destination `contract_term` per staged term, idempotent on `project_transfer_term_id`. |
| **Revenue cutoff** | `project_transfer_job.revenue_cutoff_date` (last day of the prior month). Splits revenue: originating account keeps revenue booked through the cutoff, destination gets everything after. |
| **DIM_RELEASE_HISTORY** | `FACTS.DIM_RELEASE_HISTORY`, the effective-dated release-to-owner timeline. Written by the `update-dim-tables` lambda; the sole mechanism for the post-transfer revenue cutoff. |

## Team

| Role | Contact |
|------|---------|
| Project | PORT enablement team (see the PORT board) |