docs: create architecture decision records (ADRs)

docs/adr/ADR-001-soroban-platform-choice.md

@@ -0,0 +1,126 @@
+# ADR-001: Choice of Soroban Over Other Smart Contract Platforms
+
+**Status**: Accepted  
+**Date**: 2026-05-29  
+**Author**: Stellar-Save Team  
+**Deciders**: Architecture Team
+
+## Context
+
+Stellar-Save is a decentralized Rotating Savings and Credit Association (ROSCA) platform that requires a smart contract platform to manage group creation, membership, contributions, and automated payouts. The team evaluated multiple blockchain platforms and smart contract ecosystems before selecting Soroban.
+
+### Alternatives Considered
+
+1. **Ethereum (Solidity)**
+   - Mature ecosystem with extensive tooling
+   - Large developer community
+   - High transaction costs ($5-50+ per transaction)
+   - Complex gas optimization required
+   - Slower block times (12-15 seconds)
+
+2. **Polygon (Solidity)**
+   - Lower costs than Ethereum (~$0.01-0.10 per transaction)
+   - EVM-compatible tooling
+   - Still requires significant gas optimization
+   - Centralized validator set
+   - Less focus on financial inclusion
+
+3. **Cosmos (CosmWasm)**
+   - Good for interoperability
+   - Requires running own chain or using existing chains
+   - Smaller ecosystem for financial applications
+   - More operational complexity
+
+4. **Soroban (Rust on Stellar)**
+   - Native to Stellar blockchain
+   - Designed for financial applications
+   - Very low transaction costs (~0.00001 XLM ≈ $0.000001)
+   - Fast finality (3-5 seconds)
+   - Built-in support for Stellar assets (XLM, USDC, etc.)
+   - Strong focus on financial inclusion
+
+## Decision
+
+**We chose Soroban as the smart contract platform for Stellar-Save.**
+
+## Rationale
+
+### 1. **Cost Efficiency**
+- Soroban transactions cost ~0.00001 XLM (~$0.000001 at current prices)
+- Ethereum equivalent: $5-50 per transaction
+- **Impact**: Users in emerging markets can afford frequent transactions
+- **Benefit**: Enables true financial inclusion for unbanked populations
+
+### 2. **Stellar's Financial Focus**
+- Stellar was designed specifically for financial applications
+- Native support for multiple assets (XLM, USDC, EURC, etc.)
+- Built-in payment channels and atomic swaps
+- **Impact**: ROSCA mechanics align naturally with Stellar's design
+- **Benefit**: Simpler contract logic, fewer edge cases
+
+### 3. **Fast Finality**
+- Soroban transactions finalize in 3-5 seconds
+- Ethereum: 12-15 seconds per block, multiple confirmations needed
+- **Impact**: Better user experience with immediate feedback
+- **Benefit**: Faster payout execution and cycle advancement
+
+### 4. **Rust Smart Contracts**
+- Memory-safe language prevents common vulnerabilities
+- Strong type system catches errors at compile time
+- Excellent performance characteristics
+- **Impact**: Reduced security risks compared to Solidity
+- **Benefit**: Safer handling of financial transactions
+
+### 5. **Institutional Knowledge**
+- Stellar Development Foundation provides excellent documentation
+- Growing community of developers building financial applications
+- Active support for Soroban development
+- **Impact**: Easier to find help and best practices
+- **Benefit**: Faster development and fewer blockers
+
+### 6. **Alignment with Mission**
+- Stellar's mission: "Democratize access to financial services"
+- Soroban enables building on Stellar's infrastructure
+- **Impact**: Direct alignment with Stellar-Save's goal of financial inclusion
+- **Benefit**: Potential for ecosystem partnerships and integrations
+
+## Consequences
+
+### Positive
+- ✅ Extremely low transaction costs enable mass adoption
+- ✅ Fast finality improves user experience
+- ✅ Rust provides strong safety guarantees
+- ✅ Natural fit for financial applications
+- ✅ Smaller contract sizes reduce deployment costs
+- ✅ Access to Stellar's asset ecosystem
+
+### Negative
+- ❌ Smaller developer ecosystem compared to Ethereum
+- ❌ Fewer third-party tools and libraries
+- ❌ Less historical data on production deployments
+- ❌ Soroban is relatively new (launched 2023)
+
+### Mitigation
+- Actively contribute to Soroban ecosystem
+- Document patterns and best practices
+- Maintain close relationship with Stellar Development Foundation
+- Build reusable contract libraries for community
+
+## Implementation Notes
+
+- Smart contracts written in Rust using Soroban SDK
+- Contracts deployed to Stellar testnet, futurenet, and mainnet
+- Frontend uses `@stellar/stellar-sdk` for contract interaction
+- Events emitted by contracts are indexed via Horizon API
+
+## Related Decisions
+
+- ADR-002: Sequential payout order default design
+- ADR-003: Backend event indexing approach
+
+## References
+
+- [Soroban Documentation](https://soroban.stellar.org/)
+- [Stellar Development Foundation](https://stellar.org/)
+- [Soroban SDK (Rust)](https://github.com/stellar/rs-soroban-sdk)
+- [Stellar Asset Ecosystem](https://stellar.org/ecosystem/projects)

docs/adr/ADR-002-sequential-payout-order.md

@@ -0,0 +1,164 @@
+# ADR-002: Sequential Payout Order Default Design Decision
+
+**Status**: Accepted  
+**Date**: 2026-05-29  
+**Author**: Stellar-Save Team  
+**Deciders**: Product & Architecture Team
+
+## Context
+
+In a ROSCA, members take turns receiving the full pool of contributions. The order in which members receive payouts is a critical design decision that affects:
+- User expectations and fairness perception
+- Contract complexity and gas costs
+- Flexibility for different use cases
+- Predictability and planning
+
+The team needed to decide on the default payout order mechanism while allowing for future flexibility.
+
+### Alternatives Considered
+
+1. **Sequential Order (Chosen)**
+   - Members receive payouts in the order they joined
+   - Deterministic and predictable
+   - Simple to implement and verify
+   - Gas efficient
+
+2. **Random Order**
+   - Each cycle, a random member is selected
+   - Adds element of chance
+   - More complex randomness implementation
+   - Higher gas costs
+   - Harder to predict and plan
+
+3. **Auction-Based**
+   - Members bid for payout position
+   - Highest bidder receives payout
+   - Maximizes value extraction
+   - Complex contract logic
+   - Potential for gaming and manipulation
+
+4. **Flexible/Configurable**
+   - Group creator chooses order mechanism
+   - Maximum flexibility
+   - Significant complexity
+   - Harder to audit and verify
+   - Potential for unfair configurations
+
+## Decision
+
+**The default payout order is sequential based on join order.**
+
+Members receive payouts in the order they joined the group. This is the default behavior, with potential for configurable alternatives in future versions.
+
+## Rationale
+
+### 1. **Simplicity and Predictability**
+- Members know exactly when they will receive their payout
+- No surprises or randomness
+- Easy to explain to non-technical users
+- **Impact**: Builds trust and confidence in the system
+- **Benefit**: Reduces support burden and user confusion
+
+### 2. **Fairness Perception**
+- "First in, first out" is universally understood
+- Aligns with traditional ROSCA practices in many cultures
+- No perception of favoritism or manipulation
+- **Impact**: Increases adoption in communities
+- **Benefit**: Matches user expectations from offline ROSCAs
+
+### 3. **Gas Efficiency**
+- No randomness oracle needed
+- No complex sorting or selection logic
+- Minimal storage overhead (just track current position)
+- **Impact**: Lower transaction costs
+- **Benefit**: More funds go to members, less to gas fees
+
+### 4. **Auditability**
+- Trivial to verify payout order on-chain
+- Anyone can predict future payouts
+- No hidden logic or complexity
+- **Impact**: Increases transparency
+- **Benefit**: Easier security audits and community verification
+
+### 5. **Alignment with Traditional ROSCAs**
+- Most traditional ROSCAs use sequential order
+- Familiar to target users in Africa and diaspora communities
+- Reduces friction for adoption
+- **Impact**: Faster user onboarding
+- **Benefit**: Leverages existing mental models
+
+### 6. **Contract Simplicity**
+- Reduces attack surface
+- Fewer edge cases to handle
+- Easier to test and verify
+- **Impact**: Fewer bugs and vulnerabilities
+- **Benefit**: Safer handling of user funds
+
+## Consequences
+
+### Positive
+- ✅ Extremely simple to implement and understand
+- ✅ Lowest gas costs of all alternatives
+- ✅ Matches user expectations from traditional ROSCAs
+- ✅ Trivial to audit and verify
+- ✅ No randomness oracle dependencies
+- ✅ Predictable payout timing enables planning
+
+### Negative
+- ❌ No flexibility for different use cases
+- ❌ Early joiners always get paid first (potential fairness concern)
+- ❌ No mechanism to reward active members or penalize inactive ones
+- ❌ Cannot accommodate "priority" members
+
+### Mitigation
+- Document the sequential order clearly in UI
+- Allow group creators to set custom join order in future versions
+- Implement optional "random order" mode in v2.0
+- Provide tools for groups to manually adjust order if needed
+
+## Implementation Details
+
+### Storage
+```rust
+// Track current payout position
+payout_position: {group_id} → u32
+
+// Track member join order
+member_join_order: {group_id} → Vec<Address>
+```
+
+### Payout Logic
+```rust
+fn get_next_payout_recipient(group_id: u64) -> Address {
+    let position = storage.get(payout_position_key(group_id))?;
+    let members = storage.get(member_join_order_key(group_id))?;
+    members[position % members.len()]
+}
+```
+
+### Cycle Advancement
+After each payout, increment position:
+```rust
+fn advance_payout_position(group_id: u64) {
+    let current = storage.get(payout_position_key(group_id))?;
+    storage.set(payout_position_key(group_id), current + 1);
+}
+```
+
+## Future Considerations
+
+- **v2.0**: Add configurable payout order (random, auction, custom)
+- **v2.0**: Allow mid-cycle order adjustments with group consensus
+- **v3.0**: Implement weighted payout (based on contribution amount)
+- **v3.0**: Support priority members with guaranteed early payouts
+
+## Related Decisions
+
+- ADR-001: Choice of Soroban platform
+- ADR-003: Backend event indexing approach
+
+## References
+
+- [Traditional ROSCA Practices](https://en.wikipedia.org/wiki/Rotating_savings_and_credit_association)
+- [Stellar-Save Architecture](../architecture.md)
+- [Contract Implementation](../../contracts/stellar-save/src/payout.rs)