enes9103/my-claude-agents-skills/architecture-decision-records

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

# ADR-0001: Use PostgreSQL as Primary Database
 
## Status
 
Accepted
 
## Context
 
We need to select a primary database for our new e-commerce platform. The system
will handle:
 
-~10,000 concurrent users
-Complex product catalog with hierarchical categories
-Transaction processing for orders and payments
-Full-text search for products
-Geospatial queries for store locator
 
The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
compliance for financial transactions.
 
## Decision Drivers
 
-**Must have ACID compliance** for payment processing
-**Must support complex queries** for reporting
-**Should support full-text search** to reduce infrastructure complexity
-**Should have good JSON support** for flexible product attributes
-**Team familiarity** reduces onboarding time
 
## Considered Options
 
### Option 1: PostgreSQL
 
-**Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
  search, PostGIS for geospatial, team has experience
-**Cons**: Slightly more complex replication setup than MySQL
 
### Option 2: MySQL
 
-**Pros**: Very familiar to team, simple replication, large community
-**Cons**: Weaker JSON support, no built-in full-text search (need
  Elasticsearch), no geospatial without extensions
 
### Option 3: MongoDB
 
-**Pros**: Flexible schema, native JSON, horizontal scaling
-**Cons**: No ACID for multi-document transactions (at decision time),
  team has limited experience, requires schema design discipline
 
## Decision
 
We will use **PostgreSQL 15** as our primary database.
 
## Rationale
 
PostgreSQL provides the best balance of:
 
1.**ACID compliance** essential for e-commerce transactions
2.**Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
   infrastructure complexity
3.**Team familiarity** with SQL databases reduces learning curve
4.**Mature ecosystem** with excellent tooling and community support
 
The slight complexity in replication is outweighed by the reduction in
additional services (no separate Elasticsearch needed).
 
## Consequences
 
### Positive
 
-Single database handles transactions, search, and geospatial queries
-Reduced operational complexity (fewer services to manage)
-Strong consistency guarantees for financial data
-Team can leverage existing SQL expertise
 
### Negative
 
-Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
-Vertical scaling limits may require read replicas sooner
-Some team members need PostgreSQL-specific training
 
### Risks
 
-Full-text search may not scale as well as dedicated search engines
-Mitigation: Design for potential Elasticsearch addition if needed
 
## Implementation Notes
 
-Use JSONB for flexible product attributes
-Implement connection pooling with PgBouncer
-Set up streaming replication for read replicas
-Use pg_trgm extension for fuzzy search
 
## Related Decisions
 
-ADR-0002: Caching Strategy (Redis) - complements database choice
-ADR-0005: Search Architecture - may supersede if Elasticsearch needed
 
## References
 
-[PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
-[PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
-Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`

# ADR-0012: Adopt TypeScript for Frontend Development
 
**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob, @charlie
 
## Context
 
Our React codebase has grown to 50+ components with increasing bug reports
related to prop type mismatches and undefined errors. PropTypes provide
runtime-only checking.
 
## Decision
 
Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
 
## Consequences
 
**Good**: Catch type errors at compile time, better IDE support, self-documenting
code.
 
**Bad**: Learning curve for team, initial slowdown, build complexity increase.
 
**Mitigations**: TypeScript training sessions, allow gradual adoption with
`allowJs: true`.

# ADR-0015: API Gateway Selection
 
In the context of **building a microservices architecture**,
facing **the need for centralized API management, authentication, and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx solution**,
to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
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 profile storage due to schema flexibility
needs. Since then:
 
-MongoDB's multi-document transactions remain problematic for our use case
-Our schema has stabilized and rarely changes
-We now have PostgreSQL expertise from other services
-Maintaining two databases increases operational burden
 
## Decision
 
Deprecate MongoDB and migrate user profiles to PostgreSQL.
 
## Migration Plan
 
1.**Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
2.**Phase 2** (Week 3-4): Backfill historical data, validate consistency
3.**Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
4.**Phase 4** (Week 6): Remove MongoDB writes, decommission
 
## Consequences
 
### Positive
 
-Single database technology reduces operational complexity
-ACID transactions for user data
-Team can focus PostgreSQL expertise
 
### Negative
 
-Migration effort (~4 weeks)
-Risk of data issues during migration
-Lose some schema flexibility
 
## Lessons Learned
 
Document from ADR-0003 experience:
 
-Schema flexibility benefits were overestimated
-Operational cost of multiple databases was underestimated
-Consider long-term maintenance in technology decisions

# RFC-0025: Adopt Event Sourcing for Order Management
 
## Summary
 
Propose adopting event sourcing pattern for the order management domain to
improve auditability, enable temporal queries, and support business analytics.
 
## Motivation
 
Current challenges:
 
1.Audit requirements need complete order history
2."What was the order state at time X?" queries are impossible
3.Analytics team needs event stream for real-time dashboards
4.Order state reconstruction for customer support is manual
 
## Detailed Design
 
### Event Store

 
### Projections
 
- **CurrentOrderState**: Materialized view for queries
- **OrderHistory**: Complete timeline for audit
- **DailyOrderMetrics**: Analytics aggregation
 
### Technology
 
- Event Store: EventStoreDB (purpose-built, handles projections)
- Alternative considered: Kafka + custom projection service
 
## Drawbacks
 
- Learning curve for team
- Increased complexity vs. CRUD
- Need to design events carefully (immutable once stored)
- Storage growth (events never deleted)
 
## Alternatives
 
1. **Audit tables**: Simpler but doesn't enable temporal queries
2. **CDC from existing DB**: Complex, doesn't change data model
3. **Hybrid**: Event source only for order state changes
 
## Unresolved Questions
 
- [ ] Event schema versioning strategy
- [ ] Retention policy for events
- [ ] Snapshot frequency for performance
 
## Implementation Plan
 
1. Prototype with single order type (2 weeks)
2. Team training on event sourcing (1 week)
3. Full implementation and migration (4 weeks)
4. Monitoring and optimization (ongoing)
 
## References
 
- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [EventStoreDB Documentation](https://www.eventstore.com/docs)

docs/
├── 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
 
This directory contains Architecture Decision Records (ADRs) for [Project Name].
 
## Index
 
| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User 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 the template
3.Submit PR for review
4.Update this index after approval
 
## ADR Status
 
-**Proposed**: Under discussion
-**Accepted**: Decision made, implementing
-**Deprecated**: No longer relevant
-**Superseded**: Replaced by another ADR
-**Rejected**: Considered but not adopted

# Install adr-tools
brew install adr-tools
 
# Initialize ADR directory
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 table of contents
adr generate toc > docs/adr/README.md
 
# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

## ADR Review Checklist
 
### Before Submission
 
-[ ] Context clearly explains the problem
-[ ] All viable options considered
-[ ] Pros/cons balanced and honest
-[ ] Consequences (positive and negative) documented
-[ ] Related ADRs linked
 
### During Review
 
-[ ] At least 2 senior engineers reviewed
-[ ] Affected teams consulted
-[ ] Security implications considered
-[ ] Cost implications documented
-[ ] Reversibility assessed
 
### After Acceptance
 
-[ ] ADR index updated
-[ ] Team notified
-[ ] Implementation tickets created
-[ ] Related documentation updated