Tasks · 001-portfolio-analytics

Real-time portfolio analytics

Platform-level, cross-cutting work: the scaffold, the shared model, the ledger, the wiring, and the reconcile harness the child slices build on.

Status Draft Spec 001-portfolio-analytics Design design Branch 001-portfolio-analytics Created Read time

Twelve platform tasks across five phases. Setup → Foundational → US1·US2·US3 → Polish. Tasks marked [P] can run in parallel. These are the shared seams every child slice (002–005) depends on; each child's own analytic tasks live in its tasks.html. Tests for a story MUST be written and failing before its implementation starts.

1 · Execution strategy

Land US1 — one trade producing three coherent, reconcilable analytics — end to end, then iterate to snapshot/restore (US2) and the extensibility proof (US3).

Setup → Foundational → US1 → US2 → US3 → Polish, closing each story's conformance before the next opens.

After Foundational, the child slices (002–005) proceed in parallel against the shared model + ledger; coordinate only at the AnalyticsPlatform seam via the spec.

2 · Phase 1 — Setup

Scaffold the Quarkus Maven project — pom.xml with the Quarkus 3.37.3 BOM and the rest, rest-jackson, arc, micrometer-registry-prometheus, and smallrye-openapi extensions pom.xml
Configure the build floor — jacoco coverage report + check, and the ship-dark toggle / metrics / openapi settings pom.xml · src/main/resources/application.properties

3 · Phase 2 — Foundational

The shared seams no analytic slice can ship without. Sequential where order matters.

Author the shared event model — Side, TradeEvent, PriceTick, and the fixed-point money scale (D-002) src/main/java/io/spectastic/portfolio/model/
Build the append-only ledger seam — the TradeLedger interface the projections fold (implementation detailed in spec 002) src/main/java/io/spectastic/portfolio/ledger/
Wire the platform bean — AnalyticsPlatform (@ApplicationScoped) fans each appended event into the three projections src/main/java/io/spectastic/portfolio/AnalyticsPlatform.java

Establishes FR-001 (single source of truth) and FR-002 (incremental fold) at the platform level.

4 · Phase 3a — US1 · One trade, three coherent analytics

Tests (write & fail first)

Reconcile-to-replay test — a seeded trade+tick stream folded incrementally equals a from-zero replay across all three projections src/test/java/io/spectastic/portfolio/ReconcileToReplayTest.java

Implementation

Fan events into the projections — the platform fold updates position, weights, and tax lots on every append src/main/java/io/spectastic/portfolio/AnalyticsPlatform.java
Expose the read surface — AnalyticsResource serving trades/ticks in and positions/weights/realized out, behind the dark toggle src/main/java/io/spectastic/portfolio/api/

Closes FR-002, NFR-002, SC-001.

5 · Phase 3b — US2 · Resume from a checkpoint

Snapshot-equals-replay test — restore at sequence N then replay the tail equals a full replay to M src/test/java/io/spectastic/portfolio/ReconcileToReplayTest.java
Snapshot / restore across projections — deep-copy fold checkpoints wired through the platform src/main/java/io/spectastic/portfolio/AnalyticsPlatform.java

Closes FR-003, NFR-003.

6 · Phase 3c — US3 · Add an analytic without touching the ledger

Tests (write & fail first)

Extensibility test — a fourth trivial projection folds the existing ledger with zero ledger-contract change src/test/java/io/spectastic/portfolio/ReconcileToReplayTest.java

Implementation

Document the projection SPI — the fold contract a new analytic implements src/main/java/io/spectastic/portfolio/AnalyticsPlatform.java

Closes FR-004, SC-002.

7 · Phase 4 — Polish

Instrument the folds — Micrometer timers on each fold step, exposed at /q/metrics (P-15, the SLO instrument) src/main/java/io/spectastic/portfolio/AnalyticsPlatform.java
Publish the contract — OpenAPI at /q/openapi and a README quickstart (P-11) src/main/resources · README.md
Enforce the coverage floor — jacoco diff-aware check wired into mvn verify (P-10) pom.xml

8 · Dependencies

Setup           → Foundational
Foundational    → US1, US2, US3        (and unblocks child slices 002–005)
US1, US2, US3   → Polish

9 · Change log

  1. Initial platform task breakdown: scaffold + build floor (Setup), shared model + ledger seam + wiring bean (Foundational), reconcile-to-replay / snapshot / extensibility stories (US1–US3), and observability + contract + coverage (Polish). Child slices 002–005 carry their own analytic tasks.