adaptive-pricing/.claude/rules/architecture.md

Architecture

The repo has two layers:

1. Root framework layer

• INTENT.md, docs/, research/, and registry/ define the generic adaptive-pricing vocabulary, lifecycle model, and roadmap.
• workplans/ is the repo-native source of truth for tracked work (ADR-001).

2. Project implementation layer

• projects/coulomb-pricing/ contains the first concrete deployment: Coulomb Social's Economic Observatory MVP.
• observatory/ is a small Python package that reads JSON ledgers and registries from data/, computes economics snapshots, and serves a local UI.

Current Coulomb data flow:

• data/*.json ledgers and registries
• observatory/load.py parses JSON into dataclasses
• observatory/ledger.py builds monthly cost rows
• observatory/economics.py computes liquidity, margins, and snapshots
• observatory/allocation.py, usage.py, pricing_context.py, simulator.py, credits.py, and recommendations.py derive higher-level pricing views
• observatory/api.py assembles the dashboard payload
• observatory/__main__.py renders the Markdown report
• observatory/server.py exposes /api/dashboard and serves ui/

External integrations are file-based in MVP:

• Bubble export importer
• Stripe export importer
• OpenRouter export importer

The internal model and ledgers are the source of truth. Provider exports feed the ledgers; they do not replace them.

Quick Reference

~/state-hub/mcp_server/TOOLS.md — MCP tool reference