# PRD: Single Supply Chain — Company Codes

**Date:** 2026-05-18

**Author:** Michael Rojas

**Status:** Draft

## Stakeholders

| Name | Role |
|------|------|
| Michael Rojas | Project tech lead |
| Charles Owens | Technical advisor — primary decision maker on data model |
| Danielle Vu | Product owner — PRD author |
| Sean Golden | Engineering — proposed "servicing entity" concept |
| Robert Kordisch | Settlement feed owner — confirmed no impact |
| Humda Rahman | Signing entity cleanup — in-progress parallel work |
| Max Lester, Tina Kim | Finance — QC process, approval workflow |
| Kuhuk Goyal | Account creation — confirmed payment entity derivation unchanged |
| Nico Lombard | Engineering — confirmed P&L reconciliation follows existing process |
| Troy Denkinger | Engineering — content/insights account creation |
| George Theka | Engineering |

---

## 1. Executive Summary

Decouple the rigid 1:1:1 relationship between Signing Entity, Company Code, and Profit Center in the Abacus royalty accounting database. This enables Foundation Media and the broader Sony ecosystem to operate with one legal entity mapping to multiple profit centers — a structure Sony already uses outside The Orchard.

**Hard deadline:** Foundation Media full catalog migration — June/July 2026.

---

## 2. Problem Statement

The Orchard has historically operated under a 1:1:1 relationship between Signing Entity (legal entity on contract), Company Code (SAP financial container), and Profit Center (revenue-generating unit). This is enforced by the `reference_signing_entity` table in the Abacus MySQL database.

**Foundation Media** (company code 2755) breaks this model. As a distributor for Santa Anna (distributed through The Orchard), the content does not conform to 1:1. Outside The Orchard, Sony Music does not follow this alignment.

**Concrete impact:**
- Santa Anna (signing entity ID 21) needs two profit centers: SA-FM Originated (US7219) and Santa Anna (US6286)
- OVO (signing entity ID 22) needs two profit centers: OVO Catalog (US6703) and OVO New (US7260)
- Foundation Media (signing entity ID 20) needs its own: Foundation 3P (US6284)
- Without this change, 5 duplicate signing entities would be required — with incorrect legal entity names on 4 of them

**Existing data quality issues proving the structural flaw:**
- "Orchard Enterprises NY Inc" already appears 3 times (IDs 13, 27, 34) as separate signing entities — same legal name, different profit centers
- 82 total rows in the reference table; many are duplicates created to work around the 1:1 limitation

---

## 3. Users & Personas

| Persona | Role | Needs |
|---------|------|-------|
| **Contract Admin (CA)** | Creates and manages contracts in Abacus | Select the correct profit center when creating a contract; move contracts between profit centers |
| **Finance Team** | Reviews and approves financial entity relationships; maintains SAP | QC new entity relationships; receive notifications when profit centers change on contracts; reconcile P&L |
| **Solutions Team** | Creates accounts in A360, sets up initial account metadata | No direct impact (payment entity derivation unchanged) |
| **Abacus Engineering** | Maintains and extends the Abacus platform | Enters new entity relationships manually (M1 interim workflow) |

---

## 4. Requirements

### 4.1 Functional Requirements

#### Must Have (M1 — Before June 2026)

| ID | Requirement | Rationale |
|----|-------------|-----------|
| F1 | Break the 1:1 link between Signing Entity, Company Code, and Profit Center in `reference_signing_entity` | Core structural change enabling all other requirements |
| F2 | Introduce a new mapping between Signing Entity and Profit Center, with a user-facing display name | One legal entity can map to multiple profit centers; users need a human-readable label |
| F3 | Display name is surfaced on all external documents | Replaces legal name in external-facing contexts. Placeholder names are acceptable until business provides real names (D20). Note: D18 confirms showing both display name and SAP code in the Abacus UI, but whether external docs show display name only or both is unresolved. |
| F4 | Backfill all existing signing entities with corresponding mapping records | No contracts can be orphaned |
| F5 | Display the mapping's display name on the contract detail view in the Abacus UI | Users can see which profit center a contract is assigned to |
| F6 | Support the 5 Foundation Media / Santa Anna / OVO profit center mappings | The immediate business need that triggered this work |
| F7 | Abacus team can manually enter new Signing Entity <> Profit Center relationships | Interim workflow; users email the team with new relationships |

#### Should Have (M2)

| ID | Requirement | Rationale |
|----|-------------|-----------|
| F8 | When creating a contract, show a cascading dropdown: Signing Entity -> filtered profit center mappings | Self-service; eliminates email-based workflow |
| F9 | Auto-select the mapping when a Signing Entity has exactly one option | Preserves current UX for the majority of entities (no extra click) |
| F10 | Admin screen for managing profit center mappings (CRUD) | Finance/admin can create, edit, soft-delete mappings |
| F11 | Validate that company_code + profit_center combinations exist in SAP before creating a mapping | Prevents invalid financial routing |
| F12 | Looker report showing new mappings, contracts by mapping, and backfill gaps | Visibility and QA for Finance |

