anchi-kit 1.2.0 → 1.2.2

package/.antigravity/skills/backend-development/references/backend-mindset.md

@@ -1,387 +0,0 @@
-# Backend Development Mindset
-
-Problem-solving approaches, architectural thinking, and collaboration patterns for backend engineers (2025).
-
-## Problem-Solving Mindset
-
-### Systems Thinking Approach
-
-**Holistic Engineering** - Understanding how components interact within larger ecosystem
-
-```
-User Request
-  → Load Balancer
-  → API Gateway (auth, rate limiting)
-  → Application (business logic)
-  → Cache Layer (Redis)
-  → Database (persistent storage)
-  → Message Queue (async processing)
-  → External Services
-```
-
-**Questions to Ask:**
-- What happens if this component fails?
-- How does this scale under load?
-- What are the dependencies?
-- Where are the bottlenecks?
-- What's the blast radius of changes?
-
-### Breaking Down Complex Problems
-
-**Decomposition Strategy:**
-
-1. **Understand requirements** - What problem are we solving?
-2. **Identify constraints** - Performance, budget, timeline, tech stack
-3. **Break into modules** - Separate concerns (auth, data, business logic)
-4. **Define interfaces** - API contracts between modules
-5. **Prioritize** - Critical path first
-6. **Iterate** - Build, test, refine
-
-**Example: Building Payment System**
-
-```
-Complex: "Build payment processing"
-
-Decomposed:
-1. Payment gateway integration (Stripe/PayPal)
-2. Order creation and validation
-3. Payment intent creation
-4. Webhook handling (success/failure)
-5. Idempotency (prevent double charges)
-6. Retry logic for transient failures
-7. Audit logging
-8. Refund processing
-9. Reconciliation system
-```
-
-## Trade-Off Analysis
-
-### CAP Theorem (Choose 2 of 3)
-
-**Consistency** - All nodes see same data at same time
-**Availability** - Every request receives response
-**Partition Tolerance** - System works despite network failures
-
-**Real-World Choices:**
-- **CP (Consistency + Partition Tolerance):** Banking systems, financial transactions
-- **AP (Availability + Partition Tolerance):** Social media feeds, product catalogs
-- **CA (Consistency + Availability):** Single-node databases (not distributed)
-
-### PACELC Extension
-
-**If Partition:** Choose Availability or Consistency
-**Else (no partition):** Choose Latency or Consistency
-
-**Examples:**
-- **PA/EL:** Cassandra (available during partition, low latency normally)
-- **PC/EC:** HBase (consistent during partition, consistent over latency)
-- **PA/EC:** DynamoDB (configurable consistency vs latency)
-
-### Performance vs Maintainability
-
-| Optimize For | When to Choose |
-|--------------|---------------|
-| **Performance** | Hot paths, high-traffic endpoints, real-time systems |
-| **Maintainability** | Internal tools, admin dashboards, CRUD operations |
-| **Both** | Core business logic, payment processing, authentication |
-
-**Example:**
-```typescript
-// Maintainable: Readable, easy to debug
-const users = await db.users.findAll({
-  where: { active: true },
-  include: ['posts', 'comments'],
-});
-
-// Performant: Optimized query, reduced joins
-const users = await db.query(`
-  SELECT u.*,
-    (SELECT COUNT(*) FROM posts WHERE user_id = u.id) as post_count,
-    (SELECT COUNT(*) FROM comments WHERE user_id = u.id) as comment_count
-  FROM users u
-  WHERE u.active = true
-`);
-```
-
-### Technical Debt Management
-
-**20-40% productivity increase** from addressing technical debt properly
-
-**Debt Quadrants:**
-1. **Reckless + Deliberate:** "We don't have time for design"
-2. **Reckless + Inadvertent:** "What's layering?"
-3. **Prudent + Deliberate:** "Ship now, refactor later" (acceptable)
-4. **Prudent + Inadvertent:** "Now we know better" (acceptable)
-
-**Prioritization:**
-- High interest, high impact → Fix immediately
-- High interest, low impact → Schedule in sprint
-- Low interest, high impact → Tech debt backlog
-- Low interest, low impact → Leave as-is
-
-## Architectural Thinking
-
-### Domain-Driven Design (DDD)
-
-**Bounded Contexts** - Separate models for different domains
-
-```
-E-commerce System:
-
-[Sales Context]          [Inventory Context]       [Shipping Context]
-- Order (id, items,      - Product (id, stock,     - Shipment (id,
-  total, customer)        location, reserved)       address, status)
-- Customer (id, email)   - Warehouse (id, name)    - Carrier (name, API)
-- Payment (status)       - StockLevel (quantity)   - Tracking (number)
-
-Each context has its own:
-- Data model
-- Business rules
-- Database schema
-- API contracts
-```
-
-**Ubiquitous Language** - Shared vocabulary between devs and domain experts
-
-### Layered Architecture (Separation of Concerns)
-
-```
-┌─────────────────────────────┐
-│   Presentation Layer        │  Controllers, Routes, DTOs
-│   (API endpoints)           │
-├─────────────────────────────┤
-│   Business Logic Layer      │  Services, Use Cases, Domain Logic
-│   (Core logic)              │
-├─────────────────────────────┤
-│   Data Access Layer         │  Repositories, ORMs, Database
-│   (Persistence)             │
-└─────────────────────────────┘
-```
-
-**Benefits:**
-- Clear responsibilities
-- Easier testing (mock layers)
-- Flexibility to change implementations
-- Reduced coupling
-
-### Designing for Failure (Resilience)
-
-**Assume everything fails eventually**
-
-**Patterns:**
-1. **Circuit Breaker** - Stop calling failing service
-2. **Retry with Backoff** - Exponential delay between retries
-3. **Timeout** - Don't wait forever
-4. **Fallback** - Graceful degradation
-5. **Bulkhead** - Isolate failures (resource pools)
-
-```typescript
-import { CircuitBreaker } from 'opossum';
-
-const breaker = new CircuitBreaker(externalAPICall, {
-  timeout: 3000, // 3s timeout
-  errorThresholdPercentage: 50, // Open after 50% failures
-  resetTimeout: 30000, // Try again after 30s
-});
-
-breaker.fallback(() => ({ data: 'cached-response' }));
-
-const result = await breaker.fire(requestParams);
-```
-
-## Developer Mindset
-
-### Writing Maintainable Code
-
-**SOLID Principles:**
-
-**S - Single Responsibility** - Class/function does one thing
-```typescript
-// Bad: User class handles auth + email + logging
-class User {
-  authenticate() {}
-  sendEmail() {}
-  logActivity() {}
-}
-
-// Good: Separate responsibilities
-class User {
-  authenticate() {}
-}
-class EmailService {
-  sendEmail() {}
-}
-class Logger {
-  logActivity() {}
-}
-```
-
-**O - Open/Closed** - Open for extension, closed for modification
-```typescript
-// Good: Strategy pattern
-interface PaymentStrategy {
-  process(amount: number): Promise<PaymentResult>;
-}
-
-class StripePayment implements PaymentStrategy {
-  async process(amount: number) { /* ... */ }
-}
-
-class PayPalPayment implements PaymentStrategy {
-  async process(amount: number) { /* ... */ }
-}
-```
-
-### Thinking About Edge Cases
-
-**Common Edge Cases:**
-- Empty arrays/collections
-- Null/undefined values
-- Boundary values (min/max integers)
-- Concurrent requests (race conditions)
-- Network failures
-- Duplicate requests (idempotency)
-- Invalid input (SQL injection, XSS)
-
-```typescript
-// Good: Handle edge cases explicitly
-async function getUsers(limit?: number) {
-  // Validate input
-  if (limit !== undefined && (limit < 1 || limit > 1000)) {
-    throw new Error('Limit must be between 1 and 1000');
-  }
-
-  // Handle undefined
-  const safeLimit = limit ?? 50;
-
-  // Prevent SQL injection with parameterized query
-  const users = await db.query('SELECT * FROM users LIMIT $1', [safeLimit]);
-
-  // Handle empty results
-  return users.length > 0 ? users : [];
-}
-```
-
-### Testing Mindset (TDD/BDD)
-
-**70% happy-path tests drafted by AI, humans focus on edge cases**
-
-**Test-Driven Development (TDD):**
-```
-1. Write failing test
-2. Write minimal code to pass
-3. Refactor
-4. Repeat
-```
-
-**Behavior-Driven Development (BDD):**
-```gherkin
-Feature: User Registration
-  Scenario: User registers with valid email
-    Given I am on the registration page
-    When I enter "test@example.com" as email
-    And I enter "SecurePass123!" as password
-    Then I should see "Registration successful"
-    And I should receive a welcome email
-```
-
-### Observability and Debugging Approach
-
-**100% median ROI, $500k average return** from observability investments
-
-**Three Questions:**
-1. **Is it slow?** → Check metrics (response time, DB queries)
-2. **Is it broken?** → Check logs (errors, stack traces)
-3. **Where is it broken?** → Check traces (distributed systems)
-
-```typescript
-// Good: Structured logging with context
-logger.error('Payment processing failed', {
-  orderId: order.id,
-  userId: user.id,
-  amount: order.total,
-  error: error.message,
-  stack: error.stack,
-  timestamp: Date.now(),
-  ipAddress: req.ip,
-});
-```
-
-## Collaboration & Communication
-
-### API Contract Design (Treating APIs as Products)
-
-**Principles:**
-1. **Versioning** - `/api/v1/users`, `/api/v2/users`
-2. **Consistency** - Same patterns across endpoints
-3. **Documentation** - OpenAPI/Swagger
-4. **Backward compatibility** - Don't break existing clients
-5. **Clear error messages** - Help clients fix issues
-
-```typescript
-// Good: Consistent API design
-GET    /api/v1/users         # List users
-GET    /api/v1/users/:id     # Get user
-POST   /api/v1/users         # Create user
-PUT    /api/v1/users/:id     # Update user
-DELETE /api/v1/users/:id     # Delete user
-
-// Consistent error format
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Invalid email format",
-    "field": "email",
-    "timestamp": "2025-01-09T12:00:00Z"
-  }
-}
-```
-
-### Database Schema Design Discussions
-
-**Key Considerations:**
-- **Normalization vs Denormalization** - Trade-offs for performance
-- **Indexing strategy** - Query patterns dictate indexes
-- **Migration path** - How to evolve schema without downtime
-- **Data types** - VARCHAR(255) vs TEXT, INT vs BIGINT
-- **Constraints** - Foreign keys, unique constraints, check constraints
-
-### Code Review Mindset (Prevention-First)
-
-**What to Look For:**
-- Security vulnerabilities (SQL injection, XSS)
-- Performance issues (N+1 queries, missing indexes)
-- Error handling (uncaught exceptions)
-- Edge cases (null checks, boundary values)
-- Readability (naming, comments for complex logic)
-- Tests (coverage for new code)
-
-**Constructive Feedback:**
-```
-# Good review comment
-"This could be vulnerable to SQL injection. Consider using parameterized queries:
-`db.query('SELECT * FROM users WHERE id = $1', [userId])`"
-
-# Bad review comment
-"This is wrong. Fix it."
-```
-
-## Mindset Checklist
-
-- [ ] Think in systems (understand dependencies)
-- [ ] Analyze trade-offs (CAP, performance vs maintainability)
-- [ ] Design for failure (circuit breakers, retries)
-- [ ] Apply SOLID principles
-- [ ] Consider edge cases (null, empty, boundaries)
-- [ ] Write tests first (TDD/BDD)
-- [ ] Log with context (structured logging)
-- [ ] Design APIs as products (versioning, docs)
-- [ ] Plan database schema evolution
-- [ ] Give constructive code reviews
-
-## Resources
-
-- **Domain-Driven Design:** https://martinfowler.com/bliki/DomainDrivenDesign.html
-- **CAP Theorem:** https://en.wikipedia.org/wiki/CAP_theorem
-- **SOLID Principles:** https://en.wikipedia.org/wiki/SOLID
-- **Resilience Patterns:** https://docs.microsoft.com/en-us/azure/architecture/patterns/