KMPCharts/.paul/ROADMAP.md

Roadmap: chart-realtime

Overview

Build a standalone KMP real-time chart module from scaffold to polished publishable library. Six phases: module setup → core data structures → state API → rendering engine → demo validation → polish. Phases 2+3 parallelizable; Phase 4 is the critical path.

Current Milestone

v0.1.0 — MVP Status: Not started
Phases: 0 of 6 complete

Phases

Phase	Name	Plans	Status	Completed
1	Module Scaffold	2	Not started	-
2	Buffer + LoD	2	Not started	-
3	State API	2	Not started	-
4	Render Engine	3	Not started	-
5	Demo App	1	Not started	-
6	Polish + Docs	2	Not started	-

Phase Details

Phase 1: Module Scaffold

Goal: Buildable KMP module structure + Gradle config ready for code Depends on: Nothing Research: Unlikely (standard KMP module setup)

Scope:

• KMP module :chart-realtime with commonMain / androidMain
• Version catalog entries (Compose, coroutines, kotlin.test)
• Demo app module :app depending on :chart-realtime
• Empty placeholder classes to confirm build passes

Plans:

• 01-01: KMP module + Gradle + version catalog
• 01-02: Demo app module + dependency wiring

Phase 2: Buffer + LoD

Goal: Core data structures fully tested — CircularBuffer and LodDecimator Depends on: Phase 1 (module builds) Research: Unlikely (known algorithms)

Scope:

• CircularBuffer — pre-allocated FloatArray[timestamp, value], lock-free write, indexed read
• LodDecimator — min/max envelope per pixel column, O(n) single pass
• Unit tests for both (edge cases: empty, full, wrap-around, single point, fewer pts than pixels)

Plans:

• 02-01: CircularBuffer implementation + tests
• 02-02: LodDecimator implementation + tests

Phase 3: State API

Goal: Public API surface complete — RealtimeChartState usable by consumers Depends on: Phase 2 (CircularBuffer ready) Research: Unlikely

Scope:

• ChartConfig data class (xWindowSeconds, yRange, t0, targetFps, maxBufferSeconds)
• SignalConfig data class (name, color, strokeWidth, visible)
• YRange sealed class (Auto, Fixed)
• T0 sealed class (FirstSample, Fixed)
• RealtimeChartState — holds N CircularBuffers, addSignal/removeSignal, push(), collectFrom()

Plans:

• 03-01: Config models + sealed classes
• 03-02: RealtimeChartState + Flow collector

Phase 4: Render Engine

Goal: Chart renders correctly at 200Hz with stable axes and smooth frame rate Depends on: Phase 2 (LoD) + Phase 3 (State) Research: Unlikely (Canvas API known)

Scope:

• RenderLoop — withFrameNanos, targetFps throttle, reads state snapshot
• AxisRenderer — X/Y gridlines, tick interval math, labels (DrawScope)
• SignalRenderer — FloatArray path build from LodDecimator output, drawLines
• RealtimeChart() composable — assembles all renderers, exposes ChartConfig + RealtimeChartState

Plans:

• 04-01: RenderLoop + AxisRenderer
• 04-02: SignalRenderer + path building
• 04-03: RealtimeChart composable integration

Phase 5: Demo App

Goal: Running Android app proves 200Hz+ with 5+ signals without frame drops Depends on: Phase 4 (rendering complete) Research: Unlikely

Scope:

• Simulated sensor data source (coroutine emitting at 200Hz)
• 5 signals with distinct colors on single chart
• ChartConfig controls: xWindow, yRange mode, signal toggle
• Verify ≥55fps sustained via Android Studio profiler

Plans:

• 05-01: Demo app with 5-signal 200Hz simulation

Phase 6: Polish + Docs

Goal: Publishable library with Material3 theming and minimal API docs Depends on: Phase 5 (demo validated) Research: Unlikely

Scope:

• Material3 default colors/typography for axis labels
• ChartTheme override support
• KDoc on all public API surface
• README with usage example (3-line integration)
• Maven local publish config

Plans:

• 06-01: Material3 theming + ChartTheme
• 06-02: KDoc + README + publish config

---

Roadmap created: 2026-05-20