# Single Supply Chain: Company Codes

## TL;DR

We're upgrading the **Signing Entity ↔ SAP Profit Center** relationship from **1:1** to **N:M**, and adding a SAP Profit Center display name.

We're doing this by:
- Adding a `display_name` column to `reference_sap_profit_center`
- Introducing a new mapping (junction) table `signing_entity_profit_center`
- Add a relationship between **Contract → SAP Profit Center** via a **Foreign Key (FK)** (`contract.reference_sap_profit_center_id`)
   - This will replace the existing inheritance via the signing entity. The now legacy `reference_signing_entity.reference_sap_profit_center_id` column will be dropped once we are fully transitioned.

Everything else is plumbing to make these changes safely without breaking the settlement feed, contract APIs, or downstream Snowflake / Looker / GraphQL consumers.

![Schema change: SE↔PC becomes N:M via junction; Contract gets direct FK to PC](images/schema-change.png)

## Value

Decouple Signing Entity from SAP Profit Center in the Abacus royalty accounting database, enabling one legal entity to map to multiple profit centers. Powers Foundation Media's full catalog migration in June/July 2026 and resolves a long-standing structural flaw that currently forces duplicate signing entities with incorrect legal names.

**Approach:** A pure mapping (junction) table (`signing_entity_profit_center`) authorizes which SAP profit centers a signing entity may use, and contracts gain a direct FK to `reference_sap_profit_center`. The user-facing label lives on `reference_sap_profit_center.display_name`. Dual-path read window gated by Harness FF `single_supply_chain_company_codes`. Three ACC epics (M1/M2/M3); destructive changes concentrated in M3. For more details see D24 in [DECISION_LOG.md](DECISION_LOG.md).

## I want to...

### Understand the project

- [Read the business case](PRD.md) — Foundation Media, stakeholders, requirements (F1–F16), success criteria. **Start here.**
- [Read the technical design](TRD.md) — target schema, DDL, backfill, FF rollout, API/GraphQL changes
- [Look up a decision](DECISION_LOG.md) — 29 confirmed decisions with rationale (D1–D29)
- [Compare the options that were considered](SPIKE_SCHEMA_DESIGN.md) — Options A/B/C/D/E side-by-side. Resolved 2026-05-27 in favor of Option B refined.

### Plan and track the work

- [See the roadmap](ROADMAP.md) — M1/M2/M3 epics, 46 tickets with dependency graphs and acceptance criteria
- [See open questions and risks](OPEN_QUESTIONS.md) — Q1–Q13: sequencing risks, behavior questions, bulk operations deferral

### Execute the migration

- [Follow the migration runbook](MIGRATION_RUNBOOK.md) — pre-migration checklist, changeset sequence, verification SQL, rollback plan, contacts
- [Follow the test plan](TEST_PLAN.md) — test cases T1–T26 across DDL, backfill, FF rollout, view switch, M2 admin, M3 cleanup, regression watchlist
- [Roll back a phase](MIGRATION_RUNBOOK.md#rollback-plan) — Liquibase per-changeset rollback, Harness FF flip, view revert SQL

### Coordinate with stakeholders

- Settlement feed regression — Robert Kordisch (signs off M1)
- Signing entity dedup coordination — Humda Rahman (parallel cleanup; M3.13 depends on her canonical IDs)
- Foundation Media / Santa Anna / OVO data load — Finance (Max Lester, Tina Kim) approve after M2.9
- Display name placeholder replacement — Danielle Vu (product owner)
- Escalation on business logic — Charles Owens (technical advisor)

## Slack Channels

| Channel | Purpose |
|---------|---------|
| `#tmp-single-supply-chain` | Project-specific coordination — design questions, ticket blockers, rollout status |
| `#abacus-devs` | Engineering coordination — DDL reviews, model regen, code changes |
| `#abacus` | Cross-team awareness — DDL lands, FF flips, settlement feed regression |
| `#abacus-support` | Business-side / user support — display name placeholder questions, Foundation Media onboarding |

## Jira Epics

| Milestone | Epic | Scope | Target |
|-----------|------|-------|--------|
| **M1** | [ACC-10364](https://theorchard.atlassian.net/browse/ACC-10364) — Backend Decoupling + Manual Workflow | DDL, backfill, FF-gated dual read, contract-write accepts PC, model regen | ~June 6, 2026 |
| **M2** | [ACC-10390](https://theorchard.atlassian.net/browse/ACC-10390) — Self-Service UI | PC admin page with manage-SEs drawer, cascading dropdown on contract form, Foundation Media data load | ~June 20, 2026 |
| **M3** | [ACC-10391](https://theorchard.atlassian.net/browse/ACC-10391) — Contract Moves + Cleanup | Contract PATCH to move PC, FF removal, drop legacy SE.PC column, SE dedup | ~July 4, 2026 |

## Key Repositories

| Repository | Role in this project |
|------------|----------------------|
| [`database`](https://github.com/theorchard/database) | Liquibase migrations — DDL changesets land in `royalty_accounting/build/changelog/ddl/` |
| [`ows-abacus-contract`](https://github.com/theorchard/ows-abacus-contract) | Contract CRUD writes — accept `reference_sap_profit_center_id` on contract create/update, validate against junction |
| [`ows-royalties`](https://github.com/theorchard/ows-royalties) | FF-gated dual read path in `Contract.get_sap_profit_center_by_contract_id()` |
| [`lambda-abacus`](https://github.com/theorchard/lambda-abacus) | `sync_contract_sap` — FF-gated dual `Prctr` source |
| [`graphql-abacus`](https://github.com/theorchard/graphql-abacus) | New `SapProfitCenter` + `SigningEntityProfitCenter` types; extend `AbacusContract` and `SigningEntity` |
| [`frontend-royalties`](https://github.com/theorchard/frontend-royalties) | Contract detail `display_name` (M1); cascading dropdown + admin screen (M2) |
| [`abacus-looker`](https://github.com/theorchard/abacus-looker) | 10 LookML views updated to surface `display_name` and join via `contract.reference_sap_profit_center_id` |
| [`python-abacus-models`](https://github.com/theorchard/python-abacus-models) | Regenerated with `SigningEntityProfitCenter` + altered Contract/ContractHistory/ReferenceSapProfitCenter models |
| [`ows-moneyhub`](https://github.com/theorchard/ows-moneyhub) | Has SELECT on `reference_sap_profit_center` — receives SELECT grant on new junction |

## Source Documents

Meeting notes, spreadsheets, the original PRD, and SAP data live in Google Drive:

[Single Supply Chain: Company Codes — Google Drive](https://drive.google.com/drive/folders/1JmDY3fKR3YyaLAE8A52sxXyYc-jUxRUZ)

Key files:
- Original PRD (`_EXT_ PRD_ Single Supply Chain Foundation Media - FINAL.docx`)
- Company Codes Master Sheet (`Company Codes Master Sheet.docx`)
- Meeting notes — 4 Gemini transcripts (Feb 4, Feb 11, Feb 18, Feb 24)
- Signing Entity / Paid By mapping — 82 rows (`Copy of Signing Entity _ Paid By Mapping.xlsx`)
- Ideal mapping — target state (`Ideal Company Code_Profit Center Mapping.xlsx`)
- SAP profit center dump — 25,709 rows (`SAP_Profit_Centers_03062026.xlsx`)
- Financial model screenshot (`Screenshot 2026-03-18 at 3.13.15 PM.png`)