Skip to content

Multi-currency: documentation and rollout readiness - #59

Open
ItsThompson wants to merge 8 commits into
mc/06-prorata-future-applicationfrom
mc/07-docs-and-rollout
Open

Multi-currency: documentation and rollout readiness#59
ItsThompson wants to merge 8 commits into
mc/06-prorata-future-applicationfrom
mc/07-docs-and-rollout

Conversation

@ItsThompson

@ItsThompson ItsThompson commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Summary

Updated project documentation so it describes the shipped multi-currency model instead of the previous single-currency design. All docs now name the FX Service and its internal gRPC boundaries, period reporting currency, expense money snapshots, the startup backfill, pro-rata captured snapshots, the enriched export schema, FX configuration, FX metrics and alert thresholds, and the legacy currency alias removal.

What changed

Documentation

  • docs/architecture.md: added FX Service to the node topology, dependency edges, service responsibilities, network-isolation table, and design decisions. Updated expense, finance, and datarights responsibilities and the expense/pro-rata data-flow sequence diagrams. Stated that the gateway has no /api/fx prefix.
  • docs/data-model.md: added the multi-currency model overview, period reporting_currency with future-scoped default settings, expense money snapshots and the startup backfill, pro-rata captured snapshots with failure reasons, the shared currency catalog, and historical migration semantics. Added FX Service to the database ownership table.
  • docs/api.md: added the Multi-Currency Fields and Compatibility section: reporting and transaction currency, the legacy currency alias removal, period context behavior, correction currency behavior, pro-rata period fields, and FX error responses. Updated the expenses/finance endpoint sections and the error-category table.
  • docs/data-export.md: replaced legacy expense and period columns with the shipped transaction/reporting snapshot columns. Added reporting_currency to budget_periods.csv and currency precision formatting rules. Updated formatting helpers to formatMinorUnits.
  • docs/monitoring.md: added the FX Service metrics table, export_currency_formatting_fallback_total, and an FX/multi-currency alert-context section with wired-vs-defined status.
  • docs/development.md: added FX Service to key variable groups.

Configuration

  • .env.example: added OPEN_EXCHANGE_RATES_APP_ID, FX_PROVIDER_TIMEOUT, FX_PROVIDER_RETRY_COUNT, FX_CACHE_MAX_AGE, and FX_SERVICE_ADDR without real secrets.
  • docker-compose.yml: added a comment above fx-service identifying it as an internal-only compute service with no browser route and no gateway prefix.
  • docker-compose.dev.yml: added an internal-only pointer comment referencing the main compose file.

Tests

  • docker compose config --quiet: compose configuration validated.
  • just test-monitoring: all three prometheus rule files valid, both promtool rule tests passed.
  • git diff --check: clean, no whitespace errors.
  • No Go or frontend code changed; backend and frontend test suites are unaffected.

Notes

  • FX alert thresholds are documented as "defined, not wired" rather than implemented as rules. Only ServiceDown is active today for fx-service (inherited via its scrape target).
  • FX_SERVICE_ADDR is documented in .env.example but remains hardcoded in docker-compose.yml, matching the existing convention for all service addresses.

References

@ItsThompson ItsThompson changed the title mc/07 docs and rollout Multi-currency: documentation and rollout readiness Aug 15, 2026
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 6f9bcb4 to 5fbc53c Compare August 15, 2026 22:49
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch 3 times, most recently from 197a23c to 993c0f9 Compare August 15, 2026 23:22
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch 2 times, most recently from 14f3a78 to 9b5c9de Compare August 15, 2026 23:53
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 9b5c9de to bf66863 Compare August 16, 2026 14:53
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from bf66863 to 7a57fae Compare August 16, 2026 15:17
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 7a57fae to 870d7e4 Compare August 16, 2026 15:45
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch 2 times, most recently from 5ca47db to d40a819 Compare August 18, 2026 23:36
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from d40a819 to 24102a4 Compare August 18, 2026 23:45
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 24102a4 to 012ff51 Compare August 18, 2026 23:51
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 012ff51 to 2616899 Compare August 19, 2026 06:30
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 2616899 to 1d3eb44 Compare August 19, 2026 19:05
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 1d3eb44 to 01541f4 Compare August 20, 2026 13:48
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 01541f4 to 816085f Compare August 20, 2026 14:58
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 816085f to 7647a69 Compare August 20, 2026 15:10
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 7647a69 to 484d957 Compare August 20, 2026 16:05
@ItsThompson
ItsThompson force-pushed the mc/07-docs-and-rollout branch from 484d957 to aa95dbb Compare August 20, 2026 17:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant