Registros de Decisiones Arquitectónicas (ADRs)

# ADR-017: Use PostgreSQL as the Primary Database

## Status
Accepted (2026-02-15)

## Context
We are building a new order management system that requires:
- ACID transactions for financial data integrity
- Complex queries with JOINs across multiple tables
- Full-text search for order lookups
- JSON support for flexible product metadata

The team has experience with both PostgreSQL and MongoDB.
Our existing infrastructure runs PostgreSQL for other services.

## Decision
We will use PostgreSQL 16 as the primary database for the
order management system.

We considered:
1. MongoDB - Better for flexible schemas, but we need strong
   transactional guarantees. The team is less experienced with
   MongoDB operations.
2. MySQL - Viable option, but PostgreSQL's JSON support and
   full-text search eliminate the need for a separate search
   service. Our existing tooling and monitoring is set up for
   PostgreSQL.

## Consequences
### Positive
- Leverages existing team expertise and operational tooling
- Strong transactional guarantees for financial data
- Built-in JSON support avoids a separate document store
- Full-text search reduces need for Elasticsearch

### Negative
- Schema migrations require more planning than a document DB
- Horizontal scaling is more complex than MongoDB sharding
- Must design the schema upfront rather than evolving freely

### Risks
- If we outgrow single-node PostgreSQL, we will need to
  evaluate CitusDB or read replicas (estimated 12+ months away
  based on current growth projections)

# ADR-023: Migrate from REST to GraphQL for Client APIs

## Status
Accepted (2026-03-01)
Supersedes: ADR-008 (Use REST for all client-facing APIs)

## Context
Our mobile app requires 12 separate REST calls to render the
home screen, leading to high latency and over-fetching. The
frontend team spends significant time aggregating data from
multiple endpoints.

## Decision
New client-facing APIs will use GraphQL via Apollo Server.
Existing REST endpoints remain unchanged until their owning
team migrates them.

## Consequences
- Reduces mobile app network calls from 12 to 1 for home screen
- Requires team training on GraphQL (2-week investment)
- Need to implement rate limiting and query complexity analysis
- Existing REST APIs continue to work; no breaking changes