mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
667 lines
34 KiB
HTML
667 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-structure-format</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="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/engineering-rfc-structure-format">
|
|
<link rel="alternate" type="text/markdown" href="/engineering-rfc-structure-format.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/engineering-rfc-structure-format.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-structure-format</h1><p class="lede">RFC document structure, templates, formatting conventions, and versioning for technical design documents</p><h1>RFC Structure & Format</h1>
|
|
<p><strong>Scope</strong>: Comprehensive guide to RFC formats, sections, templates, and documentation best practices for technical design <strong>Lines</strong>: ~300 <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>Writing a new RFC (Request for Comments) for technical design</li><li>Standardizing RFC format across an engineering team</li><li>Choosing between lightweight and comprehensive RFC templates</li><li>Defining what sections belong in an RFC vs PRD</li><li>Setting up RFC templates in GitHub, Notion, or Google Docs</li><li>Establishing RFC review and approval workflows</li><li>Training engineers on effective technical writing</li><li>Creating Architecture Decision Records (ADRs) for significant decisions</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Concept 1: RFC Purpose and Audience</h3>
|
|
<p><strong>Primary Goals</strong>:</p>
|
|
<ul><li>Document technical design decisions and rationale</li><li>Enable team review and feedback before implementation</li><li>Create referenceable record of why decisions were made</li><li>Surface risks, trade-offs, and alternatives</li></ul>
|
|
<p><strong>Key Audiences</strong>:</p>
|
|
<ul><li>Engineering team: needs implementation details, trade-offs, risks</li><li>Architects: needs system design, integration points, scalability</li><li>Product/Design: needs understanding of technical constraints</li><li>Future engineers: needs historical context for decisions</li></ul>
|
|
<h3>Concept 2: RFC vs PRD vs ADR</h3>
|
|
<p><strong>PRD (Product Requirements Document)</strong>:</p>
|
|
<ul><li>Written by: Product Manager</li><li>Focus: What we're building, why, user stories, success metrics</li><li>Audience: Cross-functional (eng, design, leadership)</li></ul>
|
|
<p><strong>RFC (Request for Comments)</strong>:</p>
|
|
<ul><li>Written by: Engineer or Tech Lead</li><li>Focus: How we're building it, architecture, trade-offs</li><li>Audience: Engineering team, technical stakeholders</li></ul>
|
|
<p><strong>ADR (Architecture Decision Record)</strong>:</p>
|
|
<ul><li>Written by: Engineer or Architect</li><li>Focus: Single significant decision (e.g., "Why we chose Postgres over MongoDB")</li><li>Audience: Engineering team, future maintainers</li><li>Format: Lightweight, decision-focused (subset of RFC)</li></ul>
|
|
<h3>Concept 3: RFC Lifecycle and Status</h3>
|
|
<p><strong>Status Flow</strong>:</p>
|
|
<pre><code>Draft → In Review → Approved → Implemented → Superseded/Deprecated</code></pre>
|
|
<p><strong>Draft</strong>: Author is still writing, not ready for review <strong>In Review</strong>: Open for comments and feedback <strong>Approved</strong>: Design accepted, ready for implementation <strong>Implemented</strong>: Design has been built and shipped <strong>Superseded</strong>: Replaced by newer RFC <strong>Deprecated</strong>: Decision no longer valid (context changed) <strong>Rejected</strong>: Proposal not accepted (document why)</p>
|
|
<hr>
|
|
<h2>Patterns</h2>
|
|
<h3>Pattern 1: Lightweight RFC Template</h3>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Small-to-medium features</li><li>Established system with well-understood architecture</li><li>Fast iteration, small team</li></ul>
|
|
<pre><code class="lang-markdown"># RFC-001: Add User Profile Photo Upload
|
|
|
|
**Author**: Jane Doe (@jane)
|
|
**Created**: 2025-10-25
|
|
**Status**: Draft → In Review → Approved
|
|
**Reviewers**: @alice (backend), @bob (frontend), @charlie (security)
|
|
|
|
## Problem Statement
|
|
Users cannot currently upload profile photos. This is a top-requested feature
|
|
(50+ support tickets) and blocks social features planned for Q1.
|
|
|
|
## Proposed Solution
|
|
Add profile photo upload with S3 storage and CloudFront CDN.
|
|
|
|
### Architecture</code></pre>
|
|
<p>Client → API (/upload-photo) → S3 (storage) → CloudFront (CDN) → Client (display)</p>
|
|
<pre><code>
|
|
### Implementation
|
|
1. Add `profile_photo_url` column to `users` table (nullable)
|
|
2. Create `/api/users/:id/upload-photo` endpoint:
|
|
- Accept multipart/form-data (max 5MB)
|
|
- Validate image type (JPEG, PNG, WebP)
|
|
- Resize to 400x400px (ImageMagick)
|
|
- Upload to S3 with UUID filename
|
|
- Store CloudFront URL in database
|
|
3. Frontend: Add upload button in settings, display photo in nav
|
|
|
|
### Trade-offs
|
|
- **S3 + CloudFront** (chosen): Scalable, low latency, $0.023/GB
|
|
- **Local storage**: Cheaper short-term, doesn't scale, slow serving
|
|
- **Database BLOB**: Simple, but bloats DB and slow retrieval
|
|
|
|
## Security Considerations
|
|
- File type validation (reject executables, scripts)
|
|
- Virus scanning (ClamAV integration, future RFC)
|
|
- Rate limiting: 5 uploads per user per hour
|
|
- Private S3 bucket with signed URLs
|
|
|
|
## Risks
|
|
- Cost: ~$50/month at 10k users, $500/month at 100k users
|
|
- Storage growth: Plan archival policy (future RFC)
|
|
|
|
## Open Questions
|
|
- [ ] Should we support GIF avatars? (Decision: No for v1, revisit in Q2)
|
|
- [ ] Compress images server-side? (Decision: Yes, use 80% JPEG quality)
|
|
|
|
## Approval
|
|
- [x] Backend: @alice (approved 2025-10-25)
|
|
- [x] Frontend: @bob (approved 2025-10-25)
|
|
- [x] Security: @charlie (approved 2025-10-26)</code></pre>
|
|
<h3>Pattern 2: Comprehensive RFC Template</h3>
|
|
<p><strong>Use case</strong>: Major architectural changes, new services, complex features</p>
|
|
<pre><code class="lang-markdown"># RFC-042: Real-Time Collaborative Editing System
|
|
|
|
## Metadata
|
|
- **RFC Number**: 042
|
|
- **Title**: Real-Time Collaborative Editing System
|
|
- **Author**: Alex Chen (@alex)
|
|
- **Contributors**: @jordan (backend), @taylor (frontend)
|
|
- **Created**: 2025-10-25
|
|
- **Last Updated**: 2025-10-26
|
|
- **Status**: In Review
|
|
- **DACI**:
|
|
- **Driver**: @alex
|
|
- **Approver**: @engineering-lead
|
|
- **Contributors**: @jordan, @taylor, @sam (product)
|
|
- **Informed**: [email protected]
|
|
|
|
## Executive Summary
|
|
Implement real-time collaborative editing (like Google Docs) for our document editor.
|
|
Uses WebSocket for transport, Operational Transform (OT) for conflict resolution,
|
|
and Redis for state management. Supports 50 concurrent editors per document.
|
|
|
|
[2-3 paragraph summary for leadership]
|
|
|
|
## Background & Context
|
|
### Current State
|
|
- Document editing is single-user only
|
|
- Users manually save and reload to see others' changes
|
|
- Conflicts are frequent (last-write-wins, data loss)
|
|
|
|
### Problem
|
|
- 40% of users work in teams (user research, Q4 2024)
|
|
- 200+ support tickets re: lost edits due to conflicts
|
|
- Competitors (Notion, Coda) all have real-time collab
|
|
|
|
### Goals
|
|
- Enable 2-50 users to edit same document simultaneously
|
|
- Latency <200ms for edit propagation (p95)
|
|
- Zero data loss from conflicts (OT guarantees convergence)
|
|
- Ship MVP by Q1 2025
|
|
|
|
## Proposed Solution
|
|
### High-Level Architecture</code></pre>
|
|
<p>┌──────────┐ │ Client │ (Browser) │ Editor │ └────┬─────┘ │ WebSocket ▼ ┌──────────┐ ┌────────┐ ┌──────────┐ │ API │─────▶│ Redis │─────▶│ Postgres │ │ Server │ │ (State)│ │ (Persist)│ └──────────┘ └────────┘ └──────────┘</p>
|
|
<pre><code>
|
|
### Components
|
|
|
|
**1. WebSocket Server** (Node.js + ws library)
|
|
- Handles persistent connections
|
|
- Routes operations between clients
|
|
- Manages presence (who's editing)
|
|
|
|
**2. Operational Transform Engine** (ot.js library)
|
|
- Transforms concurrent operations
|
|
- Guarantees convergence (all clients reach same state)
|
|
- Handles text insert/delete operations
|
|
|
|
**3. Redis State Store**
|
|
- Stores active document state (TTL: 1 hour)
|
|
- Manages operation history for late joiners
|
|
- Publishes operations to subscribers (Redis Pub/Sub)
|
|
|
|
**4. PostgreSQL Persistence**
|
|
- Stores final document snapshots (every 100 operations or 5 min)
|
|
- Document version history
|
|
- Audit log of all edits
|
|
|
|
**5. Client Editor** (React + Slate.js)
|
|
- Rich text editor with OT integration
|
|
- Displays cursors/selections of other users
|
|
- Optimistic updates with conflict resolution
|
|
|
|
### Data Flow
|
|
1. User types in editor → Generate OT operation
|
|
2. Send operation via WebSocket to server
|
|
3. Server applies OT transform (resolve conflicts)
|
|
4. Broadcast transformed operation to all clients
|
|
5. Clients apply operation to local state
|
|
6. Every 100 ops, persist snapshot to Postgres
|
|
|
|
## Alternative Approaches Considered
|
|
|
|
### Alternative 1: CRDTs (Conflict-Free Replicated Data Types)
|
|
**Pros**: Simpler conflict resolution, eventual consistency
|
|
**Cons**: Larger payload size, less battle-tested for text editing
|
|
**Decision**: OT chosen for smaller payloads and industry standard
|
|
|
|
### Alternative 2: Server-Side Rendering (SSR) with Polling
|
|
**Pros**: No WebSocket complexity
|
|
**Cons**: High latency (>1s), poor UX, server load
|
|
**Decision**: Rejected, latency unacceptable
|
|
|
|
### Alternative 3: Firebase Realtime Database
|
|
**Pros**: Fully managed, easy to integrate
|
|
**Cons**: Vendor lock-in, $0.05/GB (expensive at scale), limited OT support
|
|
**Decision**: Rejected, build in-house for cost and control
|
|
|
|
## Technical Deep Dive
|
|
|
|
### WebSocket Protocol</code></pre>
|
|
<p>// Client → Server: Edit operation { "type": "operation", "doc_id": "abc123", "operation": { "position": 42, "insert": "Hello", "version": 15 }, "client_id": "user-xyz" }</p>
|
|
<p>// Server → Clients: Transformed operation { "type": "operation", "operation": { "position": 45, // Transformed position "insert": "Hello", "version": 16 }, "author": "user-xyz" }</p>
|
|
<pre><code>
|
|
### OT Transformation Example</code></pre>
|
|
<p>Client A: Insert "X" at position 5 (version 10) Client B: Insert "Y" at position 5 (version 10) [concurrent!]</p>
|
|
<p>Server receives A's operation first:</p>
|
|
<ul><li>Apply: "HelloWorld" → "HelloXWorld" (version 11)</li><li>Broadcast to B with version 11</li></ul>
|
|
<p>Server receives B's operation (still at version 10):</p>
|
|
<ul><li>Transform B's operation against A's: position 5 → 6 (shift right)</li><li>Apply: "HelloXWorld" → "HelloXYWorld" (version 12)</li><li>Broadcast to A with version 12</li></ul>
|
|
<p>Final state for both clients: "HelloXYWorld" ✅ (converged)</p>
|
|
<pre><code>
|
|
## Non-Functional Requirements
|
|
|
|
### Performance
|
|
- Latency: <200ms for operation propagation (p95)
|
|
- Throughput: 1,000 operations/sec per server
|
|
- Concurrent editors: 50 per document
|
|
- WebSocket connections: 10,000 per server
|
|
|
|
### Scalability
|
|
- Horizontal scaling: Add more WebSocket servers (load balanced)
|
|
- Redis cluster: Shard by document ID
|
|
- Database: Read replicas for snapshots
|
|
|
|
### Reliability
|
|
- Auto-reconnect on connection loss (exponential backoff)
|
|
- Replay missed operations on reconnect (via Redis history)
|
|
- Periodic snapshots to survive Redis cache eviction
|
|
|
|
### Security
|
|
- Authenticate WebSocket connections (JWT)
|
|
- Authorize document access (check permissions)
|
|
- Rate limit: 100 operations/sec per user
|
|
|
|
## Migration & Rollout Plan
|
|
|
|
### Phase 1: Infrastructure Setup (Week 1-2)
|
|
- Deploy WebSocket server (1 instance)
|
|
- Set up Redis cluster
|
|
- Implement OT engine (ot.js integration)
|
|
|
|
### Phase 2: Alpha Testing (Week 3-4)
|
|
- Enable for internal team only (feature flag)
|
|
- Test with 2-5 concurrent editors
|
|
- Identify and fix bugs
|
|
|
|
### Phase 3: Beta Rollout (Week 5-6)
|
|
- Enable for 10% of users (feature flag)
|
|
- Monitor performance metrics (latency, errors)
|
|
- Gather user feedback
|
|
|
|
### Phase 4: General Availability (Week 7-8)
|
|
- Enable for all users
|
|
- Monitor at scale (10k+ concurrent editors)
|
|
- Plan horizontal scaling if needed
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Impact | Likelihood | Mitigation |
|
|
|------|--------|------------|------------|
|
|
| WebSocket server crash | High | Medium | Auto-restart, load balancer health checks |
|
|
| Redis cache eviction | High | Low | Persist snapshots every 5 min, replay from Postgres |
|
|
| OT bugs (divergence) | Critical | Low | Extensive testing, snapshot reconciliation |
|
|
| High cost at scale | Medium | Medium | Monitor costs, optimize Redis usage |
|
|
|
|
## Metrics & Monitoring
|
|
|
|
### Success Metrics
|
|
- 80% of collaborative sessions have <200ms latency
|
|
- <0.1% operation conflicts requiring manual resolution
|
|
- 90% of users report improved collaboration (survey)
|
|
|
|
### Monitoring
|
|
- Grafana dashboard: latency, operation rate, connection count
|
|
- Error tracking: Sentry for WebSocket errors
|
|
- Alerts: Latency >500ms, error rate >1%, Redis down
|
|
|
|
## Open Questions
|
|
- [ ] **Q1**: Should we support audio/video chat? (Decision: No, defer to Q2)
|
|
- [ ] **Q2**: Max document size for real-time? (Decision: 50k chars, show warning)
|
|
- [x] **Q3**: Which OT library? (Decision: ot.js, battle-tested)
|
|
|
|
## Appendix
|
|
|
|
### References
|
|
- Operational Transform: https://operational-transformation.github.io/
|
|
- ot.js library: https://github.com/Operational-Transformation/ot.js
|
|
- Google Wave OT whitepaper: [link]
|
|
|
|
### Glossary
|
|
- **OT**: Operational Transform (conflict resolution algorithm)
|
|
- **CRDT**: Conflict-Free Replicated Data Type (alternative to OT)
|
|
- **TTL**: Time To Live (Redis cache expiration)</code></pre>
|
|
<h3>Pattern 3: Architecture Decision Record (ADR) Template</h3>
|
|
<p><strong>Use case</strong>: Documenting single significant decision</p>
|
|
<pre><code class="lang-markdown"># ADR-005: Use PostgreSQL Over MongoDB for User Data
|
|
|
|
**Date**: 2025-10-25
|
|
**Status**: Accepted
|
|
**Deciders**: @alice (backend lead), @bob (architect)
|
|
**Consulted**: @charlie (DBA), @dana (product)
|
|
|
|
## Context
|
|
We need to choose a database for storing user data (profiles, settings, activity).
|
|
Current requirements:
|
|
- 100k users (growing to 1M in 2 years)
|
|
- ACID transactions for billing data
|
|
- Complex queries (JOINs, aggregations)
|
|
- Relational data (users, projects, memberships)
|
|
|
|
## Decision
|
|
We will use **PostgreSQL** as the primary database for user data.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- ACID guarantees for financial transactions (required for compliance)
|
|
- Rich query capabilities (JOINs, window functions, CTEs)
|
|
- Strong ecosystem (ORMs, tools, monitoring)
|
|
- Team familiarity (all backend engineers know SQL)
|
|
- Proven scalability (10M+ rows, read replicas, partitioning)
|
|
|
|
### Negative
|
|
- Vertical scaling limits (need sharding at 10M+ users)
|
|
- Harder to scale writes than NoSQL
|
|
- Schema migrations require downtime (mitigated with tools like Alembic)
|
|
|
|
### Neutral
|
|
- Requires careful indexing for performance
|
|
- Need to plan sharding strategy for future scale
|
|
|
|
## Alternatives Considered
|
|
|
|
### MongoDB
|
|
**Pros**: Flexible schema, horizontal scaling, fast writes
|
|
**Cons**: No ACID across collections (deal-breaker for billing), weaker query capabilities
|
|
**Decision**: Rejected due to ACID requirement
|
|
|
|
### MySQL
|
|
**Pros**: Similar to Postgres, team familiarity
|
|
**Cons**: Weaker JSON support, less feature-rich than Postgres
|
|
**Decision**: Postgres chosen for JSON columns and better full-text search
|
|
|
|
### DynamoDB
|
|
**Pros**: Fully managed, infinite scaling
|
|
**Cons**: Vendor lock-in, expensive, limited query flexibility
|
|
**Decision**: Rejected, need complex queries</code></pre>
|
|
<h3>Pattern 4: RFC Changelog and Version Tracking</h3>
|
|
<p><strong>Use case</strong>: Tracking changes during review process</p>
|
|
<pre><code class="lang-markdown">## Version History
|
|
|
|
| Version | Date | Author | Summary of Changes |
|
|
|---------|------|--------|--------------------|
|
|
| 1.3 | 2025-10-26 | @alex | Added security section per @charlie's feedback |
|
|
| 1.2 | 2025-10-25 | @alex | Changed from CRDTs to OT per team discussion |
|
|
| 1.1 | 2025-10-24 | @alex | Added cost analysis |
|
|
| 1.0 | 2025-10-23 | @alex | Initial draft |
|
|
|
|
## Change Log
|
|
- **2025-10-26**: Added rate limiting (100 ops/sec per user) per security review
|
|
- **2025-10-25**: Switched from CRDTs to OT after benchmarking (payload size 60% smaller)
|
|
- **2025-10-24**: Added Redis Pub/Sub for operation broadcast (replaced direct WebSocket)</code></pre>
|
|
<h3>Pattern 5: DACI Decision Framework in RFC</h3>
|
|
<p><strong>Use case</strong>: Clarifying roles for complex decisions</p>
|
|
<pre><code class="lang-markdown">## DACI Framework
|
|
|
|
**Driver**: @alex
|
|
- Responsible for RFC creation and pushing to decision
|
|
- Collects feedback and drives consensus
|
|
- Updates RFC based on input
|
|
|
|
**Approver**: @engineering-lead
|
|
- Final decision authority
|
|
- Approves or rejects RFC
|
|
- Can delegate to subject matter expert
|
|
|
|
**Contributors**: @jordan (backend), @taylor (frontend), @sam (product)
|
|
- Provide input and feedback
|
|
- Review and comment on RFC
|
|
- No veto power, but concerns addressed
|
|
|
|
**Informed**: [email protected], [email protected]
|
|
- Kept in the loop
|
|
- Can read and comment, but not required
|
|
- Notified when RFC status changes</code></pre>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>RFC Section Checklist</h3>
|
|
<pre><code>Required Sections | Optional Sections
|
|
---------------------------|-------------------
|
|
Problem Statement | Executive Summary
|
|
Proposed Solution | Background/Context
|
|
Alternatives Considered | Technical Deep Dive
|
|
Risks & Mitigations | Migration Plan
|
|
Approval/DACI | Metrics & Monitoring
|
|
| Appendix/References</code></pre>
|
|
<h3>RFC vs PRD vs ADR</h3>
|
|
<pre><code>Document | Author | Focus | Audience
|
|
---------|--------|-------|----------
|
|
PRD | PM | What & why | Cross-functional
|
|
RFC | Engineer | How (architecture) | Engineering
|
|
ADR | Engineer | Single decision | Engineering + future</code></pre>
|
|
<h3>RFC Status Flow</h3>
|
|
<pre><code>Draft → In Review → Approved → Implemented
|
|
↓
|
|
Rejected (with rationale)
|
|
↓
|
|
Superseded (replaced by newer RFC)</code></pre>
|
|
<h3>Documentation Tools</h3>
|
|
<pre><code>Tool | Best For | RFC Features
|
|
-----|----------|-------------
|
|
GitHub | Code-focused teams | Markdown, PR workflow, comments
|
|
Notion | Flexible workflows | Templates, comments, databases
|
|
Google Docs | Collaboration | Real-time editing, suggestions
|
|
Confluence | Enterprise | Versioning, permissions, templates</code></pre>
|
|
<h3>Key Guidelines</h3>
|
|
<pre><code>✅ DO: Write for future engineers (historical context)
|
|
✅ DO: Document alternatives considered (why not X?)
|
|
✅ DO: Include trade-off analysis (pros/cons)
|
|
✅ DO: Define clear approval criteria (DACI)
|
|
✅ DO: Version your RFC and track changes
|
|
|
|
❌ DON'T: Skip the "why" (rationale is critical)
|
|
❌ DON'T: Prescribe without justification (explain trade-offs)
|
|
❌ DON'T: Write implementation code in RFC (high-level design only)
|
|
❌ DON'T: Ignore edge cases and failure modes
|
|
❌ DON'T: Forget to update RFC status after implementation</code></pre>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>Critical Violations</h3>
|
|
<p>❌ <strong>Solution Without Problem Statement</strong>: Jumping to implementation without context</p>
|
|
<pre><code class="lang-markdown"># ❌ NEVER:
|
|
## Proposed Solution
|
|
We'll use Redis for caching and WebSockets for real-time updates.
|
|
|
|
# ✅ CORRECT:
|
|
## Problem Statement
|
|
API response times are >2 seconds due to repeated database queries (N+1 problem).
|
|
Users report slow dashboard loads, causing 15% drop in engagement.
|
|
|
|
## Proposed Solution
|
|
Implement Redis caching to reduce database load and improve response times to <200ms.</code></pre>
|
|
<p>❌ <strong>Single Option RFC</strong>: Only presenting one solution without alternatives ✅ <strong>Correct approach</strong>: Always present 2-3 alternatives with trade-off analysis</p>
|
|
<h3>Common Mistakes</h3>
|
|
<p>❌ <strong>Missing Trade-Off Analysis</strong>: "We'll use Postgres" without explaining why</p>
|
|
<pre><code class="lang-markdown"># ❌ Don't:
|
|
We'll use PostgreSQL for the database.
|
|
|
|
# ✅ Correct:
|
|
## Database Choice: PostgreSQL
|
|
|
|
**Alternatives Considered**:
|
|
1. **PostgreSQL** (chosen): ACID, complex queries, team familiarity
|
|
- Pros: Strong consistency, rich features
|
|
- Cons: Vertical scaling limits
|
|
2. **MongoDB**: Flexible schema, horizontal scaling
|
|
- Pros: Easy sharding
|
|
- Cons: No ACID, weaker queries (deal-breaker for billing)
|
|
3. **DynamoDB**: Fully managed, infinite scale
|
|
- Pros: No ops burden
|
|
- Cons: Vendor lock-in, expensive, limited queries
|
|
|
|
**Decision**: Postgres for ACID guarantees (financial transactions) and query flexibility.</code></pre>
|
|
<p>❌ <strong>Ignoring Risks</strong>: No discussion of what could go wrong ✅ <strong>Better</strong>: Document risks and mitigation plans</p>
|
|
<p>❌ <strong>Vague Approval Process</strong>: "Get team feedback" instead of clear DACI ✅ <strong>Better</strong>: Define Driver, Approver, Contributors, Informed</p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>rfc-technical-design.md</code> - Deep dive on architecture proposals and technical design</li><li><code>rfc-consensus-building.md</code> - How to gather feedback and drive approval</li><li><code>rfc-decision-documentation.md</code> - ADRs, tracking decisions, post-implementation review</li><li><code>product/prd-structure-templates.md</code> - Product counterpart for product requirements</li><li><code>product/prd-technical-specifications.md</code> - PM's technical specs that feed into RFCs</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-structure-format.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |