diff --git a/README.md b/README.md index 27be303..660082c 100644 --- a/README.md +++ b/README.md @@ -17,3 +17,5 @@ How to run locally: - Review README for project goals and architecture details. This is a minimal, production-oriented MVP designed to be extended by follow-up iterations. + +Documentation: See docs/CRISISPULSE_MVP_SPEC.md for a concrete MVP blueprint focused on a two-adapter (solar and water) setup and offline delta-sync workflows. diff --git a/docs/CRISISPULSE_MVP_SPEC.md b/docs/CRISISPULSE_MVP_SPEC.md new file mode 100644 index 0000000..0051ae2 --- /dev/null +++ b/docs/CRISISPULSE_MVP_SPEC.md @@ -0,0 +1,51 @@ +# CrisisPulse MVP: two-adapter blueprint + +Overview +- CrisisPulse is a federated resource orchestration platform for disaster-relief camp networks. This document sketches a production-ready MVP focusing on two adapters (solar microgrid and water purification) and a canonical, offline-first delta-sync workflow. + + MVP Roadmap (6–8 weeks) +- Phase 0: Core local ledger + delta-sync across 2 camps; implement Merkle proofs for a subset of resource entries. +- Phase 1: Graph-of-Contracts registry and governance ledger scaffolding; one cross-domain anchoring example. +- Phase 2: Two domain adapters (solar microgrid, water purification) and two relief partners; demonstrate a joint objective (minimize unmet demand while respecting safety and perishability). +- Phase 3: HIL validation with a mock camp and field exercise; metrics on latency, data footprint of proofs, and relief delivery quality. + +Toy two-adapter MVP spec +- Adapters + - SolarMicrogridAdapter + • Exposes LocalResourcePlan (allocation plan for energy) and SharedForecast (demand projection) + • API surface (illustrative): + - connect() -> bool + - get_output_estimate() -> dict + - report_allocation(plan_delta) -> dict + - WaterPurifierAdapter + • Exposes LocalResourcePlan (water treatment capacity) and production metrics + • API surface (illustrative): + - connect() -> bool + - get_production_plan() -> dict + - report_allocation(plan_delta) -> dict + +Note: In the MVP, adapters communicate via TLS mutual authentication and produce/consume deltas with lightweight cryptographic tagging. The local ledger maintains a delta history, while the governance ledger signs policy changes. + +Contracts and data model (sketch) +- LocalResourcePlan: per-domain allocation plan (e.g., energy, water, food). +- SharedForecast: cross-domain demand/supply projections. +- PlanDelta: incremental allocation changes with cryptographic tags. +- AuditLog: tamper-evident record of changes. +- PrivacyBudget: per-entry privacy budgets for privacy-preserving aggregation. + +Offline-first delta-sync +- Nodes operate fully offline; when connectivity returns, deterministic reconciliation occurs using Merkle roots and PlanDelta proofs. +- Data pruning and archival strategies ensure storage remains bounded in real-world deployments. + +Governance and privacy +- GovernanceLog: cryptographically signed events; anchored to a mission/event ID for trusted provenance. +- SimplePrivacyAggregator: secure aggregation with per-entry budgets and DP-ready placeholders. + +Next steps (what I can implement next) +- Draft toy contracts: LocalResourcePlan, SharedForecast, PlanDelta (structure + signatures). +- Implement a small demo script showing two adapters exchanging deltas and updating the LocalLedger. +- Wire a CrisisPolicy DSL fragment to validate plan deltas against basic constraints. + +This document is intentionally lightweight and designed to be extended into a full-blown SDK. + + (End of document)