# Accounting Run

The accounting run is the core royalty calculation process in Abacus. It matches sales transactions to contracts, applies term rates, converts currencies, and commits results to account ledgers.

## I want to...

### Understand the accounting run

- [Read the end-to-end flow](end-to-end.md) — what happens, in what order, by whom, in which systems, and what depends on what. **Start here.**
- [Look up a domain term](glossary.md) — one-line definitions (statement period, run controller, activity_rate, etc.)
- [Understand the entity model and data sources](architecture/overview.md) — hierarchy, contract types, Snowflake/MySQL table catalog
- [Understand the calculation pipeline](architecture/calculation.md) — contract snapshots, JSON flattening, transaction matching, formulas
- [Understand the approval and commit process](architecture/approval-and-commit.md) — staging-to-main promotion, ledger commits, reserves

### Run an accounting run

- [Follow the Abacus run guide](runbooks/run-guide.md) — step-by-step: Jenkins jobs, Abacus UI clicks, useful queries
- [Follow the legacy workflow](runbooks/legacy-workflow.md) — Docker, ActiveMQ, PHP scripts, Aurora MySQL
- [Follow the publishing sales process](runbooks/publishing-sales.md) — quarterly, manual, cross-team, Snowflake-based

### Fix something (on-call)

- [Triage an alert](runbooks/troubleshooting.md#triage) — decision tree: "I got paged, now what?"
- [Find the right dashboard](runbooks/monitoring.md) — what to watch during each phase of a run
- [Diagnose a failure](runbooks/troubleshooting.md) — common scenarios with symptom/cause/diagnosis/recovery
- [Escalate](runbooks/) — escalation path, PagerDuty, Slack channels, key bookmarks
- [Refresh a QA/dev/UAT environment](runbooks/environment-refresh.md)

### Learn about improvement efforts

- [Read the system design review](improvements/system-design-review.md) — architecture evaluation, failure modes, recommendations
- [Understand the calculation timeout issue](improvements/calculation-timeout.md) — root cause, estimation query, fixes
- [Understand the DBT refresh automation](improvements/dbt-refresh-automation.md) — WAR-2815, remaining gaps
- [See open Jira epics](improvements/open-epics.md) — ACC-10109, ACC-10203, future improvement areas

## Key Repositories

| Repository | Description |
|------------|-------------|
| [`ows-royalties-workflows`](https://github.com/theorchard/ows-royalties-workflows) | Airflow DAGs for accounting run calculation and commit |
| [`ows-accounting`](https://github.com/theorchard/ows-accounting) | Accounting service — **decommissioned** under [ACC-10631](https://theorchard.atlassian.net/browse/ACC-10631) (see [decommission tracking doc](../technical-projects/ows-accounting-decommission/README.md)) |
| [`ows-royalties`](https://github.com/theorchard/ows-royalties) | Royalties service — contract/run metadata, status updates, API for DAG tasks |
| [`ows-moneyhub`](https://github.com/theorchard/ows-moneyhub) | Customer Accounting backend (FastAPI) — statements, revenue analysis, attachments |
| [`lambda-abacus`](https://github.com/theorchard/lambda-abacus) | Lambda functions (commit_royalties, reserves_take, reserves_schedule, reserves_release, ledger_accounting_run_balance) |
| [`dbt-accounting`](https://github.com/theorchard/dbt-accounting) | DBT models for accounting data (unified tables, revenue models) |
| [`python-accounting-run-utils`](https://github.com/theorchard/python-accounting-run-utils) | Legacy data load/unload scripts (S3 <-> Aurora MySQL) |
| [`frontend-royalties`](https://github.com/theorchard/frontend-royalties) | Frontend for accounting run UI |

## Notion Sources

- [Accounting Run (Tech)](https://www.notion.so/c9ecc13c18cb4362962ce54853992580) — primary technical reference
- [Accounting Run - Run Guide](https://www.notion.so/20d97177520f80bfaf4ef78308483261) — step-by-step operational guide
- [Accounting Run Workflow](https://www.notion.so/e2f641f40d314a43abd1e0b448e6cf5d) — legacy DevOps workflow
- [Publishing Sales Accounting Run Process](https://www.notion.so/a504bc32c8ab4513bd5136c6ddd16c20) — publishing quarterly process
- [Accounting & Royalties](https://www.notion.so/6bc9dbc46f5b44688cfe9192825f156c) — team page

## Slack Channels

| Channel | Purpose |
|---------|---------|
| `#accounting-run-priv` | Private run coordination (blockers, approvals) |
| `#accounting-calc` | Calculation discussion, data packages |
| `#accounting-tech` | Engineering — environment refreshes, failures |
| `#abacus-x-ca` | Abacus x Customer Accounting cross-team — DBT refresh notifications |
| `#pub-sales-processing` | Publishing sales checksums and coordination |