The problem this solves

Corporate overhead doesn't sell anything itself, but every store still has to absorb a fair share of it before anyone can say whether that store is actually profitable. The question "how much of Corporate G&A does the NYC Flagship really carry?" has no single obvious answer — it depends on which driver you pick (revenue? headcount? square footage?) and how the allocation cascades through the org (does cost hit stores directly, or pass through a regional layer first?).

Get this wrong and every downstream profitability number is wrong with it: a small, high-headcount store can look artificially unprofitable if IT cost is allocated purely by revenue, while a huge, thin-staffed digital channel can look artificially cheap to run. PCMCS exists specifically to make this allocation auditable — not just "here's the final number" but "here's exactly which pool, at which stage, produced this number."

Audience

FP&A and cost accounting teams who own the corporate allocation methodology. Store and regional controllers who need to understand — and be able to challenge — the overhead they're being charged. Finance leadership deciding whether a driver (revenue vs headcount vs another basis) is still the right allocation basis as the business mix shifts.

Three cost pools, two different drivers

Pool sizes are computed as a percentage of total company revenue at runtime, so they stay proportional no matter which year or scenario is selected — there's no hardcoded dollar figure to go stale.

A fully traced allocation, pool by pool

• KPI row: total allocated overhead for the selected entity, as a % of that entity's revenue, its region, and how many pools were traced
• Bar chart: the three pools' allocated amounts side by side for the selected entity
• Plain-language trace: a sentence per pool explaining exactly why the entity was charged that amount — its share of the driver within its region, and that region's share of the driver company-wide
• Detail table: every number in the two-stage cascade — pool total, region share %, stage-2 amount, entity share within region %, stage-3 amount — nothing is a black box

The first step of the PCMCS module

Allocation Waterfall answers "how much overhead does this entity carry, and why." Reciprocal Cost Allocation (UC14) is the same idea applied to a harder case — cost centers that serve each other, not just downstream entities. Profitability Curve (UC15) is the payoff: it takes this exact waterfall, runs it for every entity at once, and ranks the results.

Recommended integration points

• Store-level P&L review: when a store controller disputes their overhead charge, this trace is the answer — every dollar has an explicit path back to a pool and a driver
• Driver methodology review: before switching a pool's driver from revenue to headcount (or vice versa), model the impact on every entity first
• New entity onboarding: a newly opened store immediately needs an overhead allocation — this shows exactly what it will be charged and why, driver by driver

The numbers

The honest checklist

• ✓You allocate shared/corporate cost to stores, products, or business units and need the allocation to be auditable, not just a spreadsheet formula nobody remembers
• ✓Different cost pools genuinely should use different drivers — you're not comfortable allocating everything by revenue just because it's simplest
• ✓Entities push back on their overhead charge and you need a trace, not just a total, to answer them
• ✗Your organization has a single flat overhead pool with no meaningful driver choice to make
• ✗You need cost centers that allocate to each other, not just downstream to final entities — that's UC14, not this one

Try it now

The live demo recomputes the full two-stage waterfall for any of 42 entities in real time.

Things to try

• Type "Trace NYC Flagship's allocated overhead" into the NLQ bar, then switch to a small store like Santiago — notice the IT pool's headcount-driven share behaves very differently from the revenue-driven G&A and Marketing pools
• Compare a Digital entity (very high revenue, very low headcount) against a similarly-sized physical store — the driver choice visibly changes which pool dominates its total charge

Traceability is the actual product

The allocated dollar amount itself is the easy part — a spreadsheet SUMPRODUCT can do that. What's hard, and what production PCMCS earns its keep on, is being able to answer "why" for any single dollar without re-deriving the calculation by hand. This demo is built around that constraint: every number the UI shows is stored and rendered at every stage, not just the final total, so the trace is a first-class output rather than something reconstructed after the fact.

Pool total → region share → entity share

App UI — Component breakdown

Why two different drivers, not one

