OrcaArch

Orchestrated Reconciliation & Control Architecture

English · Português

OrcaArch is an open-source, runnable reference implementation of financial infrastructure and post-trade controls, built in Go. It demonstrates reconciliation, positions, PnL, double-entry ledger controls, correction reprocessing, and operational reporting in a deterministic, in-memory environment.

It is a portfolio and learning system, not a managed service or production trading platform.

Financial problem

Post-trade operations must compare internal trades with broker executions, identify breaks, isolate exceptions, maintain positions, calculate PnL, and preserve accounting control when corrections arrive.

OrcaArch makes that control flow executable and inspectable without a database, external broker, or market-data integration.

Financial pipeline

The financial scenario runs a deterministic three-day workflow:

1. Match internal trades against broker executions through three reconciliation tiers.
2. Classify exact matches, tolerance matches, discrepancies, review candidates, duplicates, and unmatched records.
3. Exclude unresolved results from positions, PnL, and ledger updates.
4. Calculate positions, weighted average cost, realized PnL, and unrealized PnL using scenario-provided mark prices.
5. Generate append-only double-entry ledger entries and daily balance controls.
6. Produce summary and detail reports through CSV and a read-only HTTP API.

See Scenarios for statuses and operational contracts.

Correction and reprocessing demo

make correction-demo

The interactive demo applies a supported price correction to an InternalTrade:

1. Select a trade and provide a new price within the demo tolerance.
2. Recalculate the affected instrument scope.
3. Append reversals for prior ledger entries.
4. Append versioned replacement entries.
5. Verify that the ledger remains balanced.
6. Produce a reprocessing audit output.

Generated files:

output/correction_demo/README.md
output/correction_demo/before_ledger.csv
output/correction_demo/after_ledger.csv
output/correction_demo/reprocessing_audit.csv
output/correction_demo/summary.csv

Financial reprocessing is append-only and versioned. The current in-memory implementation does not deduplicate resubmission of the same correction batch.

Run it

Requirements: Go 1.22+.

git clone https://github.com/GRhama/orcaarch.git
cd orcaarch

go test ./...
go test -race ./...
make financial-export-csv MODE=small
make financial-run-api MODE=small

Use small mode for the reviewer path. volume mode exists for performance evidence but is not the default demo path.

Optional scaffold installer

Node 16+ users can generate a lightweight scaffold:

npx create-orcaarch
# or: npm create orcaarch

Then run make help, make reports, or make correction-demo inside the generated project. The scaffold downloads the OrcaArch source engine when an operational command first runs.

API and reports

Start the financial API:

make financial-run-api MODE=small

This command starts the server on :8081 and remains running; use a second terminal to query endpoints.

Summary endpoints:

GET /api/v1/financial/reports/daily_summary
GET /api/v1/financial/reports/instrument_summary
GET /api/v1/financial/reports/exception_summary
GET /api/v1/financial/reports/pnl_summary
GET /api/v1/financial/reports/ledger_control_summary

Detail endpoints:

GET /api/v1/financial/details/reconciliation
GET /api/v1/financial/details/positions
GET /api/v1/financial/details/realized_pnl
GET /api/v1/financial/details/unrealized_pnl
GET /api/v1/financial/details/ledger
GET /api/v1/financial/details/exceptions
GET /api/v1/financial/details/reprocessing_audit

make financial-export-csv MODE=small writes the same five summaries and seven detail reports under output/, with output/README.md as the reading guide.

Technical evidence

• Go domain model with no infrastructure dependency.
• Fixed-point Money stored as int64 at scale ×10000; no float32 or float64 for monetary calculations.
• Deterministic financial scenarios and mock mark prices.
• Append-only ledger reversals and versioned replacement entries.
• Daily debit/credit balance controls.
• Unit, integration, race, volume-smoke, and benchmark coverage.
• Standard-library read-only HTTP API.
• In-memory execution with no database or authentication.

Run benchmarks:

go test ./... -run '^$' -bench=. -benchmem

See Financial Volume Benchmark and Financial Reconciliation pprof for recorded evidence and limits.

Secondary scenario: logistics

OrcaArch also includes an implemented logistics reconciliation scenario: ERP shipments versus carrier invoices, landed cost, weighted average cost, ledger entries, quarantine, and correction reprocessing.

This secondary scenario shows that the reconciliation and control pattern can be reused with domain-specific rules. It remains runnable through make run-api and make export-csv.

Documentation

• Architecture
• Scenarios
• API First
• Product Case
• Benchmarks
• Historical Financial Scenario Design
• AI Workflow

---

OrcaArch PT-BR

OrcaArch é uma implementação de referência open-source e executável de infraestrutura financeira e controles de pós-negociação, construída em Go. Demonstra reconciliação, posições, PnL, ledger de partida dobrada, reprocessamento de correções e relatórios operacionais em ambiente determinístico e in-memory.

É um sistema de portfólio e aprendizado, não um serviço gerenciado nem uma plataforma de trading para produção.

Problema financeiro

O cenário financeiro compara trades internos com execuções de broker usando três níveis de matching. Resultados não resolvidos seguem para exceptions e não alimentam posições, PnL ou ledger.

O pipeline calcula posições, custo médio ponderado, PnL realizado e não realizado com mark prices fornecidos pelo cenário. Também gera ledger, controles de balanceamento, relatórios CSV e API HTTP somente-leitura.

Demo de correção

make correction-demo

A demo corrige o preço suportado de um InternalTrade, reprocessa o escopo afetado e gera reversões append-only, lançamentos substitutos versionados e saída de auditoria.

O fluxo financeiro atual não garante deduplicação da reapresentação do mesmo lote de correção.

Como rodar

git clone https://github.com/GRhama/orcaarch.git
cd orcaarch

go test ./...
go test -race ./...
make financial-export-csv MODE=small
make financial-run-api MODE=small

Esse comando inicia o servidor em :8081 e permanece em execução; use outro terminal para consultar os endpoints.

Use small como caminho padrão de demonstração. O modo volume existe para evidência de desempenho, mas não é o caminho recomendado para review.

Instalação opcional por scaffold:

npx create-orcaarch

Evidência técnica

• Money fixed-point em int64, escala ×10000, sem floats para cálculos monetários.
• Cenários mock determinísticos e mark prices fornecidos pelo cenário.
• Reconciliação financeira em três tiers e oito statuses.
• Posições, custo médio, PnL realizado e não realizado.
• Reversões append-only, versionamento e controles de balanceamento do ledger.
• Relatórios CSV, API somente-leitura, testes, race tests e benchmarks.
• Execução in-memory, sem banco de dados e sem autenticação.

Cenário secundário: logística

O cenário logístico continua implementado e executável. Ele demonstra reutilização do padrão de reconciliação e controle com regras específicas de outro domínio.

Consulte Scenarios, Architecture e Product Case para detalhes.