[augustinemartins]

Summary

Resolves three issues with one commit each:

Commit	Issue
feat(split): contract usage analytics	Closes #1034
feat(split): contract monitoring and alerting	Closes #1033
docs: contract architecture and design decisions	Closes #1032

---

#1034: Contract usage analytics (contracts/split/src/analytics.rs)

Requirement	Implementation
Design analytics system	On-chain aggregates, so dashboards read current usage in one call. See docs/ISSUE_1034_USAGE_ANALYTICS.md and ADR 0003.
Event tracking	analytics::record is called from the lifecycle event helpers in events.rs (created, paid, released, refunded). Every path that emits those events is counted, with no per-call-site changes.
Aggregation	Lifetime UsageTotals (instance) and one DailyUsage bucket per UTC day (persistent), plus unique creator/payer counts.
Reporting	get_usage_report(from_day, to_day), up to 90 days, empty days included.
Dashboards	get_usage_dashboard(): totals, today and insights in one read.
Insights	get_usage_insights(): average payment and invoice size, payments per invoice, release and refund rates, week-over-week payment trend, busiest day.

Recording never emits events and counters saturate, so the event stream is unchanged and analytics can never revert a payment. Admins can switch recording off with set_analytics_enabled.

#1033: Monitoring and alerting (contracts/split/src/monitoring.rs)

Requirement	Implementation
Design monitoring system	Alert rules evaluated against analytics metrics. See docs/ISSUE_1033_MONITORING_ALERTING.md and ADR 0005.
Metric collection	MetricKind: today's invoices, payments, payment volume, refunds and refund volume; lifetime refund rate; current payment amount. get_metrics() returns a snapshot.
Alerting rules	Up to 20 admin-managed AlertRules: metric, Above/Below, threshold, severity, cooldown, enabled.
Dashboards	get_monitoring_dashboard(): stats, rules, metrics, 10 most recent alerts, receiver.
Alert delivery	Stored alert (newest 50 kept), a (split, alert, rule_id) event, and an optional receiver contract's on_alert(alert) via try_invoke_contract. A failing receiver never reverts the triggering operation.
Monitoring analytics	MonitoringStats: evaluations, alerts by severity, unacknowledged, failed deliveries, last alert time.

Rules run automatically after each usage event (only those for affected metrics). check_alerts() is open to anyone, so keepers can catch conditions no event triggers, such as "no payments today". With no rules registered, the payment path pays one instance read.

#1032: Architecture documentation

• Rewrote docs/ARCHITECTURE.md: crate map, split layering and module map, storage model, state flows, cross-cutting concerns, design decisions and references.
• Mermaid diagrams: system context, module layering, invoice record layout, invoice status state machine (matches valid_transition), payment/release and refund sequences, alert lifecycle.
• Fixed stale content: the directory layout, lib.rs size, the broken EVENTS.md link, and the refund flow.
• New ADRs 0002–0005, indexed in docs/adr/README.md.
• New storage keys documented in STORAGE_KEY_REGISTRY.md.

---

Testing

The split crate does not compile on main. There are 53 existing errors from earlier merges (for example missing ContractError variants, StorageTier, ShardError, and the undeclared webhooks module), so cargo test -p split cannot run on any branch right now.

What I ran:

• No new compiler errors: cargo check -p split --lib --tests produces exactly the same errors on main and on each commit, and no warnings in the new code beyond the existing deprecated-publish warning.
• Logic tests: compiled the real analytics.rs and monitoring.rs in a standalone harness with soroban-sdk 28 testutils. 7 tests passed, covering totals and unique counts, daily buckets, reports and bounds, the week-over-week trend, enable/disable, rule CRUD and limits, firing on usage, cooldown, check_alerts for Below rules, acknowledgement, delivery to a working and a failing receiver, and history pruning. These tests found and fixed an overflow in get_usage_report at u64::MAX.
• Contract-level tests: added as test_1034_* and test_1033_* in contracts/split/src/test.rs. They type-check, and will run once main builds again.

Notes

• Hooking analytics into the event helpers adds about two storage writes per tracked event. This may show up in compute-budget baselines once the crate builds again.
• Cargo.lock on main is missing the charity-split member, so cargo rewrites it locally. That change is not included in this PR.

🤖 Generated with Claude Code