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]>
711 lines
38 KiB
HTML
711 lines
38 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>product-prd-technical-specifications</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="/product-prd-technical-specifications.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/product-prd-technical-specifications">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/product-prd-technical-specifications.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>product-prd-technical-specifications</h1><p class="lede">API specifications, data models, architecture diagrams, and technical constraints for product requirements</p><h1>PRD Technical Specifications</h1>
|
|
<p><strong>Scope</strong>: Bridging product requirements and engineering implementation with API specs, data models, and technical constraints <strong>Lines</strong>: ~360 <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>Defining API requirements for product features</li><li>Specifying data models and entity relationships</li><li>Documenting technical constraints (performance, scalability, security)</li><li>Creating architecture diagrams to illustrate system design</li><li>Planning third-party integrations and dependencies</li><li>Defining migration strategies for data or features</li><li>Collaborating with engineering to validate technical feasibility</li><li>Bridging PRD requirements and RFC (Request for Comments) technical designs</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Concept 1: PM vs Engineering Technical Ownership</h3>
|
|
<p><strong>PM Owns (in PRD)</strong>:</p>
|
|
<ul><li><strong>What data</strong> the system needs (e.g., "User profile must include name, email, preferences")</li><li><strong>What API behaviors</strong> are required (e.g., "API must support filtering by date range")</li><li><strong>What constraints</strong> exist (e.g., "Must support 10,000 concurrent users")</li><li><strong>What integrations</strong> are needed (e.g., "Must integrate with Stripe for payments")</li></ul>
|
|
<p><strong>Engineering Owns (in RFC)</strong>:</p>
|
|
<ul><li><strong>How data is stored</strong> (e.g., Postgres schema, NoSQL structure)</li><li><strong>How APIs are implemented</strong> (e.g., REST vs GraphQL, specific endpoints)</li><li><strong>How to achieve performance</strong> (e.g., caching strategy, database indexing)</li><li><strong>How to architect</strong> the solution (e.g., microservices vs monolith)</li></ul>
|
|
<p><strong>Collaboration Zone</strong>: PMs and engineers collaborate on trade-offs (e.g., "Real-time updates vs eventual consistency")</p>
|
|
<h3>Concept 2: API Specification Formats</h3>
|
|
<p><strong>OpenAPI (Swagger)</strong>: Standard for REST APIs</p>
|
|
<ul><li>Machine-readable API definitions</li><li>Auto-generates documentation</li><li>Enables contract testing</li></ul>
|
|
<p><strong>GraphQL Schema</strong>: For GraphQL APIs</p>
|
|
<ul><li>Defines types, queries, mutations</li><li>Self-documenting via introspection</li></ul>
|
|
<p><strong>Informal API Specs</strong> (in PRD):</p>
|
|
<ul><li>Describe endpoints, inputs, outputs at high level</li><li>Engineering translates to formal OpenAPI/GraphQL schema in RFC</li></ul>
|
|
<h3>Concept 3: Data Model Levels of Detail</h3>
|
|
<p><strong>Conceptual Model</strong> (PM in PRD):</p>
|
|
<ul><li>Entities and relationships (e.g., "User has many Projects")</li><li>Key attributes (e.g., "Project has title, description, owner")</li><li>Business logic constraints (e.g., "User can only own 10 projects on free plan")</li></ul>
|
|
<p><strong>Logical Model</strong> (Engineering in RFC):</p>
|
|
<ul><li>Normalized tables or collections</li><li>Foreign keys, indexes</li><li>Data types and validations</li></ul>
|
|
<p><strong>Physical Model</strong> (Engineering in implementation):</p>
|
|
<ul><li>Actual database schema (DDL)</li><li>Performance optimizations (partitioning, sharding)</li></ul>
|
|
<hr>
|
|
<h2>Patterns</h2>
|
|
<h3>Pattern 1: Informal API Specification (PM in PRD)</h3>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Defining API requirements at product level</li><li>Providing engineering with clear API expectations</li><li>Not prescribing exact implementation</li></ul>
|
|
<pre><code class="lang-markdown">## API Requirements: User Management
|
|
|
|
### Create User Account
|
|
**Purpose**: Allow new users to sign up
|
|
|
|
**Input**:
|
|
- `email` (string, required): User's email address (validated format)
|
|
- `password` (string, required): Password (min 8 chars, 1 number, 1 symbol)
|
|
- `display_name` (string, optional): User's preferred display name
|
|
|
|
**Output (Success)**:
|
|
- `user_id` (string): Unique identifier for created user
|
|
- `email` (string): Confirmed email
|
|
- `created_at` (timestamp): Account creation time
|
|
|
|
**Output (Error)**:
|
|
- `error_code` (string): Machine-readable error (e.g., "EMAIL_IN_USE")
|
|
- `error_message` (string): Human-readable error
|
|
- `field_errors` (object, optional): Field-specific validation errors
|
|
|
|
**Constraints**:
|
|
- Must complete in <500ms (p95 latency)
|
|
- Must return 201 status on success, 4xx on validation error
|
|
- Must send verification email within 1 minute
|
|
- Email must be case-insensitive ([email protected] == [email protected])
|
|
|
|
**Security**:
|
|
- Password must be hashed (bcrypt or stronger)
|
|
- Rate limit: 5 signup attempts per IP per hour
|
|
- Email verification required before account activation
|
|
|
|
### Get User Profile
|
|
**Purpose**: Retrieve user's profile information
|
|
|
|
**Input**:
|
|
- `user_id` (string, required): ID of user to fetch
|
|
- `fields` (array of strings, optional): Specific fields to return (default: all)
|
|
|
|
**Authentication**: Required (user can only fetch own profile, or admin can fetch any)
|
|
|
|
**Output (Success)**:
|
|
- `user_id` (string)
|
|
- `email` (string)
|
|
- `display_name` (string)
|
|
- `profile_photo_url` (string, optional)
|
|
- `created_at` (timestamp)
|
|
- `preferences` (object): User settings
|
|
|
|
**Output (Error)**:
|
|
- `error_code`: "UNAUTHORIZED" | "USER_NOT_FOUND"
|
|
- `error_message`: Human-readable error
|
|
|
|
**Constraints**:
|
|
- Must complete in <100ms (p95 latency)
|
|
- Must support up to 1,000 requests/sec per server</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul><li>Engineering understands API requirements without over-specification</li><li>PM focuses on behavior, not implementation</li><li>Easy to review and validate with stakeholders</li></ul>
|
|
<h3>Pattern 2: Entity-Relationship Diagram (Conceptual)</h3>
|
|
<p><strong>Use case</strong>: Defining data model for PRD</p>
|
|
<pre><code class="lang-markdown">## Data Model: Project Management System
|
|
|
|
### Entities and Relationships
|
|
</code></pre>
|
|
<p>User (1) ──── (many) Project │ └─── (many) ProjectMembership ──── (1) Project</p>
|
|
<pre><code>
|
|
### Entity: User
|
|
**Attributes**:
|
|
- `user_id` (unique identifier)
|
|
- `email` (unique, required)
|
|
- `display_name` (required)
|
|
- `profile_photo_url` (optional)
|
|
- `account_tier` ("free" | "pro" | "enterprise")
|
|
- `created_at` (timestamp)
|
|
|
|
**Business Rules**:
|
|
- Email must be verified before account activation
|
|
- Free tier users can own max 10 projects
|
|
- Pro tier users can own unlimited projects
|
|
|
|
### Entity: Project
|
|
**Attributes**:
|
|
- `project_id` (unique identifier)
|
|
- `title` (required, max 100 chars)
|
|
- `description` (optional, max 1000 chars)
|
|
- `owner_user_id` (foreign key to User)
|
|
- `status` ("active" | "archived" | "deleted")
|
|
- `created_at` (timestamp)
|
|
- `updated_at` (timestamp)
|
|
|
|
**Business Rules**:
|
|
- Only owner can delete project
|
|
- Archived projects are read-only
|
|
- Deleted projects are soft-deleted (not permanently removed)
|
|
|
|
### Entity: ProjectMembership
|
|
**Attributes**:
|
|
- `membership_id` (unique identifier)
|
|
- `project_id` (foreign key to Project)
|
|
- `user_id` (foreign key to User)
|
|
- `role` ("viewer" | "editor" | "admin")
|
|
- `invited_at` (timestamp)
|
|
- `joined_at` (timestamp, optional)
|
|
|
|
**Business Rules**:
|
|
- User can have only one membership per project (unique on project_id + user_id)
|
|
- Project owner automatically has "admin" role
|
|
- "Viewer" can read, "Editor" can read/write, "Admin" can read/write/invite</code></pre>
|
|
<h3>Pattern 3: Technical Constraints Documentation</h3>
|
|
<p><strong>Use case</strong>: Defining non-functional requirements for engineering</p>
|
|
<pre><code class="lang-markdown">## Technical Constraints: User Dashboard
|
|
|
|
### Performance Requirements
|
|
**Page Load Time**:
|
|
- Initial load: <2 seconds on 4G network (p95)
|
|
- Subsequent navigation: <500ms (p95)
|
|
- Time to Interactive (TTI): <3 seconds (p95)
|
|
|
|
**API Response Time**:
|
|
- Read operations: <100ms (p95)
|
|
- Write operations: <500ms (p95)
|
|
- Bulk operations: <2 seconds for up to 1,000 items (p95)
|
|
|
|
**Scalability**:
|
|
- Must support 10,000 concurrent users (current peak: 2,000)
|
|
- Must handle 100,000 API requests/minute (current: 20,000/min)
|
|
- Database queries must support 1M+ user records
|
|
|
|
### Security Requirements
|
|
**Authentication**:
|
|
- JWT-based authentication with 1-hour expiration
|
|
- Refresh tokens with 30-day expiration
|
|
- HTTPS required for all API calls
|
|
|
|
**Authorization**:
|
|
- Role-based access control (RBAC)
|
|
- Users can only access their own data (except admins)
|
|
- API rate limiting: 1,000 requests/hour per user
|
|
|
|
**Data Protection**:
|
|
- Passwords hashed with bcrypt (cost factor 12+)
|
|
- Sensitive data encrypted at rest (AES-256)
|
|
- PII (email, name) encrypted in database
|
|
- GDPR compliance: user data export and deletion
|
|
|
|
### Availability & Reliability
|
|
**Uptime**:
|
|
- 99.9% uptime SLA (< 43 minutes downtime/month)
|
|
- Graceful degradation if dependent services fail
|
|
- Zero downtime deployments
|
|
|
|
**Data Durability**:
|
|
- Database backups every 6 hours
|
|
- Point-in-time recovery for last 30 days
|
|
- Multi-region replication for disaster recovery
|
|
|
|
### Compatibility Requirements
|
|
**Browser Support**:
|
|
- Chrome 90+ (last 2 years)
|
|
- Safari 14+ (last 2 years)
|
|
- Firefox 88+ (last 2 years)
|
|
- Edge 90+ (Chromium-based)
|
|
|
|
**Device Support**:
|
|
- Desktop (1920x1080 and above)
|
|
- Tablet (768px width and above)
|
|
- Mobile (375px width and above)
|
|
- Screen readers (WCAG 2.1 AA compliance)
|
|
|
|
### Operational Constraints
|
|
**Deployment**:
|
|
- CI/CD pipeline with automated tests
|
|
- Rollback capability within 5 minutes
|
|
- Feature flags for gradual rollout
|
|
|
|
**Monitoring**:
|
|
- Application performance monitoring (APM)
|
|
- Error tracking and alerting
|
|
- User analytics and funnel tracking</code></pre>
|
|
<h3>Pattern 4: Third-Party Integration Specification</h3>
|
|
<p><strong>Use case</strong>: Defining integration requirements for external services</p>
|
|
<pre><code class="lang-markdown">## Integration Requirements: Payment Processing
|
|
|
|
### Integration: Stripe
|
|
|
|
**Use Case**: Process credit card payments for subscription upgrades
|
|
|
|
**Required Capabilities**:
|
|
- Create customer records
|
|
- Process one-time payments
|
|
- Set up recurring subscriptions
|
|
- Handle webhook events (payment success, failure, subscription changes)
|
|
- Retrieve payment history
|
|
|
|
**API Endpoints Needed** (Informal):
|
|
- `POST /payments/charge`: Initiate one-time payment
|
|
- Input: `amount`, `currency`, `payment_method_id`, `customer_id`
|
|
- Output: `transaction_id`, `status`, `receipt_url`
|
|
- `POST /subscriptions/create`: Start recurring subscription
|
|
- Input: `customer_id`, `plan_id`, `payment_method_id`
|
|
- Output: `subscription_id`, `status`, `next_billing_date`
|
|
- `POST /webhooks/stripe`: Receive Stripe events
|
|
- Input: Stripe webhook payload
|
|
- Output: 200 OK (acknowledge receipt)
|
|
|
|
**Error Handling**:
|
|
- Payment declined: Show user-friendly error, allow retry
|
|
- Network timeout: Implement retry logic with exponential backoff
|
|
- Webhook failure: Queue for retry (max 3 attempts)
|
|
|
|
**Security**:
|
|
- Never store raw credit card numbers (use Stripe tokens)
|
|
- Validate webhook signatures (Stripe signing secret)
|
|
- Use Stripe's test mode for development/staging
|
|
|
|
**Constraints**:
|
|
- Must use Stripe API version 2023-10-16 or later
|
|
- Must handle webhooks within 30 seconds (Stripe timeout)
|
|
- Must comply with PCI DSS requirements (Level 1)
|
|
|
|
**Fallback Plan**:
|
|
- If Stripe is down, display maintenance message
|
|
- Queue failed payments for manual retry
|
|
- Email customer with payment failure notice</code></pre>
|
|
<h3>Pattern 5: Architecture Diagram (C4 Model - Context Level)</h3>
|
|
<p><strong>Use case</strong>: Illustrating system context for PRD</p>
|
|
<pre><code class="lang-markdown">## System Architecture: Project Management Platform
|
|
|
|
### Context Diagram (C4 Level 1)
|
|
</code></pre>
|
|
<p>┌─────────────────────────────────────────────────────────────┐ │ External Systems │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Stripe │ │ SendGrid │ │ Auth0 │ │ │ │ Payments │ │ Email │ │ SSO │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ └───────┼─────────────────┼──────────────────┼─────────────────┘ │ │ │ │ │ │ ┌───────┼─────────────────┼──────────────────┼─────────────────┐ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Project Management Platform (Web App) │ │ │ │ │ │ │ │ - User authentication & authorization │ │ │ │ - Project creation & management │ │ │ │ - Real-time collaboration │ │ │ │ - Payment processing │ │ │ │ - Email notifications │ │ │ └─────────────────────────────────────────────────┘ │ │ ▲ │ │ │ │ └──────────────────────────┼───────────────────────────────────┘ │ │ ┌────────┴────────┐ │ │ ┌─────▼─────┐ ┌─────▼─────┐ │ Web User │ │ Mobile │ │ (Browser)│ │ User │ └───────────┘ └───────────┘</p>
|
|
<pre><code>
|
|
### Key Interactions
|
|
1. **User → Web App**: HTTPS, JWT authentication
|
|
2. **Web App → Stripe**: Payment processing API (HTTPS, webhook events)
|
|
3. **Web App → SendGrid**: Transactional email API (HTTPS)
|
|
4. **Web App → Auth0**: SSO authentication (OAuth 2.0, optional for enterprise)
|
|
|
|
### Data Flow
|
|
- **User signup**: Web App → SendGrid (verification email)
|
|
- **Subscription purchase**: Web App → Stripe (payment), Stripe → Web App (webhook)
|
|
- **Project creation**: Web App → Database (store), Web App → SendGrid (invite emails)</code></pre>
|
|
<h3>Pattern 6: Migration and Rollout Plan</h3>
|
|
<p><strong>Use case</strong>: Defining how to transition from old to new system</p>
|
|
<pre><code class="lang-markdown">## Migration Plan: Legacy User System → New Authentication System
|
|
|
|
### Current State
|
|
- 50,000 active users on legacy auth (custom built)
|
|
- Passwords stored with MD5 hashing (insecure!)
|
|
- No email verification required
|
|
- No support for 2FA or SSO
|
|
|
|
### Target State
|
|
- All users migrated to new auth system (Auth0 or custom with bcrypt)
|
|
- Passwords re-hashed with bcrypt on first login
|
|
- Email verification enforced for new users
|
|
- 2FA available for all users
|
|
|
|
### Migration Strategy
|
|
|
|
**Phase 1: Dual-Write (Week 1-2)**
|
|
- New signups go directly to new system
|
|
- Existing user logins trigger background migration:
|
|
1. Verify password against legacy system
|
|
2. If correct, hash with bcrypt and store in new system
|
|
3. Mark user as migrated in database flag
|
|
- No user-facing changes (transparent migration)
|
|
|
|
**Phase 2: Email Verification Backfill (Week 3-4)**
|
|
- Send verification emails to unmigrated users (50k total)
|
|
- Require verification on next login
|
|
- Grace period: 30 days before enforcing
|
|
|
|
**Phase 3: Dual-Read (Week 5-6)**
|
|
- Login attempts check new system first
|
|
- If user not migrated, fall back to legacy system and migrate
|
|
- Monitor migration rate (target: 90% in 30 days)
|
|
|
|
**Phase 4: Legacy System Deprecation (Week 7-8)**
|
|
- Force remaining users to reset password (triggers migration)
|
|
- Disable legacy login after 90% migration
|
|
- Archive legacy auth database (don't delete, keep for 1 year)
|
|
|
|
**Rollback Plan**:
|
|
- If migration fails, revert to legacy system
|
|
- Feature flag to toggle new vs legacy auth
|
|
- Monitor error rates (>5% triggers automatic rollback)
|
|
|
|
### Success Metrics
|
|
- 90% of users migrated within 30 days
|
|
- <1% failed login rate during migration
|
|
- Zero security incidents during migration
|
|
- <100 support tickets related to migration</code></pre>
|
|
<h3>Pattern 7: OpenAPI Specification (Formal, Engineering-Led)</h3>
|
|
<p><strong>Use case</strong>: Engineering translates PM's informal API spec into OpenAPI for RFC</p>
|
|
<pre><code class="lang-yaml"># This is what engineering produces in RFC (not PRD)
|
|
# PM provides informal spec, engineering formalizes it
|
|
|
|
openapi: 3.0.0
|
|
info:
|
|
title: User Management API
|
|
version: 1.0.0
|
|
description: API for user account management
|
|
|
|
paths:
|
|
/users:
|
|
post:
|
|
summary: Create user account
|
|
operationId: createUser
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- email
|
|
- password
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: [email protected]
|
|
password:
|
|
type: string
|
|
minLength: 8
|
|
pattern: '^(?=.*[0-9])(?=.*[!@#$%^&*])'
|
|
example: SecurePass1!
|
|
display_name:
|
|
type: string
|
|
maxLength: 50
|
|
example: John Doe
|
|
responses:
|
|
'201':
|
|
description: User created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
format: uuid
|
|
email:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
'400':
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error_code:
|
|
type: string
|
|
enum: [EMAIL_IN_USE, INVALID_PASSWORD]
|
|
error_message:
|
|
type: string
|
|
field_errors:
|
|
type: object</code></pre>
|
|
<p><strong>Note</strong>: PM includes this in PRD appendix only if collaborating closely with engineering</p>
|
|
<h3>Pattern 8: Dependency Matrix</h3>
|
|
<p><strong>Use case</strong>: Tracking all external dependencies and their constraints</p>
|
|
<pre><code class="lang-markdown">## Dependencies: Project Management Platform
|
|
|
|
| Dependency | Purpose | Constraint | Risk | Mitigation |
|
|
|------------|---------|------------|------|------------|
|
|
| Stripe API | Payment processing | 99.9% uptime SLA | Outage blocks upgrades | Queue failed payments, retry |
|
|
| SendGrid API | Transactional email | 50k emails/month (free tier) | Hit limit | Upgrade to paid, throttle emails |
|
|
| Auth0 | SSO (enterprise only) | 7k active users (free tier) | Hit limit | Upgrade or build custom SSO |
|
|
| AWS S3 | File storage (profile photos) | Unlimited storage | Cost scales with usage | Set storage limits per user |
|
|
| PostgreSQL | Primary database | Self-hosted, manual scaling | Performance bottleneck | Plan sharding strategy |
|
|
| Redis | Session cache | Self-hosted, 16GB limit | Out of memory | Increase instance size |
|
|
| Vercel | Web hosting | 100GB bandwidth/month (free) | Hit limit | Upgrade to paid tier |
|
|
|
|
### Critical Dependencies (Failure Impact: High)
|
|
- **Stripe**: Cannot process payments → Revenue loss
|
|
- **PostgreSQL**: Cannot read/write data → Platform down
|
|
|
|
### Optional Dependencies (Failure Impact: Low)
|
|
- **SendGrid**: Cannot send emails → Use fallback (in-app notifications)
|
|
- **Auth0**: Cannot use SSO → Users use email/password login</code></pre>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>PM vs Engineering Technical Ownership</h3>
|
|
<pre><code>PM Owns (PRD) | Engineering Owns (RFC)
|
|
--------------------------|---------------------------
|
|
What data is needed | How data is stored (schema)
|
|
What API does | How API is implemented (REST/GraphQL)
|
|
What constraints exist | How to meet constraints (caching, etc.)
|
|
What integrations needed | How to integrate (API client, webhooks)</code></pre>
|
|
<h3>API Specification Checklist</h3>
|
|
<pre><code>Element | PM Should Define (PRD) | Engineering Should Define (RFC)
|
|
--------|------------------------|--------------------------------
|
|
Endpoint purpose | ✅ | ✅
|
|
Input parameters | ✅ | ✅ (with types, validation)
|
|
Output structure | ✅ | ✅ (with schema)
|
|
Error handling | ✅ | ✅ (with HTTP codes)
|
|
Performance | ✅ (SLA: <100ms) | ✅ (how to achieve)
|
|
Security | ✅ (auth required) | ✅ (JWT implementation)
|
|
Implementation | ❌ | ✅ (framework, libraries)</code></pre>
|
|
<h3>Data Model Detail Levels</h3>
|
|
<pre><code>Level | Owner | Example
|
|
------|-------|--------
|
|
Conceptual | PM (PRD) | "User has many Projects"
|
|
Logical | Engineering (RFC) | Normalized tables, foreign keys
|
|
Physical | Engineering (Code) | DDL, indexes, partitions</code></pre>
|
|
<h3>Key Guidelines</h3>
|
|
<pre><code>✅ DO: Define what the API must do, not how it's built
|
|
✅ DO: Collaborate with engineering on technical feasibility
|
|
✅ DO: Specify performance constraints (e.g., <100ms response)
|
|
✅ DO: Document third-party integrations and dependencies
|
|
✅ DO: Include security and compliance requirements
|
|
|
|
❌ DON'T: Prescribe database schema (that's RFC territory)
|
|
❌ DON'T: Specify frameworks or libraries (engineering decision)
|
|
❌ DON'T: Write formal OpenAPI specs in PRD (engineering's job)
|
|
❌ DON'T: Ignore engineering feedback on constraints
|
|
❌ DON'T: Forget to document migration and rollout plans</code></pre>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>Critical Violations</h3>
|
|
<p>❌ <strong>Over-Specifying Implementation in PRD</strong>: Telling engineering how to build it</p>
|
|
<pre><code class="lang-markdown"># ❌ NEVER (in PRD):
|
|
## Technical Implementation
|
|
- Use PostgreSQL for user table
|
|
- Implement REST API with Express.js
|
|
- Hash passwords with bcrypt cost factor 12
|
|
- Deploy on AWS EC2 t3.medium instances
|
|
|
|
# ✅ CORRECT (in PRD):
|
|
## Technical Constraints
|
|
- Must support 10,000 concurrent users
|
|
- Password storage must meet OWASP guidelines (hashing, salting)
|
|
- API response time <100ms (p95)
|
|
- Must achieve 99.9% uptime SLA
|
|
|
|
[Engineering decides: Postgres vs Mongo, Express vs FastAPI, etc.]</code></pre>
|
|
<p>❌ <strong>Missing Performance Requirements</strong>: Vague "should be fast" instead of SLAs ✅ <strong>Correct approach</strong>: "API must respond in <100ms for p95 latency"</p>
|
|
<h3>Common Mistakes</h3>
|
|
<p>❌ <strong>API Spec Without Error Handling</strong>: Only defining happy path</p>
|
|
<pre><code class="lang-markdown"># ❌ Don't:
|
|
POST /users
|
|
Input: email, password
|
|
Output: user_id
|
|
|
|
# ✅ Correct:
|
|
POST /users
|
|
Input: email, password
|
|
Output (Success): user_id, email, created_at
|
|
Output (Error): error_code, error_message, field_errors
|
|
Error Codes: EMAIL_IN_USE, INVALID_PASSWORD, RATE_LIMIT_EXCEEDED</code></pre>
|
|
<p>❌ <strong>Ignoring Security Constraints</strong>: No mention of auth, encryption, compliance ✅ <strong>Better</strong>: Document auth requirements, data encryption, GDPR compliance</p>
|
|
<p>❌ <strong>Missing Dependency Risks</strong>: Not planning for third-party service failures ✅ <strong>Better</strong>: Document fallback plans for each critical dependency</p>
|
|
<p>❌ <strong>No Migration Plan</strong>: Assuming new system magically replaces old one ✅ <strong>Better</strong>: Define phased rollout with dual-write, dual-read, deprecation</p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>prd-structure-templates.md</code> - Document technical specs within PRD sections</li><li><code>prd-requirements-gathering.md</code> - Gather technical constraints during research</li><li><code>prd-user-stories-acceptance.md</code> - Translate technical requirements into testable stories</li><li><code>engineering/rfc-structure-format.md</code> - Engineering's detailed technical design</li><li><code>engineering/rfc-technical-design.md</code> - Engineering translates PRD specs into implementation</li><li><code>api-design-rest.md</code> - Deep dive on REST API design patterns</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="/product-prd-technical-specifications.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |