"Think of [system] like [familiar thing]. [Familiar thing] does X, Y, Z.
Similarly, [system] does A, B, C to solve [problem]."

Lesson: [What was learned]
Story: "We discovered this when [situation]. [What happened].
        [How we fixed it]."
Takeaway: [How to apply in future]

Lesson: Database Migrations Need Careful Planning

Story: "We had a production database with 10 million user records. We wanted
to add a new column with a NOT NULL constraint. We didn't think to make it
nullable first, then backfill. We locked the entire table for 2 hours.
Customers couldn't log in. 😱"

Takeaway: For large tables, always backfill with nullable columns first,
then add constraints. Test on production volume in staging first.

User → [Component A] → [Component B] → Storage
  ↓                                        ↑
  └─── Response ←─────────────────────────┘

[Component A] receives requests and validates them.
[Component B] processes business logic.
Storage persists results.
Response returns to user.

Key insight: [Why this design matters]

We chose [Option A] over [Option B] because [reason].
Trade-off: [What we gave up] vs [What we gained].
Constraint: [What made this choice necessary].
Alternative: If [constraint changed], we would [different approach].

We chose PostgreSQL over MongoDB because transaction support was critical
for payment data integrity.
Trade-off: More complex queries vs guaranteed data consistency.
Constraint: Financial data must never be corrupted, even in edge cases.
Alternative: If we had simple key-value data with no relationships,
we'd use DynamoDB for infinite scalability.

Imagine [familiar analogy]. [System] is similar. It [core purpose] by
[key mechanism]. Just like [analogy detail], [system] [parallel detail].

In practical terms: [concrete example of what it does]

## Architecture Overview

The system consists of [N] main components:

1. [Component A] - Role and responsibility
2. [Component B] - Role and responsibility
3. [Component C] - Role and responsibility

## Data Flow

[ASCII diagram or text flow]

User requests → A → B → Storage → Response

Each component has a specific job:
- [Component A] does [X]
- [Component B] does [Y]
- [Component C] does [Z]

## Why This Design

We separated concerns into layers because [reason]:
- Easier to test each layer independently
- Clear responsibilities
- Can replace components without affecting others

## [Technology Name]

### The Choice
We use [Technology] for [purpose].

### Why We Chose It
1. [Reason 1]: [Explanation with example]
2. [Reason 2]: [Explanation with example]
3. [Reason 3]: [Explanation with example]

### Alternatives Considered
- [Alternative 1]: [Why we didn't choose it]
- [Alternative 2]: [Why we didn't choose it]

### Lesson We Learned
[Anecdote about discovering why this was the right choice]

Example: "We initially considered [other tech], but in production discovered
that [problem]. Switching to [chosen tech] fixed [issue]."

## Directory Structure

## Folder Purposes

### handlers/
Receives HTTP requests and routes them. Handles:
- Input validation
- Calling services
- Formatting responses

Example: `handlers/users.ts` handles GET /users/:id

### services/
Business logic and rules. Handles:
- User validation
- Database queries
- External service calls

Example: `services/UserService.ts` validates and creates users

### models/
Data structures and schema. Defines:
- TypeScript types
- Database schemas
- Validation rules

Example: `models/User.ts` defines user data structure

## Why This Structure

This layered architecture keeps concerns separate:
- Handlers: HTTP concerns
- Services: Business logic
- Models: Data definitions

Each layer can be tested independently.

## Lesson 1: [Title]

### The Problem
[What went wrong, when we discovered it, impact]

### How We Fixed It
[What we changed, how it solved the problem]

### Takeaway
[How to avoid this, apply the lesson to future projects]

---

## Lesson 2: [Title]

[Same structure...]

## Constraints That Shaped This Design

### Consistency Over Performance
We chose PostgreSQL with transactions over eventually-consistent NoSQL
because losing money data is worse than slightly slower queries.
Constraint: Financial systems must never have data corruption.

### Latency Over Throughput
We process payments synchronously (user waits for response) instead of
async because users need to know immediately if their payment succeeded.
Constraint: Users expect <500ms response time for payment confirmation.

### Simplicity Over Flexibility
We use a monolith instead of microservices because the added complexity
of distributed systems wasn't justified by our scale.
Constraint: 5 engineers, not 500. Operational simplicity matters.

## If Constraints Changed...

If we didn't care about response time, we'd process payments asynchronously.
If we had 10x the volume, we'd split into microservices.
If we had less important data, we'd use cheaper but riskier datastores.

Architecture is shaped by constraints. When constraints change, architecture should too.

## What We Learned

[Project] succeeds because:
1. [Key insight 1]
2. [Key insight 2]
3. [Key insight 3]

## For Future Engineers

When maintaining or extending this system, remember:
- [Critical principle]
- [Important constraint]
- [Lesson we learned the hard way]

## Questions?

This explanation covers the major architecture and decisions. For specific
implementation details, see:
- [Architecture ADRs](./docs/adr/)
- [Setup Guide](./SETUP.md)
- [Contributing Guide](./CONTRIBUTING.md)