architecture-decision-recordsDocument significant technical decisions with context, rationale, and consequences to maintain clear, lightweight architectural records for future reference.
Install via ClawdBot CLI:
clawdbot install wpank/architecture-decision-recordsLightweight documentation capturing the context, decision, and consequences of significant technical choices. ADRs become the institutional memory of why things are built the way they are.
ADR, architecture decision record, technical documentation, decision log, MADR, RFC, design decisions, trade-offs
| Write ADR | Skip ADR |
|-----------|----------|
| New framework/language adoption | Minor version upgrades |
| Database technology choice | Bug fixes |
| API design patterns | Implementation details |
| Security architecture | Routine maintenance |
| Integration patterns | Configuration changes |
| Breaking changes | Code formatting |
Proposed ā Accepted ā Deprecated ā Superseded
ā
RejectedNever modify accepted ADRs - write new ones to supersede.
# ADR-NNNN: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Context
[What is the issue? What forces are at play? 2-3 paragraphs max.]
## Decision
We will [decision statement].
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Drawback 1]
- [Drawback 2]
### Risks
- [Risk and mitigation]
## Related
- ADR-XXXX: [Related decision]# ADR-0001: Use PostgreSQL as Primary Database
## Status
Accepted
## Context
We need to select a primary database for our e-commerce platform handling:
- ~10,000 concurrent users
- Complex product catalog with hierarchical categories
- Transaction processing for orders and payments
- Full-text search for products
The team has experience with MySQL, PostgreSQL, and MongoDB.
## Decision Drivers
- **Must have** ACID compliance for payment processing
- **Must support** complex queries for reporting
- **Should support** full-text search to reduce infrastructure
- **Should have** good JSON support for flexible product attributes
## Considered Options
### Option 1: PostgreSQL
**Pros**: ACID compliant, excellent JSONB support, built-in full-text search, PostGIS
**Cons**: Slightly more complex replication than MySQL
### Option 2: MySQL
**Pros**: Familiar to team, simple replication
**Cons**: Weaker JSON support, no built-in full-text search
### Option 3: MongoDB
**Pros**: Flexible schema, native JSON
**Cons**: No ACID for multi-document transactions, team has limited experience
## Decision
We will use **PostgreSQL 15** as our primary database.
## Rationale
PostgreSQL provides the best balance of ACID compliance (essential for e-commerce),
built-in capabilities (reduces infrastructure), and team familiarity.
## Consequences
### Positive
- Single database handles transactions, search, and geospatial
- Reduced operational complexity
- Strong consistency for financial data
### Negative
- Need PostgreSQL-specific training for team
- Vertical scaling limits may require read replicas
### Risks
- Full-text search may not scale as well as Elasticsearch
- **Mitigation**: Design for potential ES addition if needed
## Implementation Notes
- Use JSONB for flexible product attributes
- Implement connection pooling with PgBouncer
- Set up streaming replication for read replicas
## Related
- ADR-0002: Caching Strategy (Redis)
- ADR-0005: Search Architecture# ADR-0012: Adopt TypeScript for Frontend
**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob
## Context
React codebase has 50+ components with increasing bugs from prop type mismatches.
## Decision
Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
## Consequences
**Good**: Catch type errors at compile time, better IDE support
**Bad**: Learning curve, initial slowdown
**Mitigation**: Training sessions, `allowJs: true` for gradual adoption# ADR-0015: API Gateway Selection
In the context of **building a microservices architecture**,
facing **the need for centralized API management and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx**,
to achieve **vendor independence and plugin extensibility**,
accepting that **we need to manage Kong infrastructure ourselves**.# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL
## Status
Accepted (Supersedes ADR-0003)
## Context
ADR-0003 (2021) chose MongoDB for user profiles. Since then:
- MongoDB transactions remain problematic for our use case
- Our schema has stabilized and rarely changes
- Maintaining two databases increases operational burden
## Decision
Deprecate MongoDB and migrate user profiles to PostgreSQL.
## Migration Plan
1. **Week 1-2**: Create PostgreSQL schema, enable dual-write
2. **Week 3-4**: Backfill historical data, validate consistency
3. **Week 5**: Switch reads to PostgreSQL
4. **Week 6**: Remove MongoDB writes, decommission
## Lessons Learned
- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimateddocs/
āāā adr/
āāā README.md # Index and guidelines
āāā template.md # Team's ADR template
āāā 0001-use-postgresql.md
āāā 0002-caching-strategy.md
āāā 0003-mongodb-user-profiles.md # [DEPRECATED]
āāā 0020-deprecate-mongodb.md # Supersedes 0003# Architecture Decision Records
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted | 2024-01-10 |
| [0002](0002-caching-strategy.md) | Caching with Redis | Accepted | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for Profiles | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
## Creating a New ADR
1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in template, submit PR for review
3. Update this index after approval# Install
brew install adr-tools
# Initialize
adr init docs/adr
# Create new ADR
adr new "Use PostgreSQL as Primary Database"
# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
# Generate index
adr generate toc > docs/adr/README.mdBefore submission:
During review:
After acceptance:
Generated Mar 1, 2026
A retail company building a new e-commerce platform needs to choose a primary database that supports ACID transactions for payments, complex queries for reporting, and full-text search for products. The team evaluates PostgreSQL, MySQL, and MongoDB to balance compliance, scalability, and team expertise, documenting the decision to ensure consistency and future reference.
A fintech startup adopting a microservices architecture must select an API gateway for centralized management, rate limiting, and security. They compare Kong Gateway, AWS API Gateway, and custom Nginx solutions, focusing on vendor independence, extensibility, and infrastructure management trade-offs to support rapid scaling and regulatory compliance.
A SaaS company with a large React codebase experiences increasing bugs from prop type mismatches and decides to adopt TypeScript for improved type safety and developer tooling. They plan an incremental migration, documenting the decision to manage learning curves and ensure smooth adoption across teams.
An enterprise with a legacy MongoDB setup for user profiles faces operational burdens and transaction issues, deciding to migrate to PostgreSQL for better consistency and reduced complexity. They create a deprecation ADR to outline the migration plan, lessons learned, and ensure alignment across development and operations teams.
A healthcare provider designing a new patient data system must choose between architectural approaches for handling sensitive health records, focusing on security, compliance (e.g., HIPAA), and integration patterns. They use ADRs to document decisions on database technology, API design, and risk mitigations to maintain audit trails and institutional knowledge.
Companies offering software services on a recurring subscription basis use ADRs to document decisions on technology stacks, scalability strategies, and API designs, ensuring long-term maintainability and reducing technical debt as they evolve features and integrate with third-party systems.
Consulting firms and development agencies leverage ADRs to capture client-specific architectural decisions, such as framework adoptions or infrastructure choices, providing transparent documentation that aids in project handovers, compliance audits, and future enhancements for enterprise clients.
Open source projects and communities use ADRs to log key technical decisions, like adopting new libraries or deprecating features, fostering collaboration and transparency among contributors, and serving as a reference for users and maintainers to understand the project's evolution and rationale.
š¬ Integration Tip
Integrate ADRs into your existing documentation workflow by storing them in a version-controlled directory like docs/adr/ and linking them from project READMEs to ensure visibility and consistency across teams.
Use when designing new system architecture, reviewing existing designs, or making architectural decisions. Invoke for system design, architecture review, design patterns, ADRs, scalability planning.
Guide any property decision for buyers, sellers, landlords, investors, or agents in any jurisdiction.
Predict construction project costs using Machine Learning. Use Linear Regression, K-Nearest Neighbors, and Random Forest models on historical project data. Train, evaluate, and deploy cost prediction models.
Generate photorealistic architectural renders and visualizations using each::sense AI. Create exterior views, interior renders, sketch-to-render conversions,...
Dual-stream event publishing combining Kafka for durability with Redis Pub/Sub for real-time delivery. Use when building event-driven systems needing both guaranteed delivery and low-latency updates. Triggers on dual stream, event publishing, Kafka Redis, real-time events, pub/sub, streaming architecture.
Convert IFC files (2x3, 4x1, 4x3) to Excel databases using IfcExporter CLI. Extract BIM data, properties, and geometry without proprietary software.