# 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

Template 2: Lightweight ADR

# 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`.

Template 3: Y-Statement Format

# 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**.

references/decision-templates.md

Raw file

wshobson/agents

- **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**: JSON querying/indexing differs from PostgreSQL JSONB; validate the

required operators and indexes. Built-in FULLTEXT and spatial support exist,

but their functions and limitations must be checked against this workload.

See the [MySQL index reference](https://dev.mysql.com/doc/refman/8.4/en/create-index.html).

### Option 3: MongoDB

- **Pros**: Flexible schema, native JSON, horizontal scaling

- **Cons**: [Multi-document transactions](https://www.mongodb.com/docs/manual/core/write-operations-atomicity/)

are supported on replica sets and sharded clusters but can cost more than

single-document writes; the team has limited experience and needs 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) reduce infrastructure complexity

3. **Added extensions**: PostGIS supplies geospatial capabilities after server

installation and [database enablement](https://postgis.net/documentation/getting_started/).

4. **Team familiarity** with SQL databases reduces learning curve

5. **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`