A single driver for every pool is the most common allocation shortcut in practice, and it's also the most common source of allocation disputes. Revenue-based allocation systematically under-charges high-revenue/low-headcount entities (a busy digital channel) and over-charges low-revenue/high-headcount ones (a large-format store with heavy staffing but modest per-store sales) for anything that actually tracks people rather than sales — IT seats, help-desk tickets, device refreshes. This demo deliberately splits the three pools across two drivers (revenue for G&A and Marketing, headcount for IT) specifically so that contrast is visible when comparing entities with different revenue-to-headcount ratios.

The driver assignment is a property of the pool definition (ALLOCATION_POOLS[i].driver), not a per-query choice — in a real deployment, changing a pool's driver is a methodology decision that should be deliberate and reviewed, not something an end user toggles per query.

Why region-then-entity, not straight to entity

// Stage 1 → 2: pool total splits across 4 regions by driver share
regionSharePct = regionDriverTotal / companyDriverTotal
stage2Amount   = poolTotal × regionSharePct

// Stage 2 → 3: that region's allocation splits across its entities
entityShareInRegionPct = entityDriver / regionDriverTotal
stage3Amount = stage2Amount × entityShareInRegionPct

Routing through a regional layer instead of going straight from pool to entity mirrors how real allocation methodologies are usually built — regional management overhead genuinely is organized regionally, and even for the two pools that aren't regional in nature, cascading through region first makes the calculation auditable one layer at a time: "is this region's total allocation right?" is a much smaller question than "are all 42 entities' allocations right?", and the region check has to pass before the entity-level checks are even meaningful.

Every pool sums back to exactly its total

Because regionSharePct and entityShareInRegionPct are both computed as a share of driver, not as independently-set percentages, summing stage3Amount across every one of the 42 entities for a given pool reproduces that pool's poolTotal exactly (within floating-point rounding) — there is no leakage and no double-counting built into the math. This was verified directly: a unit test sums every entity's Stage-3 allocation for each of the three pools and asserts the sum equals poolTotal to within half a dollar.

A four-field schema built for one job: pick the entity

Allocation's NLQ schema is {intent, entity, year, scenario, confidence} — deliberately narrow. There's no pool selector, no stage selector: the demo always shows the full three-pool waterfall for whichever entity the query resolves to, because a partial trace (one pool, one stage) isn't actually useful on its own — the value is in seeing all three pools' contributions side by side. The few-shot examples cover the entity-name variety already established across the site's other entity-bearing use cases (bare names, "Trace X's...", possessive phrasing, region-adjacent phrasing) plus year/scenario extraction, reusing the same ENTITY_ALIASES table the other eight entity-driven use cases already share.

Cost model — At-scale projections

LLM cost is flat per query at roughly $0.0002 regardless of company size — the query only resolves an entity name plus year/scenario. The allocation calculation itself is O(entities) per pool for the driver totals (computed once per query, not once per entity), so it scales linearly and stays trivial client-side compute even at real-world scale — a group with 500 entities instead of 42 would still resolve a single entity's trace in well under a millisecond.

Key files

Why this module reuses two other modules' generators instead of its own

PCMCS doesn't own revenue or headcount data — it allocates cost using whatever the entity's actual revenue and headcount already are. Calling genIS() and genWorkforce() directly (rather than duplicating a parallel set of numbers inside the PCMCS data file) keeps the allocation grounded in the same P&L and staffing the FP&A and Workforce modules already show, so a query in one module and a query in another about the same entity never disagree.

Tech stack — Every tool in this build

Known attack surfaces

Guardrails — What prevents bad allocation math

• Driver is a property of the pool, not the query: a user's NLQ phrasing can never change which driver a pool uses — that's a methodology decision fixed in ALLOCATION_POOLS
• Share percentages are always driver-ratios, never independently set: regionSharePct and entityShareInRegionPct are computed from the same driver totals used to size the pool, so the cascade can't produce a total that diverges from poolTotal
• Missing driver data fails to zero, not to a crash: regionRev[region] ? ... : 0 guards every division, so an entity or region with zero of a driver gets zero allocation rather than a NaN propagating through the UI

Who is asking, and what are they allowed to see?

