Implementation Guides
Implementation guides are step-by-step instructions for executing decisions documented in Architecture Decision Records (ADRs). While ADRs capture the "what" and "why" of architectural decisions, implementation guides provide the "how" - concrete steps to bring those decisions to life.
Active Implementations
Miniapp Multi-Environment Deployment
Status: In Progress Phase: 1 - Fix Staging Credentials Related ADR: Miniapp Multi-Environment Deployment Model
Setting up full multi-environment deployment for the Emerge miniapp with proper Farcaster credentials per domain.
Current Progress:
- [ ] Phase 1: Fix Staging Credentials
- [ ] Phase 2: Local Development with Ngrok
- [ ] Phase 3: Production Custom Domain
- [ ] Phase 4: Environment-Specific Bot Accounts
Implementation Guide Format
Each implementation guide includes:
| Section | Purpose |
|---|---|
| Related ADR | Link to the architectural decision being implemented |
| Prerequisites | What you need before starting |
| Phases | Ordered implementation steps |
| Verification | How to confirm each phase works |
| Troubleshooting | Common issues and fixes |
When to Create an Implementation Guide
Create an implementation guide when:
- ✅ An ADR requires multi-step execution
- ✅ The implementation spans multiple services or configurations
- ✅ There are environment-specific considerations
- ✅ The process needs to be repeatable
Do not create implementation guides for:
- ❌ Simple, one-time changes
- ❌ Implementation details already in the ADR
- ❌ Code-only changes without configuration
Naming Convention
Implementation files follow the same date-based naming as ADRs:
YYYY-MM-DD-implementation-name.mdExample: 2026-01-29-miniapp-deployment.md
Contributing
To create a new implementation guide:
- Ensure the related ADR exists and is accepted
- Create a new file:
impl/YYYY-MM-DD-name.md - Include frontmatter with
related_adrreference - Document phases with clear verification steps
- Submit PR for review