System Design
Architectural decision framework for web apps and iOS native applications with custom backends.
Decision Process
- Identify requirements (scale, platform, constraints)
- Load relevant reference file (see table below)
- Use comparison matrix to evaluate options
- Verify compatibility using MCP context7 for latest docs
- Document decision with rationale
Reference Navigation
| Decision Type | Load | Use When | |---------------|------|----------| | API style | references/api-patterns.md | Choosing REST vs GraphQL vs gRPC | | Database | references/database-patterns.md | Selecting primary database, caching layer | | Authentication | references/auth-patterns.md | Designing auth flow, token strategy | | Real-time | references/realtime-patterns.md | Adding live updates, push notifications | | iOS architecture | references/ios-patterns.md | Native iOS app structure, offline-first | | Backend architecture | references/architecture-patterns.md | Monolith vs microservices, serverless | | File storage | references/storage-patterns.md | Media uploads, CDN, cloud storage |
Decision Documentation
Record each decision in .agents/architect/decisions.md:
## [date] - [decision title]
Context: [what prompted this decision]
Options: [what was considered]
Decision: [what was chosen]
Rationale: [why]Platform Considerations
Web + iOS Projects
- Design API with mobile constraints in mind (bandwidth, battery)
- Plan for offline-first on iOS with backend sync
- Consider BFF (Backend for Frontend) if needs diverge significantly
iOS-Specific
- Always check
references/ios-patterns.mdfor native patterns - Auth must include Keychain storage and biometrics
- Push notifications require APNs backend integration