1# ADR-0001: Use PostgreSQL as Primary Database
  2
  3## Status
  4
  5Accepted
  6
  7## Context
  8
  9We need to select a primary database for our new e-commerce platform. The system
 10will handle:
 11
 12- ~10,000 concurrent users
 13- Complex product catalog with hierarchical categories
 14- Transaction processing for orders and payments
 15- Full-text search for products
 16- Geospatial queries for store locator
 17
 18The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
 19compliance for financial transactions.
 20
 21## Decision Drivers
 22
 23- **Must have ACID compliance** for payment processing
 24- **Must support complex queries** for reporting
 25- **Should support full-text search** to reduce infrastructure complexity
 26- **Should have good JSON support** for flexible product attributes
 27- **Team familiarity** reduces onboarding time
 28
 29## Considered Options
 30
 31### Option 1: PostgreSQL
 32
 33- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
 34  search, PostGIS for geospatial, team has experience
 35- **Cons**: Slightly more complex replication setup than MySQL
 36
 37### Option 2: MySQL
 38
 39- **Pros**: Very familiar to team, simple replication, large community
 40- **Cons**: Weaker JSON support, no built-in full-text search (need
 41  Elasticsearch), no geospatial without extensions
 42
 43### Option 3: MongoDB
 44
 45- **Pros**: Flexible schema, native JSON, horizontal scaling
 46- **Cons**: No ACID for multi-document transactions (at decision time),
 47  team has limited experience, requires schema design discipline
 48
 49## Decision
 50
 51We will use **PostgreSQL 15** as our primary database.
 52
 53## Rationale
 54
 55PostgreSQL provides the best balance of:
 56
 571. **ACID compliance** essential for e-commerce transactions
 582. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
 59   infrastructure complexity
 603. **Team familiarity** with SQL databases reduces learning curve
 614. **Mature ecosystem** with excellent tooling and community support
 62
 63The slight complexity in replication is outweighed by the reduction in
 64additional services (no separate Elasticsearch needed).
 65
 66## Consequences
 67
 68### Positive
 69
 70- Single database handles transactions, search, and geospatial queries
 71- Reduced operational complexity (fewer services to manage)
 72- Strong consistency guarantees for financial data
 73- Team can leverage existing SQL expertise
 74
 75### Negative
 76
 77- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
 78- Vertical scaling limits may require read replicas sooner
 79- Some team members need PostgreSQL-specific training
 80
 81### Risks
 82
 83- Full-text search may not scale as well as dedicated search engines
 84- Mitigation: Design for potential Elasticsearch addition if needed
 85
 86## Implementation Notes
 87
 88- Use JSONB for flexible product attributes
 89- Implement connection pooling with PgBouncer
 90- Set up streaming replication for read replicas
 91- Use pg_trgm extension for fuzzy search
 92
 93## Related Decisions
 94
 95- ADR-0002: Caching Strategy (Redis) - complements database choice
 96- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
 97
 98## References
 99
100- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
101- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
102- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`

 1# ADR-0012: Adopt TypeScript for Frontend Development
 2
 3**Status**: Accepted
 4**Date**: 2024-01-15
 5**Deciders**: @alice, @bob, @charlie
 6
 7## Context
 8
 9Our React codebase has grown to 50+ components with increasing bug reports
10related to prop type mismatches and undefined errors. PropTypes provide
11runtime-only checking.
12
13## Decision
14
15Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
16
17## Consequences
18
19**Good**: Catch type errors at compile time, better IDE support, self-documenting
20code.
21
22**Bad**: Learning curve for team, initial slowdown, build complexity increase.
23
24**Mitigations**: TypeScript training sessions, allow gradual adoption with
25`allowJs: true`.

1# ADR-0015: API Gateway Selection
2
3In the context of **building a microservices architecture**,
4facing **the need for centralized API management, authentication, and rate limiting**,
5we decided for **Kong Gateway**
6and against **AWS API Gateway and custom Nginx solution**,
7to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
8accepting that **we need to manage Kong infrastructure ourselves**.

 1# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL
 2
 3## Status
 4
 5Accepted (Supersedes ADR-0003)
 6
 7## Context
 8
 9ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
10needs. Since then:
11
12- MongoDB's multi-document transactions remain problematic for our use case
13- Our schema has stabilized and rarely changes
14- We now have PostgreSQL expertise from other services
15- Maintaining two databases increases operational burden
16
17## Decision
18
19Deprecate MongoDB and migrate user profiles to PostgreSQL.
20
21## Migration Plan
22
231. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
242. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
253. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
264. **Phase 4** (Week 6): Remove MongoDB writes, decommission
27
28## Consequences
29
30### Positive
31
32- Single database technology reduces operational complexity
33- ACID transactions for user data
34- Team can focus PostgreSQL expertise
35
36### Negative
37
38- Migration effort (~4 weeks)
39- Risk of data issues during migration
40- Lose some schema flexibility
41
42## Lessons Learned
43
44Document from ADR-0003 experience:
45
46- Schema flexibility benefits were overestimated
47- Operational cost of multiple databases was underestimated
48- Consider long-term maintenance in technology decisions

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

 1# Architecture Decision Records
 2
 3This directory contains Architecture Decision Records (ADRs) for [Project Name].
 4
 5## Index
 6
 7| ADR                                   | Title                              | Status     | Date       |
 8| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
 9| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
10| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
11| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
12| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |
13
14## Creating a New ADR
15
161. Copy `template.md` to `NNNN-title-with-dashes.md`
172. Fill in the template
183. Submit PR for review
194. Update this index after approval
20
21## ADR Status
22
23- **Proposed**: Under discussion
24- **Accepted**: Decision made, implementing
25- **Deprecated**: No longer relevant
26- **Superseded**: Replaced by another ADR
27- **Rejected**: Considered but not adopted

 1# Install adr-tools
 2brew install adr-tools
 3
 4# Initialize ADR directory
 5adr init docs/adr
 6
 7# Create new ADR
 8adr new "Use PostgreSQL as Primary Database"
 9
10# Supersede an ADR
11adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
12
13# Generate table of contents
14adr generate toc > docs/adr/README.md
15
16# Link related ADRs
17adr link 2 "Complements" 1 "Is complemented by"

 1## ADR Review Checklist
 2
 3### Before Submission
 4
 5- [ ] Context clearly explains the problem
 6- [ ] All viable options considered
 7- [ ] Pros/cons balanced and honest
 8- [ ] Consequences (positive and negative) documented
 9- [ ] Related ADRs linked
10
11### During Review
12
13- [ ] At least 2 senior engineers reviewed
14- [ ] Affected teams consulted
15- [ ] Security implications considered
16- [ ] Cost implications documented
17- [ ] Reversibility assessed
18
19### After Acceptance
20
21- [ ] ADR index updated
22- [ ] Team notified
23- [ ] Implementation tickets created
24- [ ] Related documentation updated