mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
731 lines
34 KiB
HTML
731 lines
34 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-decision-documentation</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-decision-documentation.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/engineering-rfc-decision-documentation">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/engineering-rfc-decision-documentation.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-decision-documentation</h1><p class="lede">Architecture Decision Records (ADRs), decision rationale, status tracking, and post-implementation review</p><h1>RFC Decision Documentation</h1>
|
|
<p><strong>Scope</strong>: Documenting architectural decisions, tracking status, maintaining decision history, and post-implementation review <strong>Lines</strong>: ~320 <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>Creating Architecture Decision Records (ADRs) for significant decisions</li><li>Documenting decision rationale (why we chose X over Y)</li><li>Tracking RFC status (proposed, accepted, deprecated, superseded)</li><li>Maintaining a changelog of RFC updates during review</li><li>Using DACI framework to clarify decision-making roles</li><li>Conducting post-implementation reviews (retrospectives on decisions)</li><li>Managing decision deprecation (when decisions become obsolete)</li><li>Creating searchable decision history for future reference</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Concept 1: Architecture Decision Records (ADRs)</h3>
|
|
<p><strong>Purpose</strong>: Lightweight documentation of significant architectural decisions <strong>Format</strong>: Markdown file in <code>docs/adr/</code> or <code>adr/</code> directory <strong>Naming</strong>: <code>ADR-NNN-title-in-kebab-case.md</code> (e.g., <code>ADR-005-use-postgres-over-mongodb.md</code>)</p>
|
|
<p><strong>When to Write an ADR</strong>:</p>
|
|
<ul><li>Choosing technology (database, framework, cloud provider)</li><li>Architectural pattern (microservices, monolith, event-driven)</li><li>Security approach (OAuth, JWT, session-based auth)</li><li>Data storage strategy (relational, NoSQL, caching)</li><li>Any decision with long-term impact (hard to reverse)</li></ul>
|
|
<p><strong>When NOT to Write an ADR</strong>:</p>
|
|
<ul><li>Routine code changes (refactoring, bug fixes)</li><li>Tactical decisions (variable naming, file organization)</li><li>Decisions easily reversed (UI colors, button labels)</li></ul>
|
|
<h3>Concept 2: Decision Status Lifecycle</h3>
|
|
<p><strong>Status Flow</strong>:</p>
|
|
<pre><code>Proposed → Accepted → Implemented → [Deprecated | Superseded]
|
|
↓
|
|
Rejected</code></pre>
|
|
<p><strong>Proposed</strong>: Decision is being considered, not yet approved <strong>Accepted</strong>: Decision approved, ready for implementation <strong>Implemented</strong>: Decision has been built and deployed <strong>Deprecated</strong>: Decision no longer valid (context changed) <strong>Superseded</strong>: Replaced by newer decision (link to new ADR) <strong>Rejected</strong>: Decision not accepted (document why)</p>
|
|
<h3>Concept 3: Decision Rationale Components</h3>
|
|
<p><strong>Context</strong>: What circumstances led to this decision? <strong>Options Considered</strong>: What alternatives were evaluated? <strong>Decision</strong>: What did we choose? <strong>Rationale</strong>: Why did we choose this? (trade-offs, constraints) <strong>Consequences</strong>: What are the positive, negative, neutral outcomes? <strong>Related Decisions</strong>: What other decisions does this affect?</p>
|
|
<hr>
|
|
<h2>Patterns</h2>
|
|
<h3>Pattern 1: ADR Template (Minimal)</h3>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Documenting single architectural decision</li><li>Quick reference for future engineers</li></ul>
|
|
<pre><code class="lang-markdown"># ADR-012: Use JWT for API Authentication
|
|
|
|
**Date**: 2025-10-25
|
|
**Status**: Accepted
|
|
**Deciders**: @alice (backend lead), @bob (security)
|
|
|
|
## Context
|
|
We need to authenticate API requests from web and mobile clients.
|
|
Current system uses session cookies (server-side state, doesn't scale).
|
|
|
|
Requirements:
|
|
- Stateless authentication (no server-side sessions)
|
|
- Works for web and mobile
|
|
- Support for token expiration and refresh
|
|
|
|
## Decision
|
|
We will use **JWT (JSON Web Tokens)** for API authentication.
|
|
|
|
## Rationale
|
|
- **Stateless**: No server-side session storage (scales horizontally)
|
|
- **Cross-platform**: Works for web, mobile, and third-party API clients
|
|
- **Standard**: Well-documented, many libraries available
|
|
- **Expiration**: Built-in expiry (`exp` claim), supports refresh tokens
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Horizontal scaling: No session replication needed
|
|
- Faster authentication: No database lookup per request
|
|
- Mobile-friendly: Tokens stored in app, not cookies
|
|
|
|
### Negative
|
|
- Token size: ~200 bytes vs 32-byte session ID (acceptable overhead)
|
|
- Revocation: Cannot invalidate token before expiry (mitigated with short TTL + refresh tokens)
|
|
- Secret management: Must protect JWT signing secret (use env vars, rotate regularly)
|
|
|
|
### Neutral
|
|
- Need to implement token refresh logic (standard pattern)
|
|
- Must validate tokens on every request (minimal CPU overhead)
|
|
|
|
## Alternatives Considered
|
|
|
|
### Session-based Auth (Current System)
|
|
**Pros**: Simple, easy to revoke
|
|
**Cons**: Server-side state, doesn't scale horizontally, not mobile-friendly
|
|
**Rejected**: Scalability requirement
|
|
|
|
### OAuth 2.0
|
|
**Pros**: Industry standard, supports third-party login
|
|
**Cons**: Complex for our use case (overkill for internal API)
|
|
**Deferred**: Consider for future third-party integrations
|
|
|
|
### API Keys
|
|
**Pros**: Simple, long-lived
|
|
**Cons**: No expiration, hard to rotate, security risk
|
|
**Rejected**: No built-in expiration mechanism</code></pre>
|
|
<h3>Pattern 2: ADR with DACI Framework</h3>
|
|
<p><strong>Use case</strong>: Complex decision requiring clear accountability</p>
|
|
<pre><code class="lang-markdown"># ADR-018: Migrate from Monolith to Microservices
|
|
|
|
**Date**: 2025-10-25
|
|
**Status**: Accepted
|
|
**Last Updated**: 2025-10-26
|
|
|
|
## DACI
|
|
|
|
**Driver**: @alex (backend architect)
|
|
- Responsible for RFC and implementation plan
|
|
|
|
**Approver**: @cto
|
|
- Final decision authority
|
|
- Accountable for outcome
|
|
|
|
**Contributors**:
|
|
- @jordan (backend lead): Technical feasibility
|
|
- @taylor (DevOps): Infrastructure and deployment
|
|
- @sam (product): Product impact and timeline
|
|
|
|
**Informed**:
|
|
- [email protected]
|
|
- [email protected]
|
|
|
|
## Context
|
|
Current monolithic Rails app is becoming difficult to scale and maintain:
|
|
- Deployment takes 30+ minutes (affects release velocity)
|
|
- Tight coupling makes bug fixes risky (change one feature, break another)
|
|
- Team growth is bottlenecked (merge conflicts, slow tests)
|
|
- Database queries are slow (N+1 problems, no caching)
|
|
|
|
Goals:
|
|
- Improve deployment speed (target: <5 min per service)
|
|
- Enable independent team scaling (3 teams, 15 engineers)
|
|
- Reduce blast radius of bugs (isolate failures)
|
|
|
|
## Decision
|
|
We will **gradually migrate** from monolith to microservices using the Strangler Fig pattern.
|
|
|
|
**Phase 1**: Extract Auth Service (Q1 2025)
|
|
**Phase 2**: Extract User Service (Q2 2025)
|
|
**Phase 3**: Extract Project Service (Q3 2025)
|
|
|
|
## Rationale
|
|
- **Gradual migration**: Reduces risk vs big-bang rewrite
|
|
- **Strangler Fig**: Proven pattern (Netflix, Airbnb successfully used)
|
|
- **Start small**: Auth Service is well-isolated, low risk
|
|
- **Team autonomy**: Each service can be owned by a team (clear boundaries)
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Faster deployments: 5 min per service vs 30 min monolith
|
|
- Independent scaling: Scale auth separately from other services
|
|
- Team autonomy: Teams can deploy independently (no coordination)
|
|
- Technology flexibility: Can use different languages/frameworks per service
|
|
|
|
### Negative
|
|
- Complexity: Distributed systems (service discovery, tracing)
|
|
- Cost: More infrastructure (3 services vs 1 monolith)
|
|
- Estimated: $500/mo → $1,200/mo (2.4x increase)
|
|
- Debugging: Cross-service issues harder to debug (need distributed tracing)
|
|
- Data consistency: Eventual consistency (no ACID across services)
|
|
|
|
### Neutral
|
|
- Learning curve: Team needs to learn Kubernetes, service mesh
|
|
- Operational overhead: More services to monitor and maintain
|
|
- Network latency: Service-to-service calls add ~10ms overhead
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| Migration takes too long | High | Timebox to 9 months, cancel if not on track |
|
|
| Data consistency issues | High | Use event sourcing for critical workflows |
|
|
| Cost overruns | Medium | Monitor monthly, optimize resource usage |
|
|
| Team expertise gap | Medium | Hire DevOps engineer, training budget |
|
|
|
|
## Alternatives Considered
|
|
|
|
### Continue with Monolith
|
|
**Pros**: No migration cost, simpler operations
|
|
**Cons**: Doesn't solve scaling, deployment, team autonomy problems
|
|
**Rejected**: Problems will worsen as team grows
|
|
|
|
### Modular Monolith
|
|
**Pros**: Logical separation, single deployment
|
|
**Cons**: Still have deployment bottleneck, doesn't solve scaling
|
|
**Considered**: Good middle ground, but doesn't meet goals
|
|
|
|
### Full Microservices Rewrite
|
|
**Pros**: Clean slate, modern architecture
|
|
**Cons**: High risk, 12+ months, business disruption
|
|
**Rejected**: Too risky, Strangler Fig is safer
|
|
|
|
## Implementation Plan
|
|
[Link to RFC-042: Microservices Migration Plan]
|
|
|
|
## Post-Implementation Review
|
|
**Scheduled**: 2026-01-15 (3 months after Phase 3 completion)
|
|
**Participants**: @alex, @jordan, @taylor, @sam, @cto
|
|
**Review Questions**:
|
|
- Did we achieve deployment speed goal? (<5 min per service)
|
|
- Did team autonomy improve? (measure: deploy frequency per team)
|
|
- What unexpected issues arose?
|
|
- Would we make the same decision again?</code></pre>
|
|
<h3>Pattern 3: Decision Status Tracking</h3>
|
|
<p><strong>Use case</strong>: Maintaining history of decision lifecycle</p>
|
|
<pre><code class="lang-markdown"># ADR-005: Use PostgreSQL Over MongoDB
|
|
|
|
**Status**: Implemented
|
|
**Created**: 2025-01-15
|
|
**Accepted**: 2025-01-20
|
|
**Implemented**: 2025-02-10
|
|
**Last Reviewed**: 2025-10-25
|
|
|
|
## Status History
|
|
|
|
| Date | Status | Notes |
|
|
|------|--------|-------|
|
|
| 2025-01-15 | Proposed | Initial draft by @alice |
|
|
| 2025-01-17 | In Review | Feedback from @bob, @charlie |
|
|
| 2025-01-20 | Accepted | Approved by @cto after design review |
|
|
| 2025-02-10 | Implemented | Deployed to production |
|
|
| 2025-10-25 | Reviewed | Still valid, no changes needed |
|
|
|
|
## Review Notes (2025-10-25)
|
|
- **Still valid?**: Yes, Postgres continues to meet needs
|
|
- **Performance**: Query latency <50ms (p95), meets SLA
|
|
- **Scalability**: 1.5M users, no scaling issues yet
|
|
- **Would we choose differently?**: No, Postgres was correct choice
|
|
- **Next review**: 2026-04-25 (6 months)</code></pre>
|
|
<h3>Pattern 4: Superseded Decision</h3>
|
|
<p><strong>Use case</strong>: When a decision is replaced by a newer one</p>
|
|
<pre><code class="lang-markdown"># ADR-003: Use Redis for Session Storage
|
|
|
|
**Status**: Superseded by ADR-012 (JWT Authentication)
|
|
**Created**: 2024-06-01
|
|
**Accepted**: 2024-06-10
|
|
**Implemented**: 2024-07-01
|
|
**Superseded**: 2025-10-25
|
|
|
|
## Superseded Notice
|
|
⚠️ **This decision is no longer active.**
|
|
|
|
**Superseded by**: [ADR-012: Use JWT for API Authentication](./ADR-012-use-jwt-for-api-authentication.md)
|
|
|
|
**Reason**: Migrated from session-based auth to stateless JWT auth for better scalability.
|
|
|
|
**Migration**: Completed 2025-10-25. Redis session store decommissioned.
|
|
|
|
---
|
|
|
|
## Original Decision (For Historical Reference)
|
|
|
|
### Context
|
|
We needed server-side session storage for user authentication...
|
|
|
|
[Keep original ADR content for historical reference]</code></pre>
|
|
<h3>Pattern 5: Deprecated Decision</h3>
|
|
<p><strong>Use case</strong>: When context changes and decision is no longer valid</p>
|
|
<pre><code class="lang-markdown"># ADR-008: Deploy on Heroku
|
|
|
|
**Status**: Deprecated (No Longer Valid)
|
|
**Created**: 2023-03-15
|
|
**Accepted**: 2023-03-20
|
|
**Implemented**: 2023-04-01
|
|
**Deprecated**: 2025-06-15
|
|
|
|
## Deprecation Notice
|
|
⚠️ **This decision is no longer valid.**
|
|
|
|
**Deprecated Date**: 2025-06-15
|
|
**Reason**: Company standardized on AWS for all infrastructure.
|
|
|
|
**Current State**: All services migrated to AWS ECS (completed 2025-06-15).
|
|
|
|
**Replacement Decision**: [ADR-025: Standardize on AWS](./ADR-025-standardize-on-aws.md)
|
|
|
|
---
|
|
|
|
## Original Decision (For Historical Context)
|
|
|
|
### Context
|
|
We chose Heroku for fast iteration and minimal DevOps overhead...
|
|
|
|
[Keep original content for reference]</code></pre>
|
|
<h3>Pattern 6: Rejected Decision</h3>
|
|
<p><strong>Use case</strong>: Documenting decisions that were NOT accepted</p>
|
|
<pre><code class="lang-markdown"># ADR-014: Use GraphQL for Public API (REJECTED)
|
|
|
|
**Status**: Rejected
|
|
**Created**: 2025-05-10
|
|
**Rejected**: 2025-05-20
|
|
**Deciders**: @alice (backend lead), @bob (CTO)
|
|
|
|
## Context
|
|
We evaluated GraphQL as an alternative to our REST API for the public API.
|
|
|
|
## Proposal (Rejected)
|
|
Replace REST API with GraphQL to reduce over-fetching and under-fetching.
|
|
|
|
## Rationale for Rejection
|
|
|
|
### Reasons NOT Accepted
|
|
1. **Team expertise**: No GraphQL experience on team (6+ month learning curve)
|
|
2. **Third-party integrations**: Most partners expect REST APIs (not GraphQL)
|
|
3. **Tooling**: Our monitoring/caching infrastructure is REST-optimized
|
|
4. **Client complexity**: Mobile apps would need GraphQL client library (adds weight)
|
|
|
|
### What We Learned
|
|
- Over-fetching is not a significant problem (bandwidth is cheap)
|
|
- Under-fetching can be solved with REST API design (compound endpoints)
|
|
- GraphQL benefits don't justify migration cost for our use case
|
|
|
|
## Alternative Chosen
|
|
Continue with REST API, improve with:
|
|
- Compound endpoints to reduce round-trips (e.g., `/users/:id?include=projects`)
|
|
- Field filtering via query params (e.g., `?fields=name,email`)
|
|
- Better API documentation (OpenAPI/Swagger)
|
|
|
|
## Related Decisions
|
|
- [ADR-006: REST API Design Principles](./ADR-006-rest-api-design-principles.md)
|
|
|
|
## Future Consideration
|
|
If we build a complex web app with diverse data needs, revisit GraphQL.
|
|
**Trigger**: If >10 clients request custom data views.</code></pre>
|
|
<h3>Pattern 7: RFC Changelog</h3>
|
|
<p><strong>Use case</strong>: Tracking changes to RFC during review process</p>
|
|
<pre><code class="lang-markdown"># RFC-042: Real-Time Collaboration
|
|
|
|
[... RFC content ...]
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### Version 1.3 (2025-10-26) - Final
|
|
- **Added**: Security section (rate limiting, auth)
|
|
- **Changed**: WebSocket server from Node.js to Go (better concurrency)
|
|
- **Reason**: Security review feedback from @charlie
|
|
- **Status**: Approved by @cto
|
|
|
|
### Version 1.2 (2025-10-25)
|
|
- **Added**: Failure mode analysis (Redis downtime)
|
|
- **Changed**: Rate limit from 100 to 200 ops/sec
|
|
- **Removed**: Audio/video chat (out of scope)
|
|
- **Reason**: Design review feedback from @jordan, @taylor
|
|
|
|
### Version 1.1 (2025-10-24)
|
|
- **Added**: Cost analysis ($500/mo at 10k users)
|
|
- **Changed**: Alternative approach section (expanded CRDTs analysis)
|
|
- **Reason**: @bob requested cost breakdown
|
|
|
|
### Version 1.0 (2025-10-23) - Initial Draft
|
|
- **Created**: Initial draft by @alex
|
|
- **Sections**: Problem, solution, architecture, alternatives
|
|
|
|
---
|
|
|
|
## Version History Table
|
|
|
|
| Version | Date | Author | Status | Key Changes |
|
|
|---------|------|--------|--------|-------------|
|
|
| 1.3 | 2025-10-26 | @alex | Approved | Security section added |
|
|
| 1.2 | 2025-10-25 | @alex | In Review | Failure modes, rate limit |
|
|
| 1.1 | 2025-10-24 | @alex | In Review | Cost analysis |
|
|
| 1.0 | 2025-10-23 | @alex | Draft | Initial draft |</code></pre>
|
|
<h3>Pattern 8: Post-Implementation Review</h3>
|
|
<p><strong>Use case</strong>: Retrospective after decision is implemented</p>
|
|
<pre><code class="lang-markdown"># Post-Implementation Review: ADR-012 JWT Authentication
|
|
|
|
**Review Date**: 2025-10-25 (6 months post-implementation)
|
|
**Participants**: @alice (backend lead), @bob (security), @charlie (DevOps), @dana (product)
|
|
|
|
## Original Decision (Summary)
|
|
- **Date**: 2025-04-25
|
|
- **Decision**: Migrate from session-based auth to JWT
|
|
- **Rationale**: Stateless, scalable, mobile-friendly
|
|
|
|
## Implementation Timeline
|
|
- **Start**: 2025-05-01
|
|
- **Alpha**: 2025-05-15 (internal testing)
|
|
- **Beta**: 2025-06-01 (10% rollout)
|
|
- **GA**: 2025-06-15 (100% rollout)
|
|
|
|
## Success Metrics (Actual vs Target)
|
|
|
|
| Metric | Target | Actual | Status |
|
|
|--------|--------|--------|--------|
|
|
| API latency reduction | -20ms (p95) | -35ms | ✅ Exceeded |
|
|
| Horizontal scaling | 3x capacity | 5x capacity | ✅ Exceeded |
|
|
| Failed logins (migration) | <1% | 0.3% | ✅ Met |
|
|
| Support tickets (auth issues) | <50 | 12 | ✅ Exceeded |
|
|
|
|
## What Went Well
|
|
1. **Smooth migration**: Dual-write period prevented data loss
|
|
2. **Performance**: Better than expected (-35ms vs -20ms target)
|
|
3. **Scalability**: 5x capacity increase (vs 3x target)
|
|
4. **Minimal user impact**: Only 12 support tickets (vs 50 expected)
|
|
|
|
## What Went Poorly
|
|
1. **Token refresh complexity**: Took 2 weeks longer than estimated
|
|
- Root cause: Edge cases in refresh token rotation
|
|
- Mitigation: Added integration tests for refresh flows
|
|
2. **Secret rotation**: Manual process (should be automated)
|
|
- Action item: Automate JWT secret rotation (ADR-030)
|
|
3. **Mobile token storage**: Security concern (tokens in local storage)
|
|
- Action item: Migrate to secure keychain (iOS) and keystore (Android)
|
|
|
|
## Unexpected Challenges
|
|
- **Third-party integrations**: 3 partners needed JWT support (undiscovered dependency)
|
|
- Resolution: Provided migration guide and support
|
|
- **Token size**: 200-byte tokens caused issues with legacy proxies
|
|
- Resolution: Whitelisted JWT header in proxy config
|
|
|
|
## Lessons Learned
|
|
1. **Dual-write is critical**: Prevented data loss during migration
|
|
2. **Test refresh flows**: Edge cases are tricky, need comprehensive tests
|
|
3. **Automate ops**: Secret rotation should be automated from day 1
|
|
4. **Mobile security**: Token storage needs platform-specific solutions
|
|
|
|
## Would We Make Same Decision?
|
|
**Yes**, JWT was the correct choice.
|
|
|
|
**Rationale**:
|
|
- Performance and scalability benefits exceeded expectations
|
|
- Migration was smooth despite token refresh complexity
|
|
- Would address mobile token storage earlier next time
|
|
|
|
## Follow-Up Actions
|
|
- [ ] **ADR-030**: Automate JWT secret rotation (assigned: @charlie)
|
|
- [ ] **ADR-031**: Migrate mobile to secure token storage (assigned: @alice)
|
|
- [ ] **Documentation**: Update API docs with JWT best practices
|
|
|
|
## Next Review
|
|
**Scheduled**: 2026-04-25 (6 months)
|
|
**Trigger**: If token-related security incidents occur, review immediately</code></pre>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>ADR Checklist</h3>
|
|
<pre><code>Required Sections | Optional Sections
|
|
------------------|------------------
|
|
Date | DACI roles
|
|
Status | Status history
|
|
Context | Related decisions
|
|
Decision | Risks & mitigations
|
|
Rationale | Implementation plan
|
|
Consequences | Post-implementation review
|
|
Alternatives |</code></pre>
|
|
<h3>Decision Status Values</h3>
|
|
<pre><code>Status | Meaning | Next Action
|
|
-------|---------|------------
|
|
Proposed | Being considered | Seek feedback, approve/reject
|
|
Accepted | Approved | Implement
|
|
Implemented | Deployed | Monitor, review
|
|
Deprecated | No longer valid | Link to replacement
|
|
Superseded | Replaced | Link to new decision
|
|
Rejected | Not accepted | Document why</code></pre>
|
|
<h3>When to Write an ADR</h3>
|
|
<pre><code>Write ADR | Don't Write ADR
|
|
----------|----------------
|
|
Technology choice (DB, cloud) | Routine code changes
|
|
Architectural pattern | Variable naming
|
|
Security approach | UI colors/layout
|
|
Data strategy | Bug fixes
|
|
Hard-to-reverse decisions | Easily reversible decisions</code></pre>
|
|
<h3>Post-Implementation Review Questions</h3>
|
|
<pre><code>Question | Purpose
|
|
---------|--------
|
|
Did we achieve goals? | Measure success
|
|
What went well? | Identify strengths
|
|
What went poorly? | Learn from mistakes
|
|
Would we decide the same way? | Validate decision
|
|
What's next? | Plan follow-up actions</code></pre>
|
|
<h3>Key Guidelines</h3>
|
|
<pre><code>✅ DO: Document why, not just what (rationale is critical)
|
|
✅ DO: Include alternatives considered (why not X?)
|
|
✅ DO: Track status changes over time
|
|
✅ DO: Conduct post-implementation reviews (learn from outcomes)
|
|
✅ DO: Link related decisions (create decision graph)
|
|
|
|
❌ DON'T: Skip consequences (positive, negative, neutral)
|
|
❌ DON'T: Forget to update status (proposed → accepted → implemented)
|
|
❌ DON'T: Delete superseded ADRs (keep for historical context)
|
|
❌ DON'T: Write ADRs for trivial decisions
|
|
❌ DON'T: Ignore post-implementation learnings</code></pre>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>Critical Violations</h3>
|
|
<p>❌ <strong>Decision Without Rationale</strong>: "We chose X" without explaining why</p>
|
|
<pre><code class="lang-markdown"># ❌ NEVER:
|
|
## Decision
|
|
We will use PostgreSQL.
|
|
|
|
# ✅ CORRECT:
|
|
## Decision
|
|
We will use PostgreSQL.
|
|
|
|
## Rationale
|
|
- ACID transactions required for billing (compliance)
|
|
- Rich query capabilities (JOINs, window functions)
|
|
- Team expertise (all backend engineers know SQL)
|
|
- Proven scalability (read replicas, partitioning)
|
|
|
|
## Alternatives Considered
|
|
- MongoDB: Flexible schema, but no ACID (rejected)
|
|
- DynamoDB: Managed, but vendor lock-in (rejected)</code></pre>
|
|
<p>❌ <strong>No Consequences Section</strong>: Ignoring negative outcomes ✅ <strong>Correct approach</strong>: Document positive, negative, and neutral consequences</p>
|
|
<h3>Common Mistakes</h3>
|
|
<p>❌ <strong>Deleting Superseded Decisions</strong>: Removing historical context</p>
|
|
<pre><code class="lang-markdown"># ❌ Don't:
|
|
[Delete ADR-003 after it's superseded]
|
|
|
|
# ✅ Correct:
|
|
Keep ADR-003 with "Superseded" status and link to ADR-012</code></pre>
|
|
<p>❌ <strong>No Status Updates</strong>: Decision stays "Proposed" even after implementation ✅ <strong>Better</strong>: Update status to Accepted → Implemented with dates</p>
|
|
<p>❌ <strong>Skipping Post-Implementation Review</strong>: No retrospective on decision</p>
|
|
<pre><code class="lang-markdown"># ❌ Don't:
|
|
Implement decision → Move on to next task
|
|
|
|
# ✅ Correct:
|
|
Implement decision → Wait 3-6 months → Conduct review → Document learnings</code></pre>
|
|
<p>❌ <strong>ADR for Trivial Decisions</strong>: "ADR-099: Use camelCase for variable names" ✅ <strong>Better</strong>: ADRs for significant, hard-to-reverse decisions only</p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>rfc-structure-format.md</code> - RFC document templates and formatting</li><li><code>rfc-technical-design.md</code> - Architecture proposals and technical design</li><li><code>rfc-consensus-building.md</code> - Driving approval and building consensus</li><li><code>product/prd-structure-templates.md</code> - Product decision documentation (PRDs)</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-decision-documentation.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |