Cultivating an AI-Friendly Codebase

# System Architecture

## Overview
This is a microservices-based e-commerce platform with:
- React frontend (port 3000)
- Node.js API gateway (port 8000)
- Python recommendation service (port 8001)
- PostgreSQL database
- Redis cache

## Key Design Decisions

### Why microservices?
We chose microservices to enable independent scaling
and team autonomy. Trade-off: Added complexity in
deployment and debugging.

### Why PostgreSQL?
Strong ACID guarantees for financial transactions.
Trade-off: More expensive to scale than NoSQL.

## System Boundaries
- Frontend: Only UI logic, no business rules
- API Gateway: Authentication, routing, rate limiting
- Services: Domain-specific business logic
- Database: Single source of truth

## Integration Points
- Payment: Stripe API
- Email: SendGrid
- Analytics: Segment
- Monitoring: Datadog

# User Authentication System

## Requirements
- Email/password login
- OAuth (Google, GitHub)
- 2FA via TOTP
- Session timeout: 24 hours
- Password requirements: 12+ chars, mixed case, numbers

## Constraints
- Must work with existing user table
- Cannot break mobile app (v2.1.0+)
- GDPR compliant data handling
- Max login attempts: 5 per hour

## Edge Cases
- User changes email during active session
- OAuth provider is down
- User has 2FA but loses device
- Concurrent logins from different devices

# Architectural Decision Records

## ADR-001: Why We Use Redux Instead of Context API
**Date**: 2024-01-15
**Status**: Accepted

**Context**: Need state management for complex app state

**Decision**: Use Redux Toolkit over React Context API

**Rationale**:
- Time-travel debugging is valuable for bug reproduction
- Middleware ecosystem (thunks, sagas) provides flexibility
- Team already familiar with Redux patterns

**Consequences**:
- More boilerplate than Context
- Learning curve for new developers
- Worth it for our scale and complexity

**Alternatives Considered**:
- React Context API (too limited for our needs)
- MobX (team lacks experience)
- Zustand (too new, small ecosystem)

# Known Gotchas and Pitfalls

## Database Gotchas

### Race Condition in Order Processing
**Problem**: Orders can be processed twice if user clicks fast
**Solution**: Use SELECT FOR UPDATE lock in transaction
**Example**: See `services/orders/create.ts:45`

### Slow Query on User Dashboard
**Problem**: JOIN across 5 tables without indexes
**Solution**: Use materialized view that refreshes hourly
**Location**: `migrations/015_dashboard_view.sql`

## Authentication Gotchas

### Session Cookie Not Working in Safari
**Problem**: SameSite=None requires Secure flag
**Solution**: Ensure HTTPS in production, use Lax in dev
**Config**: `config/session.ts:12`

## Deployment Gotchas

### Environment Variables Not Loading
**Problem**: .env file ignored in Docker
**Solution**: Use --env-file flag or ENV in Dockerfile
**Documentation**: `deployment/README.md`

"Why is the authentication failing in production but working locally?"
[30 minutes of investigation]
"Ah! SameSite cookie issue with Safari and cross-origin requests"

## Auth Gotcha: Safari Cookie Issue
**Problem**: Auth works locally but fails in Safari on production
**Cause**: SameSite=None requires Secure flag (HTTPS)
**Solution**: Set sameSite:'none', secure:true for production
**Location**: config/session.ts:12
**Date Discovered**: 2024-01-28

"Before implementing auth, read GOTCHAS.md to avoid known pitfalls."
AI reads the file and proactively suggests: "I see we've had Safari
cookie issues before. I'll make sure to set SameSite and Secure flags."