Case study /08 · Shipped · maintained
CarbonMarketsHQ
Context
Traders, project developers and analysts need one place where portfolio values, market prices and transaction records are consistent. Spreadsheets were the incumbent, with all the silent-error risk that implies.
Problem
Valuations combined market data of varying freshness with foreign-exchange rates and unit conversions. Any inconsistency — a stale rate, a double conversion, an ambiguous vintage — surfaces as a wrong number that someone might trade on.
Constraints
- Financial data correctness was non-negotiable; silent failure modes had to be designed out.
- External data sources delivered on their own schedules and formats, not ours.
- The platform was live: changes shipped into a system with active users and standing data.
- Multi-currency support had to be exact about when and how conversion happened.
Responsibilities
- Frontend features in React and Next.js, from data-dense tables to valuation views.
- Python services for valuation computation and data ingestion.
- Foreign-exchange conversion layer with explicit rate provenance.
- API design for portfolio, pricing and transaction resources.
- Transaction workflow implementation and state modeling.
- Integration with registry data and tokenized carbon-credit infrastructure in the Hedera Guardian ecosystem.
- Ongoing production maintenance, debugging and hardening.
Architecture
- A Next.js frontend consumes typed APIs backed by Python services and PostgreSQL.
- Valuations are computed server-side from versioned inputs — price, FX rate and quantity each carry their source and timestamp.
- FX conversion is centralized in one service path; nothing else in the codebase is allowed to multiply by a rate.
- Transactions move through an explicit state machine so operational workflows are auditable step by step.
- An integration layer reconciles platform records against registry and tokenized-credit state, so off-chain valuations and on-chain holdings can never silently disagree.
Key decisions
- Store money as exact decimals with currency codes end-to-end; floats never touch financial values.
- Record the FX rate used on every valuation row instead of recomputing historically — auditability beat storage cost.
- Prefer boring, observable batch ingestion over streaming for market data whose sources update daily anyway.
- Type the API boundary strictly so frontend and backend disagreements fail in CI, not in production.
Implementation
- Valuation endpoints compose price resolution, FX conversion and quantity math in one audited code path with structured logging.
- Ingestion jobs validate and normalize external market data before it can enter pricing tables.
- Data-dense frontend views use server-driven pagination and column-level formatting rules per unit and currency.
- Workflow transitions emit events consumed by notifications and audit views.
Performance
- Portfolio views aggregate in SQL close to the data rather than in application memory.
- Hot pricing lookups are indexed by instrument and date, keeping valuation queries flat as history grows.
- Frontend tables virtualize long result sets to keep interaction latency low.
Outcomes
- Valuation and FX logic became a single trusted code path with full provenance.
- Operational teams run transaction workflows in the platform instead of spreadsheets.
- The system has remained maintainable through sustained feature development in production.
- [PLACEHOLDER — add real volume/value figures here if the client approves publication.]
Lessons
- In financial software, provenance is a feature: every number should be able to explain itself.
- Centralizing dangerous operations (like FX conversion) is worth more than any code-review checklist.
- Production maintenance is product work — reliability compounds into user trust.
Software Architecture
