# CityPulse: Participatory Digital Twin (Open-Source MVP)

CityPulse aims to be a modular, open-source platform for cross-domain urban resource optimization with privacy-preserving, offline-first federated coordination. This MVP scaffold demonstrates core concepts and provides a path toward production-grade integration with adapters, governance, and a lightweight simulator.

What’s included
- Core domain models: LocalProblem, SharedSignals, PlanDelta, DualVariables, AuditLog.
- Delta store with deterministic replay for auditable governance trails.
- Minimal ADMM-lite solver to illustrate federated coordination semantics.
- Starter adapters: DERControllerAdapter and WaterPumpControllerAdapter.
- Lightweight packaging setup (pyproject.toml) and test harness.

How to run
- Run tests and build package: ./test.sh
- The test suite exercises core data structures and adapter bindings.

Packaging and publishing
- The package is named idea171-citypulse-participatory-digital and is provisioned for publishing to PyPI or a private registry.
- A READY_TO_PUBLISH file will be created when the repository state fully matches publishing requirements.

Roadmap (high level)
- Phase 0: Skeleton protocol core + adapters over TLS; end-to-end delta-sync.
- Phase 1: Governance ledger scaffolding and identity layer.
- Phase 2: Cross-domain demo in a simulated district.
- Phase 3: Hardware-in-the-loop validation.

Enjoy contributing and shaping the CityPulse ecosystem.