idea78-solarsphere-offline-first/AGENTS.md

SolarSphere Offline-First MVP Agents

This repository contains a production-oriented Python MVP for SolarSphere, an offline-first geospatial visualization scaffold. The code focuses on data contracts, a pluggable data-source adapter surface, deterministic delta reconciliation, and a lightweight render summary suitable for testing and extension.

Architecture overview

• Core data primitives: Asset, TelemetryPoint, WeatherLayer, Event.
• Data sources: pluggable adapters (CSV, REST, MQTT, etc.). CSVAdapter is implemented for MVP.
• Delta reconciliation: deterministic, replay-friendly merge of local and remote deltas.
• Lightweight renderer: builds a serializable snapshot suitable for downstream visualization without a browser runtime.
• Packaging: Python package under idea78_solarsphere_offline_first with a small, exportable API.

Tech stack decisions

• Language: Python 3.9+ for rapid prototyping, strong typing, and easy packaging.
• No external GUI dependencies yet; a JSON-friendly render path is provided to support future WebGL/Canvas rendering layers.
• Tests: pytest-based unit tests ensure data models, adapters, and delta logic behave deterministically.

Testing and commands

• Run tests locally: ./test.sh
• Build package: python3 -m build
• Inspect package: pytest tests -q

Contributing rules

• Add small, well-scoped changes; prefer minimal surface area.
• Update AGENTS.md if you add new architecture or data contracts.
• Ensure tests cover new behavior.