#### Could Have (M3)

| ID | Requirement | Rationale |
|----|-------------|-----------|
| F13 | Update or move contracts to different profit center mappings | Business flexibility as relationships evolve |
| F14 | When a contract's profit center mapping changes, trigger the existing P&L reconciliation notification to Finance | Finance must make corresponding SAP changes |
| F15 | When a signing entity changes on a contract, require re-selection of profit center from the new entity's options | Prevent orphaned financial routing |
| F16 | Audit trail for all profit center mapping changes on contracts | Compliance and traceability |

#### Out of Scope

- SAP profit center creation — stays with SAP tech team (D6)
- "Owned" label revenue classification — different mechanism; on Sam's plate
- Consultation with other Sony labels — not needed (D16)
- Payment entity derivation — unchanged, stays on signing entity (D5)
- KN&R payable feed and Slaughterhouse (internal revenue-to-account mapping pipeline) — unaffected

### 4.2 Non-Functional Requirements

| ID | Requirement |
|----|-------------|
| NF1 | Settlement feed must continue to work without changes (D4) |
| NF2 | Backfill must be idempotent and auditable — can re-run without creating duplicates |
| NF3 | No downtime during schema migration |

### 4.3 Technical Constraints (implementation details — see TRD for specifics)

| ID | Constraint |
|----|------------|
| TC1 | Migration uses nullable column additions, then backfill, then NOT NULL enforcement — avoids downtime |
| TC2 | Snowflake sync must be updated to replicate the new table and resolve profit centers through it |
| TC3 | `python-abacus-models` (the Python ORM models used by backend services and data pipelines) must be regenerated for both MySQL and Snowflake schemas |

---

## 5. Naming Decision Required

Four terms have been used for the same concept: "Profit Center Name" (PRD), "Servicing Entity" (Feb 4 meeting), "Servicing Center" (ideal mapping spreadsheet), and "Revenue Servicing Entity" (Feb 11 meeting). See D17 in the Decision Log for the full history. The naming question is intertwined with the schema approach — see [SPIKE_SCHEMA_DESIGN.md](SPIKE_SCHEMA_DESIGN.md) for the Option A vs B framing.

**Does not block engineering.** The DB column name and UI label are independent. Placeholders are used until the decision is made.

---

## 6. Success Criteria

| Metric | Target |
|--------|--------|
| Foundation Media, Santa Anna, and OVO contracts can be created with correct profit centers | M1 |
| No duplicate signing entities needed for multi-profit-center legal entities | M1 |
| All existing contracts have a FK to the new mapping table (zero NULLs after backfill) | M1 |
| Settlement feed continues to operate correctly (zero regression) | M1 |
| Contract admins can self-service profit center selection during contract creation | M2 |
| Finance has Looker visibility into all profit center mapping relationships | M2 |

---

## 7. Open Questions

None of these block engineering work. Placeholders are used where business input is pending; all can be resolved with data updates (no code change, no deploy).

| # | Question | Impact If Delayed | Owner |
|---|---|---|---|
| 1 | Display names for existing 82 entities — what should each one be called? | Placeholder names shown in UI; updated via SQL when provided | Business / Finance |
| 2 | Finance submission workflow — admin screen or approval queue? (Also SPIKE_SCHEMA_DESIGN Q7) | Admin screen ships without approval workflow; add later if needed | Max Lester / Tina Kim |
| 3 | Naming — see D17 in Decision Log (also SPIKE_SCHEMA_DESIGN Q3) | UI defaults to placeholder; one label constant to change | Stakeholder group |
| 4 | Looker report requirements — what metrics/dimensions? | Report ships with default columns; refine based on feedback | Business |
| 5 | What happens when the right mapping doesn't appear for a signing entity? | Users email the Abacus team (M1 manual workflow); escalation flow added in M2 | Product |
| 6 | QC process — block accounting activity until Finance signs off? | No blocking by default; add gating later if Finance requires it | Finance |
| 7 | "Owned" label revenue — out of scope? | Confirmed out of scope for M1-M3; separate initiative | Sam |

---

## 8. References

| Document | Location |
|----------|----------|
| Source documents (PRD, meeting notes, spreadsheets, SAP data) | [Google Drive](https://drive.google.com/drive/folders/1JmDY3fKR3YyaLAE8A52sxXyYc-jUxRUZ) |
| Schema spike (Options A, B, C) | [SPIKE_SCHEMA_DESIGN.md](SPIKE_SCHEMA_DESIGN.md) |
| Decision log | [DECISION_LOG.md](DECISION_LOG.md) |