production-principles

# Production Development Principles

These are universal production development principles for any project.

> **Philosophy**: Simple, scalable, maintainable. Not MVP shortcuts, not enterprise bloat.

## Golden Rules (ALWAYS Follow)

1. **If it works reliably, ship it** - Perfect is still the enemy of done
2. **YAGNI until you need it** - Don't build for hypothetical futures
3. **Simple files > Complex architecture** - Start simple, extract when needed
4. **Direct > Abstract** - Prefer direct solutions, abstract when patterns emerge
5. **Start hardcoded, extract when needed** - Make it configurable after the 3rd use
6. **Quality matters now** - We have paying customers, but over-engineering still hurts
7. **200 lines before extracting** - Functions/features can be larger now, but extract at 200 lines

## Reality Check (Where We Are)

- **your current customer base**: Optimize for this scale, not millions
- **Production beta**: Real customers, but still learning
- **Multi-tenant**: Each customer has unique needs
- **Speed + Reliability**: Ship fast, but don't break things
- **Technical debt payback**: Fix issues that impact customers NOW

## Patterns to Avoid (Nuanced for Our Scale)

### ❌ Avoid Unless Justified

These patterns add complexity. Only use if you meet the criteria:

- **Factory patterns**: Avoid unless you have 5+ different implementations
- **Dependency injection frameworks**: Avoid unless team size >5 developers (Go interfaces are fine)
- **Abstract base classes**: Avoid unless you have 3+ concrete implementations
- **Event sourcing / CQRS**: Avoid unless you have audit requirements or >10,000 events/day
- **Microservices**: Avoid unless monolith is >100k LOC or team >10 developers
- **Complex repository patterns**: Avoid unless you have 5+ data sources (direct queries + transactions are fine)
- **Service meshes**: Avoid unless you have >20 services
- **API gateways**: Avoid unless you have >10 backend services (nginx is enough)
- **Custom frameworks**: Avoid unless you're doing the same thing 10+ times

### 🚫 Still Completely Banned

- **Premature optimization**: Never optimize before measuring
- **Speculative generality**: Never build for "what if" scenarios
- **Gold plating**: Never add features "because it's cool"
- **Resume-driven development**: Never use tech "to learn it"

## Patterns to Use (Production-Ready)

✅ **Strongly Encouraged**:
- Simple functions with clear names
- Direct database queries with transactions for multi-step operations
- Configuration files/env vars (not hardcoded secrets)
- Defensive coding (validation, error handling, retries)
- Logging and monitoring (errors, performance, business metrics)
- Inline code when <3 uses, extract when 3+ uses (Rule of Three)
- Database migrations (not raw SQL changes)
- Basic caching when queries are measured as slow (>500ms)
- Polling with smart intervals (not webhooks unless push is required)
- Functions up to 200 lines (extract at 200, not 50)

## Production Concerns (NEW)

### 🚨 Must Haves for Production

1. **Error Handling**
   - All external calls wrapped in try/catch
   - Errors logged with context (user, customer, operation)
   - User-friendly error messages
   - Retry logic for transient failures (network, rate limits)

2. **Data Integrity**
   - Use database transactions for multi-step operations
   - Validate inputs before writing to database
   - Backups run daily (already set up)
   - Soft deletes for critical data (tickets, users)

3. **Observability**
   - Log all errors with stack traces
   - Log slow operations (>2s)
   - Monitor API response times
   - Track business metrics relevant to your product

4. **Security**
   - Never log secrets/API keys (use last 4 chars only)
   - Validate + sanitize user inputs
   - Rate limiting on public endpoints
   - Keep dependencies updated (monthly review)

5. **Multi-tenancy** (if applicable)
   - Every query includes tenant ID filter
   - Test with multiple tenants
   - No cross-tenant data leaks

### ⚖️ Production vs Speed Balance

#### Ship Fast (do these)
- Inline validation (no validation framework)
- Direct SQL queries (no ORM)
- Environment variables for config
- Simple retry logic (3 attempts, exponential backoff)
- File-based logs (rotate daily)

#### Take Time (do these right)
- Database migrations (use migrate tool)
- Authentication/authorization (test thoroughly)
- Data export/import (customers depend on this)
- Email delivery (use queue + retries)
- Payment processing (never cut corners)

## Decision Framework (Updated for Production)

Before ANY architectural decision, ask:

### Question 1: Is this reliable for production?
- **If yes**: Proceed
- **If no**: What's missing? (error handling, validation, logging)

### Question 2: Will 100 customers break this?
- **If no**: Ship it
- **If yes**: What's the bottleneck? Add specific fix (caching, indexing, pagination)

### Question 3: Can another dev maintain this in 6 months?
- **If yes**: Good complexity level
- **If no**: Add comments, extract functions, simplify

