Files
skills/public/engineering-rfc-technical-design.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

621 lines
41 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>engineering-rfc-technical-design</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/engineering-rfc-technical-design.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/engineering-rfc-technical-design">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/engineering-rfc-technical-design.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>engineering-rfc-technical-design</h1><p class="lede">Architecture proposals, technical diagrams, API design, trade-off analysis, and migration strategies for RFCs</p><h1>RFC Technical Design</h1>
<p><strong>Scope</strong>: Techniques for designing architecture, evaluating alternatives, creating technical diagrams, and planning migrations <strong>Lines</strong>: ~340 <strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Designing system architecture for a new feature or service</li><li>Evaluating multiple technical approaches and trade-offs</li><li>Creating technical diagrams (architecture, sequence, data flow)</li><li>Designing APIs (REST, GraphQL, gRPC) with versioning and compatibility</li><li>Planning database schema changes or migrations</li><li>Defining rollout strategies for new systems or migrations</li><li>Analyzing performance, scalability, and reliability trade-offs</li><li>Documenting technical decisions with quantitative justification</li></ul>
<h2>Core Concepts</h2>
<h3>Concept 1: Architecture Design Levels (C4 Model)</h3>
<p><strong>Level 1: System Context</strong></p>
<ul><li>High-level view: System + external dependencies</li><li>Audience: Non-technical stakeholders</li><li>Example: &quot;Web App talks to Stripe, SendGrid, and PostgreSQL&quot;</li></ul>
<p><strong>Level 2: Container Diagram</strong></p>
<ul><li>Major components (services, databases, message queues)</li><li>Audience: Architects, senior engineers</li><li>Example: &quot;API Server, Worker Queue, Redis Cache, Postgres DB&quot;</li></ul>
<p><strong>Level 3: Component Diagram</strong></p>
<ul><li>Internal structure of a container (modules, classes)</li><li>Audience: Engineers implementing the system</li><li>Example: &quot;API Server has Auth, User, Project modules&quot;</li></ul>
<p><strong>Level 4: Code Diagram</strong></p>
<ul><li>Class diagrams, sequence diagrams (optional)</li><li>Audience: Engineers debugging or extending code</li></ul>
<h3>Concept 2: Trade-Off Analysis Framework</h3>
<p><strong>Evaluation Dimensions</strong>:</p>
<ul><li><strong>Performance</strong>: Latency, throughput, resource usage</li><li><strong>Scalability</strong>: Horizontal vs vertical, growth limits</li><li><strong>Complexity</strong>: Development time, maintenance burden</li><li><strong>Cost</strong>: Infrastructure, licensing, operational overhead</li><li><strong>Reliability</strong>: Fault tolerance, recovery, uptime</li><li><strong>Maintainability</strong>: Code clarity, debugging, extensibility</li></ul>
<p><strong>Quantification</strong>: Always include numbers where possible</p>
<ul><li>&quot;50% faster&quot; vs &quot;faster&quot;</li><li>&quot;$500/month at 10k users&quot; vs &quot;expensive&quot;</li><li>&quot;2 weeks development&quot; vs &quot;takes time&quot;</li></ul>
<h3>Concept 3: API Design Principles</h3>
<p><strong>Versioning Strategies</strong>:</p>
<ul><li>URI versioning: <code>/api/v1/users</code>, <code>/api/v2/users</code></li><li>Header versioning: <code>Accept: application/vnd.api+json; version=1</code></li><li>Deprecation timeline: Announce → Grace period → Sunset</li></ul>
<p><strong>Backwards Compatibility</strong>:</p>
<ul><li>Add fields, don&#x27;t remove (deprecate instead)</li><li>Use optional parameters (don&#x27;t require new fields)</li><li>Version breaking changes (new endpoints)</li></ul>
<p><strong>Error Handling</strong>:</p>
<ul><li>Use HTTP status codes correctly (200, 201, 400, 401, 404, 500)</li><li>Return structured errors (error_code, message, field_errors)</li><li>Include request_id for debugging</li></ul>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Architecture Diagram (C4 Level 2 - Container)</h3>
<p><strong>When to use</strong>:</p>
<ul><li>Designing system architecture for RFC</li><li>Illustrating component interactions</li></ul>
<pre><code class="lang-markdown">## System Architecture: Real-Time Analytics Platform
### Container Diagram (C4 Level 2)
</code></pre>
<p>┌─────────────────────────────────────────────────────────────────┐ │ User Clients │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Web │ │ Mobile │ │ API │ │ │ │ Client │ │ App │ │ Client │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ └─────────┼─────────────────────┼──────────────────────┼───────────┘ │ │ │ │ HTTPS │ HTTPS │ HTTPS │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Load Balancer (NGINX) │ └────────────────────────────┬────────────────────────────────────┘ │ ┌──────────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ API Server │ │ API Server │ │ API Server │ │ (Node.js) │ │ (Node.js) │ │ (Node.js) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ ├──────────────────┴──────────────────┤ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ Redis │ │ RabbitMQ │ │ Cache │ │ Queue │ │ │ │ │ └─────────────┘ └──────┬──────┘ │ │ ▼ ┌──────────────┐ │ Worker │ │ Processes │ │ (Python) │ └──────┬───────┘ │ ┌─────────────────────────────────────┤ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ PostgreSQL │ │ S3 Bucket │ │ Database │ │ (Logs) │ │ │ │ │ └─────────────┘ └─────────────┘</p>
<pre><code>
### Component Responsibilities
**Load Balancer (NGINX)**:
- Distributes traffic across API servers (round-robin)
- Terminates SSL/TLS
- Rate limiting (1000 req/min per IP)
**API Server (Node.js + Express)**:
- Handles HTTP requests
- Authentication/authorization (JWT)
- Business logic
- Publishes jobs to RabbitMQ
**Redis Cache**:
- Session storage (JWT tokens)
- Query result caching (TTL: 5 min)
- Rate limit counters
**RabbitMQ Queue**:
- Async job processing (reports, exports)
- Decouples API from heavy workloads
**Worker Processes (Python)**:
- Consumes jobs from RabbitMQ
- Generates reports, processes data
- Uploads results to S3
**PostgreSQL Database**:
- Primary data store (users, projects, analytics)
- ACID transactions
- Read replicas for analytics queries
**S3 Bucket**:
- Stores generated reports, exports
- CloudFront CDN for fast delivery</code></pre>
<h3>Pattern 2: Sequence Diagram for Complex Workflows</h3>
<p><strong>Use case</strong>: Illustrating multi-step interactions</p>
<pre><code class="lang-markdown">## Sequence Diagram: User Signup Flow
</code></pre>
<p>Client API Server Database SendGrid │ │ │ │ │ POST /signup │ │ │ ├────────────────&gt;│ │ │ │ │ │ │ │ │ Validate │ │ │ │ email/password│ │ │ │ │ │ │ │ Check if │ │ │ │ email exists │ │ │ ├──────────────&gt;│ │ │ │&lt;──────────────┤ │ │ │ (not found) │ │ │ │ │ │ │ │ Create user │ │ │ ├──────────────&gt;│ │ │ │&lt;──────────────┤ │ │ │ (user_id) │ │ │ │ │ │ │ │ Generate │ │ │ │ verify token │ │ │ │ │ │ │ │ Send verification email │ │ ├─────────────────────────────&gt;│ │ │&lt;─────────────────────────────┤ │ │ (200 OK) │ │ │ │ │ │ 201 Created │ │ │ │&lt;────────────────┤ │ │ │ {user_id, ...} │ │ │ │ │ │ │ │ │ │ Email │ │ │ │ delivered │ │ │ │ to user │ │ │ │ │</p>
<pre><code>
### Error Scenario: Email Already Exists
</code></pre>
<p>Client API Server Database │ │ │ │ POST /signup │ │ ├────────────────&gt;│ │ │ │ Check email │ │ ├──────────────&gt;│ │ │&lt;──────────────┤ │ │ (found!) │ │ │ │ │ 400 Bad Req │ │ │&lt;────────────────┤ │ │ {error_code: │ │ │ EMAIL_IN_USE} │ │</p>
<pre><code></code></pre>
<h3>Pattern 3: Trade-Off Matrix for Alternatives</h3>
<p><strong>Use case</strong>: Comparing technical approaches objectively</p>
<pre><code class="lang-markdown">## Trade-Off Analysis: Caching Strategy
### Options Evaluated
| Criterion | Redis (In-Memory) | Postgres (DB Cache) | Memcached | CDN (CloudFront) |
|-----------|-------------------|---------------------|-----------|------------------|
| **Latency** | &lt;1ms (local) | ~10ms (network) | &lt;1ms (local) | ~50ms (edge) |
| **Scalability** | Horizontal (sharding) | Vertical (limited) | Horizontal | Infinite |
| **Persistence** | Optional (RDB/AOF) | Yes (durable) | No (memory only) | No (edge cache) |
| **Complexity** | Medium (setup cluster) | Low (already have DB) | Low (simple) | Medium (CDN config) |
| **Cost** | $50/mo (10GB instance) | $0 (included) | $30/mo (5GB) | $0.02/GB (traffic) |
| **Use Case Fit** | Session + query cache | Small datasets | Session only | Static assets |
| **Max TTL** | Custom (hours) | Custom (hours) | 30 days | 1 year |
### Decision: Redis
**Chosen**: Redis (in-memory cache with persistence)
**Rationale**:
- **Latency**: &lt;1ms meets requirement (&lt;10ms)
- **Scalability**: Can shard by cache key if needed (10k→100k users)
- **Persistence**: RDB snapshots prevent cache stampede on restart
- **Cost**: $50/mo acceptable for performance gain (vs $0 DB cache, but 10x slower)
- **Flexibility**: Supports sessions, query cache, rate limiting, pub/sub
**Runner-Up**: Postgres materialized views (for read-heavy analytics only)
**Rejected**:
- **Memcached**: No persistence (unacceptable for rate limiting data)
- **CDN**: Only for static assets (API responses are dynamic)</code></pre>
<h3>Pattern 4: API Design with Versioning</h3>
<p><strong>Use case</strong>: Designing RESTful API with backwards compatibility</p>
<pre><code class="lang-markdown">## API Design: User Management
### Base URL
- Production: `https://api.example.com`
- Staging: `https://api-staging.example.com`
### Versioning Strategy
- URI versioning: `/v1/users`, `/v2/users`
- Current version: `v1`
- Deprecation policy: 12 months notice, 6 months grace period
### Endpoints
#### `POST /v1/users` - Create User
**Request**:</code></pre>
<p>{ &quot;email&quot;: &quot;[email protected]&quot;, &quot;password&quot;: &quot;SecurePass1!&quot;, &quot;display_name&quot;: &quot;John Doe&quot; // optional }</p>
<pre><code>
**Response (201 Created)**:</code></pre>
<p>{ &quot;user_id&quot;: &quot;usr_abc123&quot;, &quot;email&quot;: &quot;[email protected]&quot;, &quot;display_name&quot;: &quot;John Doe&quot;, &quot;created_at&quot;: &quot;2025-10-25T14:30:00Z&quot; }</p>
<pre><code>
**Response (400 Bad Request)**:</code></pre>
<p>{ &quot;error_code&quot;: &quot;VALIDATION_ERROR&quot;, &quot;error_message&quot;: &quot;Invalid input&quot;, &quot;request_id&quot;: &quot;req_xyz789&quot;, &quot;field_errors&quot;: { &quot;email&quot;: &quot;Email already in use&quot;, &quot;password&quot;: &quot;Password must include a number&quot; } }</p>
<pre><code>
**Rate Limiting**:
- 5 signups per IP per hour
- Headers: `X-RateLimit-Limit: 5`, `X-RateLimit-Remaining: 3`
#### `GET /v1/users/:id` - Get User Profile
**Authentication**: Required (JWT in `Authorization: Bearer &lt;token&gt;`)
**Response (200 OK)**:</code></pre>
<p>{ &quot;user_id&quot;: &quot;usr_abc123&quot;, &quot;email&quot;: &quot;[email protected]&quot;, &quot;display_name&quot;: &quot;John Doe&quot;, &quot;profile_photo_url&quot;: &quot;https://cdn.example.com/photos/abc123.jpg&quot;, &quot;created_at&quot;: &quot;2025-10-25T14:30:00Z&quot;, &quot;preferences&quot;: { &quot;theme&quot;: &quot;dark&quot;, &quot;notifications&quot;: true } }</p>
<pre><code>
**Response (404 Not Found)**:</code></pre>
<p>{ &quot;error_code&quot;: &quot;USER_NOT_FOUND&quot;, &quot;error_message&quot;: &quot;User with ID usr_abc123 not found&quot;, &quot;request_id&quot;: &quot;req_xyz789&quot; }</p>
<pre><code>
### Breaking Change Example (v1 → v2)
**v1**: Returns `created_at` as Unix timestamp (integer)</code></pre>
<p>{&quot;created_at&quot;: 1698249600}</p>
<pre><code>
**v2**: Returns `created_at` as ISO 8601 string (breaking change)</code></pre>
<p>{&quot;created_at&quot;: &quot;2025-10-25T14:30:00Z&quot;}</p>
<pre><code>
**Migration Plan**:
1. Announce deprecation: 2025-11-01 (email, docs, changelog)
2. Grace period: v1 supported until 2026-05-01 (6 months)
3. Sunset: v1 returns 410 Gone after 2026-05-01</code></pre>
<h3>Pattern 5: Database Schema Design with Migrations</h3>
<p><strong>Use case</strong>: Planning schema changes with rollback strategy</p>
<pre><code class="lang-markdown">## Database Schema: User Authentication
### Current Schema (v1)</code></pre>
<p>CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT NOW() );</p>
<pre><code>
### Proposed Schema (v2) - Add Email Verification</code></pre>
<p>-- Migration: Add email verification columns ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE, ADD COLUMN email_verify_token VARCHAR(255), ADD COLUMN email_verify_sent_at TIMESTAMP;</p>
<p>-- Create index for fast token lookup CREATE INDEX idx_users_verify_token ON users(email_verify_token) WHERE email_verify_token IS NOT NULL;</p>
<p>-- Backfill existing users (mark as verified) UPDATE users SET email_verified = TRUE WHERE created_at &lt; NOW();</p>
<pre><code>
### Migration Plan
**Step 1: Deploy Schema Change** (Zero Downtime)
- Run `ALTER TABLE` during low-traffic window
- PostgreSQL locks table briefly (&lt;1s for 100k rows)
- Backfill existing users as verified (no behavior change)
**Step 2: Deploy Code Changes**
- New signups: Set `email_verified = FALSE`, send verification email
- Login: Check `email_verified`, block if false
- Feature flag: `REQUIRE_EMAIL_VERIFICATION` (gradual rollout)
**Step 3: Monitor**
- Track verification rate (target: 80% verify within 24 hours)
- Monitor support tickets (expect questions)
- Alert if verification email delivery rate &lt;95%
**Rollback Plan**:
- Revert code: Disable `REQUIRE_EMAIL_VERIFICATION` flag
- Keep schema changes (no need to drop columns, just stop using)
- If catastrophic: Drop columns (loses verification data)</code></pre>
<h3>Pattern 6: Migration Strategy (Old System → New System)</h3>
<p><strong>Use case</strong>: Transitioning between systems with zero downtime</p>
<pre><code class="lang-markdown">## Migration: Monolith → Microservices (Auth Service)
### Current State
- Monolithic Rails app handles everything (auth, users, projects)
- Auth logic mixed with business logic (tight coupling)
- 100k active users, 10k requests/min peak
### Target State
- Standalone Auth Service (Node.js + JWT)
- Microservices for users, projects (separate from auth)
- Same 100k users, seamless migration
### Migration Strategy: Strangler Fig Pattern
**Phase 1: Build Auth Service (Parallel Run)**
- Build new Auth Service (JWT-based)
- Dual-write: Monolith writes to both old session DB and new Auth Service
- Read from old system only (no behavior change)
- Duration: 2 weeks
**Phase 2: Shadow Traffic**
- Route 1% of login requests to Auth Service (shadow mode)
- Compare results with monolith (validate correctness)
- Fix discrepancies, increase to 10%, then 50%
- Duration: 2 weeks
**Phase 3: Gradual Cutover**
- Route 10% of users to Auth Service (read + write)
- Monitor latency, error rates, user complaints
- Increase to 50%, then 100% over 4 weeks
- Duration: 4 weeks
**Phase 4: Monolith Deprecation**
- All auth traffic goes to Auth Service
- Remove auth code from monolith (dead code)
- Decommission old session database
- Duration: 2 weeks
### Rollback Plan
- Feature flag: `USE_AUTH_SERVICE` (toggle per user)
- If Auth Service fails, revert flag → monolith
- Monitoring: Alert if Auth Service latency &gt;100ms or error rate &gt;1%
### Metrics
- **Latency**: Auth Service &lt;50ms (vs monolith 80ms)
- **Error Rate**: &lt;0.1% (vs monolith 0.2%)
- **User Impact**: Zero failed logins during migration</code></pre>
<h3>Pattern 7: Performance Benchmarking</h3>
<p><strong>Use case</strong>: Quantifying trade-offs with real data</p>
<pre><code class="lang-markdown">## Performance Benchmark: Caching Strategy
### Test Setup
- Dataset: 1M user records
- Query: `GET /users/:id/profile` (fetch user + projects)
- Load: 1,000 requests/sec (sustained)
- Tool: Apache Bench (`ab -n 10000 -c 100`)
### Results
| Approach | p50 Latency | p95 Latency | p99 Latency | Throughput | CPU Usage |
|----------|-------------|-------------|-------------|------------|-----------|
| **No Cache** (baseline) | 120ms | 350ms | 850ms | 800 req/s | 80% |
| **Redis Cache** | 8ms | 15ms | 45ms | 8,000 req/s | 20% |
| **Postgres Materialized View** | 25ms | 60ms | 150ms | 3,000 req/s | 40% |
| **In-Memory Map** (Node.js) | 2ms | 5ms | 12ms | 10,000 req/s | 30% |
### Analysis
**Winner**: Redis Cache (chosen)
- **Latency**: 15x faster than no cache (p95: 15ms vs 350ms) ✅
- **Throughput**: 10x higher (8k vs 800 req/s) ✅
- **Cost**: $50/mo for Redis instance (acceptable)
- **Risk**: Single point of failure (mitigated with Redis Sentinel)
**Runner-Up**: In-Memory Map
- **Faster**: 2ms latency, 10k req/s
- **Problem**: No persistence (lost on restart), no sharing across servers
- **Verdict**: Only viable for single-server deployment
**Rejected**: Postgres Materialized View
- **Reason**: Still 25ms latency (vs &lt;10ms requirement)
- **Use Case**: Good for analytics, not real-time API</code></pre>
<h3>Pattern 8: Failure Mode Analysis</h3>
<p><strong>Use case</strong>: Anticipating what can go wrong</p>
<pre><code class="lang-markdown">## Failure Mode Analysis: Payment Processing
### Failure Scenarios
#### 1. Stripe API Down
**Probability**: Low (99.99% uptime SLA)
**Impact**: High (no payments processed)
**Mitigation**:
- Detect: Health check every 30s, alert if 3 failures
- Respond: Show maintenance page, queue payment attempts
- Recover: Retry queued payments when Stripe recovers
#### 2. Database Connection Pool Exhausted
**Probability**: Medium (under high load)
**Impact**: High (API returns 500 errors)
**Mitigation**:
- Prevent: Set connection pool limit (50 connections)
- Detect: Monitor active connections (alert if &gt;80%)
- Respond: Reject new requests with 503 (retry-after header)
- Recover: Scale database read replicas, optimize queries
#### 3. Redis Cache Eviction
**Probability**: Medium (if cache fills up)
**Impact**: Low (fallback to database, slower but works)
**Mitigation**:
- Prevent: Set max memory limit, use LRU eviction policy
- Detect: Monitor cache hit rate (alert if &lt;80%)
- Respond: Cache miss → fetch from DB, repopulate cache
- Recover: Increase Redis memory, optimize cache keys
#### 4. Webhook Delivery Failure
**Probability**: High (network issues, client downtime)
**Impact**: Medium (events not processed by client)
**Mitigation**:
- Detect: HTTP status != 200 or timeout (&gt;30s)
- Respond: Exponential backoff retry (1s, 2s, 4s, 8s, 16s)
- Recover: Dead letter queue after 5 failures, alert for manual review
### Circuit Breaker Pattern</code></pre>
<p>// Protect against cascading failures class CircuitBreaker { constructor(failureThreshold = 5, timeout = 60000) { this.failureCount = 0; this.failureThreshold = failureThreshold; this.timeout = timeout; this.state = &#x27;CLOSED&#x27;; // CLOSED, OPEN, HALF_OPEN }</p>
<p> async call(fn) { if (this.state === &#x27;OPEN&#x27;) { throw new Error(&#x27;Circuit breaker is OPEN&#x27;); }</p>
<p> try { const result = await fn(); this.onSuccess(); return result; } catch (error) { this.onFailure(); throw error; } }</p>
<p> onSuccess() { this.failureCount = 0; this.state = &#x27;CLOSED&#x27;; }</p>
<p> onFailure() { this.failureCount++; if (this.failureCount &gt;= this.failureThreshold) { this.state = &#x27;OPEN&#x27;; setTimeout(() =&gt; { this.state = &#x27;HALF_OPEN&#x27;; }, this.timeout); } } }</p>
<p>// Usage: Protect Stripe API calls const stripeBreaker = new CircuitBreaker(5, 60000); const charge = await stripeBreaker.call(() =&gt; stripe.charges.create({...}));</p>
<pre><code></code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Architecture Diagram Types</h3>
<pre><code>Diagram Type | Use Case | Audience
-------------|----------|----------
System Context (C4-1) | High-level overview | Leadership, PM
Container (C4-2) | Major components | Architects, senior eng
Component (C4-3) | Internal structure | Engineers
Sequence | Multi-step workflows | Engineers debugging
Data Flow | Data movement | Data engineers</code></pre>
<h3>Trade-Off Evaluation Checklist</h3>
<pre><code>Dimension | Question to Ask
----------|----------------
Performance | What is p95 latency? Throughput?
Scalability | How does it scale? (horizontal/vertical)
Complexity | How long to implement? Maintain?
Cost | $ per month at 10k users? At 100k?
Reliability | What&#x27;s uptime SLA? Failure modes?
Maintainability | How easy to debug? Extend?</code></pre>
<h3>API Versioning Strategies</h3>
<pre><code>Strategy | Example | Pros | Cons
---------|---------|------|-----
URI | /v1/users | Simple, explicit | URL proliferation
Header | Accept: v=1 | Clean URLs | Less visible
Query Param | /users?v=1 | Easy to test | Ugly URLs</code></pre>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: Quantify trade-offs (numbers, not adjectives)
✅ DO: Create diagrams for complex architectures
✅ DO: Benchmark alternatives with real data
✅ DO: Plan failure modes and mitigations
✅ DO: Design APIs with backwards compatibility
❌ DON&#x27;T: Pick solutions without evaluating alternatives
❌ DON&#x27;T: Use vague terms (&quot;fast&quot;, &quot;scalable&quot;) without metrics
❌ DON&#x27;T: Ignore migration complexity
❌ DON&#x27;T: Skip performance benchmarking
❌ DON&#x27;T: Design APIs without versioning strategy</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Critical Violations</h3>
<p>❌ <strong>No Alternatives Analysis</strong>: Presenting one solution without comparison</p>
<pre><code class="lang-markdown"># ❌ NEVER:
We&#x27;ll use MongoDB for the database.
# ✅ CORRECT:
## Database Options
1. **PostgreSQL**: ACID, relations, complex queries (chosen)
2. **MongoDB**: Flexible schema, horizontal scaling
- Rejected: No ACID for financial transactions (deal-breaker)
3. **DynamoDB**: Managed, infinite scale
- Rejected: Vendor lock-in, limited query flexibility
**Decision**: Postgres for ACID guarantees and query richness.</code></pre>
<p>❌ <strong>Premature Optimization</strong>: Optimizing without measuring ✅ <strong>Correct approach</strong>: Benchmark current performance, identify bottleneck, optimize</p>
<h3>Common Mistakes</h3>
<p>❌ <strong>Vague Performance Claims</strong>: &quot;Redis is faster than Postgres&quot;</p>
<pre><code class="lang-markdown"># ❌ Don&#x27;t:
Redis is faster, so we&#x27;ll use it for caching.
# ✅ Correct:
## Benchmark Results
- Redis: 8ms p95 latency, 8k req/s throughput
- Postgres: 120ms p95 latency, 800 req/s throughput
- **Decision**: Redis for 15x latency improvement</code></pre>
<p>❌ <strong>No Failure Analysis</strong>: Assuming happy path only ✅ <strong>Better</strong>: Document failure modes, circuit breakers, fallbacks</p>
<p>❌ <strong>API Without Versioning</strong>: No plan for breaking changes ✅ <strong>Better</strong>: URI versioning, deprecation policy, migration guide</p>
<p>❌ <strong>Big Bang Migration</strong>: Switching all users at once ✅ <strong>Better</strong>: Strangler fig pattern (gradual cutover with rollback plan)</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>rfc-structure-format.md</code> - RFC document templates and formatting</li><li><code>rfc-consensus-building.md</code> - Driving approval for technical designs</li><li><code>rfc-decision-documentation.md</code> - Documenting decisions and ADRs</li><li><code>api-design-rest.md</code> - Deep dive on REST API best practices</li><li><code>database-postgres-optimization.md</code> - Postgres-specific performance tuning</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/engineering-rfc-technical-design.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>