The demo answers neither question — it has a cookie gate and no notion of a user. In production these are the two questions everything else rests on, and they have different answers: authentication is who you are, authorization is what you may see. Corporate SSO settles the first. Only Oracle EPM Cloud can settle the second, and the single most important rule in this section is that this application must never become the place where that decision is made.

9.1 · The identity chain, end to end

9.2 · Federating the corporate identity provider

Oracle EPM Cloud does not replace your directory — it trusts it. The EPM Cloud identity domain is federated with the corporate IdP so authentication happens where it already happens, under policies security has already written.

For the browser application itself, use OIDC Authorization Code flow with PKCE. Not the implicit flow, which is deprecated and leaks tokens through the URL, and never a resource-owner password grant — a finance tool should not be capable of handling a password at all.

9.3 · From group membership to EPM roles

Roles are granted to groups, never to individuals, and the groups come from the directory. That one discipline is what makes joiner/mover/leaver work without anyone having to remember this application exists.

Entra ID group                    →  EPM role / entitlement
──────────────────────────────────────────────────────────────────
FIN-EPM-Analysts                  →  Planning User
FIN-EPM-Controllers-EMEA          →  Power User + EMEA data scope
FIN-EPM-Admins                    →  Service Administrator
──────────────────────────────────────────────────────────────────
Provisioned by SCIM. Remove the user from the group and the
entitlement disappears on the next sync — including here.

For this use case the relevant native entitlement is: PCMCS User with access to the profitability application and its POV.

9.4 · The architectural decision: who enforces?

This is the choice that determines whether the deployment is defensible. Both patterns appear in the diagram above; the difference is where the security boundary actually sits.

The shortcut to refuse. Pattern B built with a Service Administrator account and no filtering at all is the most common way this gets delivered, because it works perfectly in UAT — testers are usually over-entitled, so nobody notices that everyone can see everything. It fails at the first access review, and by then it is in production with real users depending on it.

9.5 · Data-level security is the part that matters

Role membership decides whether a user can open the application. It does not decide which rows they get back, and confusing the two is the most expensive mistake available here.

• For this use case: PCMCS application and POV access; model and rule-set editing is a separate, much narrower entitlement.
• Apply it before aggregation, not after. Filtering a total that has already been computed across entities the user cannot see still leaks the total.
• The NLQ layer needs its own check. Layer 4 already validates that the resolved point of view uses approved members; production adds a second test — that the resolved POV sits inside this user’s scope — and it runs before the data call, not after. A natural-language interface is very good at asking for things politely; the authorization check must not care how the question was phrased.
• Fail closed. If entitlements cannot be resolved, return nothing and say so. An empty result is a support ticket; a permissive default is an incident.

9.6 · Provisioning, sessions and the leaver problem

• SCIM provisioning from Entra or Okta into the EPM Cloud identity domain (OCI IAM, formerly IDCS), covering joiner, mover and leaver. The mover is the case people forget — somebody changing region should lose the old scope, not accumulate both.
• No local user store. If this application keeps its own copy of who may do what, a leaver keeps access until somebody remembers to update it. Nobody ever does.
• Short-lived access tokens with refresh-token rotation; align session timeout with the data classification rather than with convenience.
• MFA and Conditional Access at the IdP — not reimplemented here. Device compliance and location policy come free with federation.
• Quarterly recertification of both the groups that grant access and the service account’s own entitlements, evidenced and signed.
• Break-glass access is a named, monitored, time-boxed account — never a shared credential in a password manager.

9.7 · What this means for Allocation Waterfall

9.8 · Security configuration checklist