### Question 4: What's the blast radius if this fails?
- **One user**: Ship it, fix if it breaks
- **One customer**: Add error handling + logging
- **All customers**: Add retry logic, monitoring, fallbacks

## When to Add Abstraction (NEW)

### Triggers for Abstraction

Extract to function/class when:
- **Rule of Three**: Same logic used 3+ times
- **Domain complexity**: Business logic gets complicated (AI logic, ticket routing)
- **Testing**: Hard to test without extraction
- **Multiple implementations**: 3+ ways to do something (Zendesk, Jira, email)
- **File size**: Function/feature exceeds 200 lines

### Extraction Examples

#### ✅ Good Abstractions (Justified)

- **Extract after 3rd duplicate**: A validation function used by 3+ handlers
- **Extract complex business logic**: When a single function exceeds 200 lines with conditional logic
- **Extract when 3+ implementations exist**: e.g., EmailProvider, SlackProvider, TeamsProvider — three implementations justify an interface

#### ❌ Still Over-Engineering

- **Abstract factories** when you only have 1 implementation
- **Generic repository patterns** when direct queries work fine
- **Configuration managers** when environment variables are enough

## Simplicity Checkpoints (Updated)

### Before Starting
- [ ] Is this the simplest RELIABLE approach?
- [ ] Do we need this for your current customer base (not 10,000)?
- [ ] Can this be 1-5 files?
- [ ] Is error handling included?
- [ ] Is this easily testable?

### During Implementation
- [ ] Am I adding abstraction before 3rd use?
- [ ] Am I creating >10 files? (Consolidate related logic)
- [ ] Did I add error handling + logging?
- [ ] Would another dev understand this in 6 months?
- [ ] Is this function >200 lines? (Extract if yes)

### Before Committing
- [ ] Does this handle failures gracefully?
- [ ] Are errors logged with context?
- [ ] Is complex logic tested (unit tests)?
- [ ] Can I deploy this without breaking existing customers?

## Scaling Triggers (When to Refactor)

### Refactor When You Hit These Limits

1. **Performance** (actual, not hypothetical)
   - API responses >2s consistently
   - Database queries >500ms
   - Memory usage growing unbounded
   - CPU consistently >70%

2. **Maintainability** (team pain)
   - Same bug appears 3+ times (extract + fix once)
   - Code duplicated 5+ times (extract + reuse)
   - New feature takes 2x longer than expected
   - Onboarding new dev takes >1 week

3. **Scale** (customer impact)
   - Customer count exceeding what your current architecture handles
   - Request volume exceeding what your database/server can handle
   - Database size requiring optimization or sharding

4. **Customer complaints** (real problems)
   - Specific feature requested by 5+ customers
   - Same issue reported 3+ times
   - Security concern raised by customer
   - Competitor has feature we don't

### Don't Refactor For

- "Clean code" principles (if it works reliably)
- Hypothetical scale (until you're at 80% of limit)
- Latest framework/library (unless security fix)
- Personal preferences (consistency > perfection)

## Mantras (Updated for Production)

- "Simple + Reliable beats complex + perfect"
- "Scale when you hit limits, not before"
- "Make it work, make it right, make it fast - IN THAT ORDER"
- "Abstract after 3rd duplicate, not before"
- "Add what you need, remove what you don't"
- "Customers don't care about architecture"
- "200 lines before extracting, not 50"

## When to Add "Enterprise" Patterns

Use enterprise patterns **ONLY when you meet ALL criteria**:

| Pattern | Minimum Requirements |
|---------|---------------------|
| Factory Pattern | 5+ different implementations |
| DI Framework | Team of 5+ developers |
| Microservices | Monolith >100k LOC OR team >10 developers |
| Event Sourcing | Audit requirement OR >10k events/day |
| CQRS | Read/write performance measured as bottleneck |
| Service Mesh | 20+ microservices |
| API Gateway | 10+ backend services |
| Repository Pattern | 5+ different data sources |

**Until you hit these thresholds**: Keep it simple

## The Prime Directive (Updated)

> **Build the simplest reliable thing that works for your current customer base. Then ship it.**

If you find yourself:
- Creating >10 files for a feature
- Writing >200 lines without extracting
- Thinking about "1000+ customer scalability"
- Adding abstraction before 3rd use
- Building generic frameworks

**STOP and ask**:

> **"What's the simplest RELIABLE way to make this work for 100 customers?"**

## Remember

You're not building for:
- ❌ Millions of users (unless you actually have them)
- ❌ Fortune 500 enterprise (unless you are one)
- ❌ Infinite scale (you need finite, measured scale)

You're building for:
- ✅ Your actual current user/customer count
- ✅ Fast iteration based on real feedback
- ✅ Reliable service for paying customers
- ✅ Maintainable codebase that your team can work on

**Ship working, reliable code. Ship it fast. Iterate based on customer feedback.**