• ✓Oracle EPM Cloud federated with the corporate IdP over SAML 2.0 or OIDC; the cookie gate removed entirely
• ✓Browser app uses OIDC Authorization Code + PKCE — no implicit flow, no password grant
• ✓MFA and Conditional Access enforced at the IdP, not reimplemented in the application
• ✓Roles granted to directory groups, never to individuals; SCIM covers joiner, mover and leaver
• ✓Enforcement pattern chosen deliberately — Pattern A where the API supports it, or Pattern B with filtering centralised and tested
• ✓Data-level security applied before aggregation, and the resolved POV checked against the user’s scope before the data call
• ✓No local user table and no local role table anywhere in the application
• ✓Every query logged against the real end user, even when a service account makes the call
• ✓Authorization failures fail closed and are logged as security events rather than swallowed
• ✓Quarterly recertification of access groups and of the service account’s own entitlements

From demo to a governed enterprise deployment

Everything above runs on synthetic data, a public LLM API key, a cookie gate, and no audit trail — deliberately, so the mechanics are inspectable. Taking Allocation Waterfall to production is not a rewrite; the 4-layer pipeline and the data-layer contract survive intact. It is a controlled-change program across six workstreams: architecture, LLM platform, security, SOX/audit, environment promotion, and operations. This section is the checklist we run with clients.

10.1 · Production reference architecture

10.2 · Choosing the LLM platform

The demo’s DeepSeek call is a placeholder for a single adapter, callLLM(system, user), behind Layer 3. Swapping the provider changes one function and zero business logic. Pick the platform the organisation already governs — the security and procurement review is the long pole, not the integration.

Put a model gateway in front of whichever you choose (Azure API Management, OCI API Gateway, Kong AI Gateway, LiteLLM, or Portkey): it owns key custody, per-team spend caps, routing and fallback between models, prompt/response logging, and lets you retire a deprecated model without touching the application.

10.3 · Security controls

10.4 · SOX, audit, and model-risk controls

A read-only NLQ layer does not change a financial-reporting control, but it is an interface to a SOX-relevant system and lands squarely in ITGC scope. Treat prompts, schemas, and eval sets as code — that single decision satisfies most of what an auditor will ask for.

10.5 · Dev → Test → Prod promotion

• Promoted artifacts: application build, prompt templates (versioned), approved-member schema snapshot, eval set, infrastructure config (IaC) — all from the same Git tag.
• Pipeline: branch → PR review → CI (tests + evals) → deploy to Test → UAT sign-off → CAB → deploy to Prod → smoke test. Hosting can stay on Cloudflare Pages/Workers or move to OCI Functions + API Gateway or the org’s standard platform — the code does not care.
• Configuration: per-environment secrets and endpoints injected at deploy; the same build runs in every environment.
• Metadata sync: a scheduled job refreshes dimension metadata into Layer 2 grounding with change detection, so a new entity or account appears in the approved lists without a code release.
• Rollback: previous build and previous prompt version retained; rollback is a redeploy, and because prompts are versioned it also reverts a prompt regression.

10.6 · Operating it

• SLOs: p95 latency, availability of the read path (the deterministic fallback keeps it alive when the LLM is down — already built), fallback rate as a quality signal, eval pass rate per release.
• Cost governance: per-user and per-team token budgets at the gateway; alert on anomalies; the unit-cost model earlier in this kit is the baseline.
• Model lifecycle: providers retire models on a schedule — re-run the eval suite on the successor before switching, and record the switch as a change.
• Incident runbook: LLM outage → fallback parser; EPM API outage → cached metadata with a stale banner; guardrail spike → review logs for injection attempts.

10.7 · What changes for Allocation Waterfall

10.8 · Production readiness checklist

• ✓LLM platform selected from the governed list, DPA / zero-retention terms on file, gateway in front of it
• ✓SSO integrated; authorisation derived from EPM security groups; cookie gate removed
• ✓Read-only EPM service account per pod, credential in a vault, rotation scheduled
• ✓Prompts, schema, and eval set version-controlled and under change management
• ✓Append-only audit log wired to the SIEM with the agreed retention
• ✓Golden-query eval suite passing in CI; results archived as release evidence
• ✓Dev / Test / Prod pipeline with gates, IaC, and a rehearsed rollback
• ✓Model-risk register entry and owner named; first re-validation date set
• ✓Metadata refresh job scheduled with change detection
• ✓SLOs, cost caps, and the incident runbook agreed with platform operations