Docs Codebase

Technical Documentation

Execution-ready patterns for clear, maintainable technical documentation.

Modern best practices (January 2026): docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.

Quick Reference

Workflow

1. Identify the documentation type and audience. 2. Find existing patterns in the repo; follow local conventions. 3. Start from the closest template in assets/ and adapt. 4. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference). 5. Run documentation QA (links, formatting, spelling, examples) before merging.

Docs Folder / LLM-Generated Revamp Mode (Any Repo)

Use this mode when a repo's docs/ folder contains substantial research notes for LLMs and implementation docs generated by LLMs.

1. Build an inventory and classify each file by doc type (Tutorial, How-to, Reference, Explanation). 2. Mark lifecycle metadata for non-canonical files:

status: draft | canonical | integrated | superseded
owner: @username
last_verified: 2026-02-24
integrates_into: docs/path/to/canonical-doc.md
delete_by: 2026-03-31

3. For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it. 4. Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes. 5. Keep a compact LLM doc library with root anchors: AGENTS.md, README.md, and minimal canonical docs under docs/ (instructions, specs, reference-data). 6. Delete integrated drafts on schedule; avoid .archive/ mirrors in docs/ unless retention is mandatory.

Decision Tree

User needs: [Documentation Task]
    ├─ Repo has a docs folder with many LLM-generated docs? → **Revamp Mode** (inventory → canonicalize → trim)
    ├─ New project? → **README.md**
    ├─ Technical decision? → **ADR**
    ├─ Building API? → **OpenAPI spec** + api-docs-template
    ├─ New version? → **CHANGELOG.md**
    ├─ Team collaboration? → **CONTRIBUTING.md**
    ├─ Documenting code? → **Docstrings** (JSDoc, Python)
    └─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)

Cross-Platform AI Documentation

AGENTS.md Standard

Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.

# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md

Do / Avoid

Do

• Assign owners and review cadences to critical docs
• Add CI checks for links, style, and staleness
• Prefer small, task-oriented docs over big wiki pages
• Use Keep a Changelog format with semantic versioning

Avoid

• Docs without owners (guaranteed to rot)
• Stale runbooks (dangerous during incidents)
• Copy/paste docs that drift from code

LLM-First Documentation Patterns

When documentation is consumed primarily by AI agents (AGENTS.md, CLAUDE.md, canonical docs for coding assistants), stale docs become a distinct category of bug.

Stale Docs = Agent Bugs

An agent reading stale docs will:

• Attempt to fix problems that are already solved (e.g., "9 open gating gaps" that were all sealed)
• Use wrong model names (e.g., "Claude Haiku" when code uses gpt-4o)
• Apply wrong limits (e.g., "fully gated" when free tier actually gets 3/week)
• Re-implement features that already exist

Rule: Treat doc updates as part of the feature PR, not as a follow-up task.

Report Integration Lifecycle

Temporary investigation docs (QA reports, research exports, audit findings) must not become permanent false sources of truth.

Every dated report file must carry lifecycle metadata:

---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---

Workflow: 1. Create report with Status: pending-integration 2. Extract durable findings into canonical docs 3. Mark report Status: integrated with date 4. Delete after Delete-by date (git history preserves everything)

Living Docs: Audit Tables with Status Columns

Instead of deleting audit findings, add a Status column:

This preserves the audit trail while showing current state. Agents can quickly scan for Open items.

Two-Pass Consolidation

When consolidating planning docs into canonical docs:

1. First pass: Follow the plan — extract content, delete source files, fix cross-references 2. Second pass: Audit deleted content against canonical destinations

• git show deleted files to recover any unique data missed in planning
• Compare code to docs for drift (e.g., feature marked "Planned" but code shows it's implemented)

Even thorough consolidation plans miss unique data that only lived in one source doc.

Canonical Set Rule (No Doc Sprawl)

• One subject/feature should have one canonical doc.
• Derived docs must link to canonical docs instead of restating them.
• If a derived doc is fully integrated, mark it integrated and remove it by delete_by (default: delete, not archive).
• If two canonical docs overlap, merge and leave a redirect note in the removed file path.

Canonical LLM Library Rule

• Root files are mandatory anchors: AGENTS.md for agent behavior/instructions and README.md for project navigation.
• The docs/ folder should expose only a small canonical set for LLM consumption: current instruction sets, current specs, and durable reference data.
• Research logs, exploratory prompts, and intermediate drafts are temporary working files, not library entries.
• Keep discovery breadcrumbs as links from canonical docs; do not duplicate full research dumps.

Anti-Fluff Rewrite Gate

Before merging LLM-generated docs, require:

• explicit audience and decision/use-case for each section
• measurable statements instead of vague claims
• source links + dates for external facts
• removal of duplicated paragraphs and "future ideas" not tied to a tracked decision

Staleness Disclaimers Over Wrong Numbers

For externally-sourced data (competitor pricing, API rate limits, third-party capabilities):

> Prices as of Feb 2026 — verify current pricing at [source].

A staleness disclaimer is safer than a potentially wrong number. Wrong numbers in agent-consumed docs cause incorrect implementation decisions.

Decision Log Collision Prevention

When adding entries to a decision log (e.g., ### D039 — Feature Name):

# Always check the latest entry number before adding
grep -o '### D[0-9]*' docs/decision-log.md | tail -1

Numbering collisions happen when two decisions are logged in rapid succession without checking.

Backlog Status Sync Pattern (Mandatory)

When implementation status changes (for example backlog milestones completed), sync canonical docs in the same delivery cycle to prevent stale guidance for humans and agents.

Sync Rules

1. Update one canonical status source first (feature matrix / roadmap / decision log). 2. Propagate only by reference links in secondary docs; avoid duplicate status prose. 3. Add concrete completion dates and owner for status changes. 4. If temporary reports are integrated, mark lifecycle state (integrated or superseded) and delete_by.

Release Gate

A feature is not doc-complete until:

• canonical status doc updated,
• dependent docs checked for conflicting claims,
• docs sync checklist completed.

Resources

Templates

Related Skills

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

API Documentation

Base URL: https://api.example.com/v1

Version: 1.0.0

Last Updated: 2025-01-15

Table of Contents

• Authentication
• Rate Limiting
• Error Handling
• Pagination
• Endpoints
• Users
• Posts
• Comments

Authentication

All API requests require authentication via Bearer token.

Obtaining an Access Token

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Using the Access Token

Include the token in the Authorization header:

GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

• Access tokens expire after 1 hour
• Use the refresh token to obtain a new access token without re-authenticating

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Rate Limiting

API requests are rate-limited to prevent abuse.

Limits:

• Authenticated users: 1000 requests per hour
• Unauthenticated requests: 100 requests per hour

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642521600

Rate Limit Exceeded Response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Error Handling

The API uses standard HTTP status codes and returns errors in RFC 7807 Problem Details format.

Error Response Format

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains invalid data",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Email address is not valid"
    },
    {
      "field": "age",
      "code": "OUT_OF_RANGE",
      "message": "Age must be between 18 and 120"
    }
  ]
}

Status Codes

Pagination

List endpoints support cursor-based pagination.

Request

GET /api/v1/users?limit=20&cursor=eyJpZCI6MTIzfQ

Query Parameters:

Response

{
  "data": [
    { "id": 1, "name": "John Doe", ... },
    { "id": 2, "name": "Jane Smith", ... }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MjB9",
    "has_more": true,
    "total": 150
  }
}

Endpoints

---

Users

List Users

Retrieve a paginated list of users.

GET /api/v1/users

Query Parameters:

Example Request:

curl -X GET "https://api.example.com/v1/users?limit=10&sort=-created_at&status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "avatar_url": "https://cdn.example.com/avatars/john.jpg",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTB9",
    "has_more": true,
    "total": 150
  }
}

---

Get User by ID

Retrieve a specific user by ID.

GET /api/v1/users/:id

Path Parameters:

Example Request:

curl -X GET "https://api.example.com/v1/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "bio": "Software engineer and open source enthusiast",
  "avatar_url": "https://cdn.example.com/avatars/john.jpg",
  "location": "San Francisco, CA",
  "website": "https://johndoe.com",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Error Responses:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

---

Create User

Create a new user.

POST /api/v1/users

Request Body:

{
  "email": "newuser@example.com",
  "name": "New User",
  "password": "SecurePassword123!",
  "bio": "Optional bio text",
  "location": "New York, NY"
}

Required Fields:

Optional Fields:

Example Request:

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "SecurePassword123!"
  }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/660e8400-e29b-41d4-a716-446655440000

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "name": "New User",
  "status": "active",
  "created_at": "2025-01-20T14:30:00Z",
  "updated_at": "2025-01-20T14:30:00Z"
}

Error Responses:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    {
      "field": "email",
      "code": "DUPLICATE_EMAIL",
      "message": "Email address is already registered"
    },
    {
      "field": "password",
      "code": "WEAK_PASSWORD",
      "message": "Password must include at least one uppercase letter"
    }
  ]
}

---

Update User

Update an existing user.

PUT /api/v1/users/:id

Path Parameters:

Request Body:

{
  "name": "Updated Name",
  "bio": "Updated bio text",
  "location": "Los Angeles, CA",
  "website": "https://updated-website.com"
}

All fields are optional. Only provided fields will be updated.

Example Request:

curl -X PUT "https://api.example.com/v1/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John D.",
    "bio": "Updated bio"
  }'

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.doe@example.com",
  "name": "John D.",
  "bio": "Updated bio",
  "status": "active",
  "updated_at": "2025-01-20T15:00:00Z"
}

---

Delete User

Delete a user permanently.

DELETE /api/v1/users/:id

Path Parameters:

Example Request:

curl -X DELETE "https://api.example.com/v1/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

HTTP/1.1 204 No Content

Error Responses:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to delete this user"
  }
}

---

Webhooks

Subscribe to events via webhooks.

Webhook Events

Webhook Payload

{
  "event": "user.created",
  "timestamp": "2025-01-20T14:30:00Z",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "email": "newuser@example.com",
    "name": "New User"
  }
}

Webhook Signature

All webhook requests include an X-Signature header with HMAC-SHA256 signature.

Verify signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

---

SDKs and Libraries

Official SDKs are available for:

• JavaScript/TypeScript
• Python
• Go
• Ruby

---

Support

• Documentation: https://docs.example.com
• API Status: https://status.example.com
• Support Email: api-support@example.com
• Discord: https://discord.gg/example-api

---

Changelog

See API Changelog for version history and breaking changes.

ADR-XXX: [Short Title of Decision]

Status

[Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-YYY]

Context

What is the issue that we're seeing that is motivating this decision or change?

• What is the background context?
• What problem are we trying to solve?
• What are the business/technical constraints?
• What are the forces at play (technical, political, social, project)?

Example:

We need to choose a database for our new microservice that will handle high-volume user profile data. The service must support:

- 10,000+ writes/second

- Complex queries with joins

- ACID transactions

- Horizontal scaling

- Sub-100ms read latency

Decision

We will [decision statement].

Be specific and actionable. State the architecture decision you've made clearly.

Example:

We will use PostgreSQL 15 with read replicas as the primary database for the user profile service.

Consequences

Positive

What becomes easier or better after this decision?

• Benefit 1 with explanation
• Benefit 2 with explanation
• Benefit 3 with explanation

Example:

- Full ACID compliance ensures data integrity for financial transactions

- Rich ecosystem of tools (pgAdmin, PostgREST, Hasura)

- Excellent JSON support via jsonb type for flexible schemas

- Battle-tested at scale (Instagram, Spotify, Reddit)

- Strong community support and extensive documentation

Negative

What becomes more difficult or worse? What tradeoffs are we accepting?

• Drawback 1 with explanation
• Drawback 2 with explanation
• Drawback 3 with explanation

Example:

- Vertical scaling limitations (mitigated with read replicas and sharding)

- More complex operational overhead than managed NoSQL solutions

- Requires careful index design for optimal query performance

- Connection pooling required for high concurrency

Neutral

What changes that are neither positive nor negative?

• Neutral change 1
• Neutral change 2

Example:

- Team needs to learn PostgreSQL-specific features (JSONB, CTEs, window functions)

- Migration from existing SQLite database requires schema transformation

- New monitoring setup required (pg_stat_statements, pg_badger)

Alternatives Considered

Alternative 1: [Name]

Description: Brief description of the alternative

Pros:

• Pro 1
• Pro 2

Cons:

• Con 1
• Con 2

Why rejected: Specific reason this alternative was not chosen

Example:

Alternative 1: MongoDB

Description: Document database with flexible schema

Pros:

• Excellent horizontal scaling with built-in sharding
• Flexible schema allows rapid iteration
• Simple JSON-like document model

Cons:

• No ACID transactions across collections (only at document level)
• Eventual consistency model unsuitable for financial data
• Less mature tooling for complex analytical queries

Why rejected: Lack of ACID transactions is a dealbreaker for our use case

Alternative 2: MySQL

Description: Popular relational database

Pros:

• Wide adoption and large community
• Good performance for read-heavy workloads
• Familiar to most developers

Cons:

• Weaker JSON support compared to PostgreSQL
• Oracle licensing concerns for enterprise use
• Less powerful query optimizer

Why rejected: PostgreSQL's superior JSON support and query capabilities better align with our requirements

Implementation

How will this decision be implemented? Include:

• Specific steps to execute
• Timeline estimates
• Team responsibilities
• Rollback plan

Example:

Phase 1: Infrastructure Setup (Week 1)

• Provision PostgreSQL 15 on AWS RDS
• Configure read replicas in multiple availability zones
• Set up connection pooling with PgBouncer
• Configure automated backups and point-in-time recovery

Responsible: DevOps team

Phase 2: Schema Design (Week 2)

• Design normalized schema for user profiles
• Create indexes for common query patterns
• Implement partitioning strategy for large tables
• Set up migration scripts with Flyway

Responsible: Backend team

Phase 3: Application Integration (Weeks 3-4)

• Implement data access layer with connection pooling
• Add query optimization and caching logic
• Write comprehensive tests for data layer
• Performance testing and tuning

Responsible: Backend team

Phase 4: Migration (Week 5)

• Blue-green deployment with gradual traffic shift
• Data migration from SQLite with validation
• Monitor performance and error rates
• Rollback plan: revert to SQLite if issues detected

Responsible: Full team

Success Metrics

How will we measure if this decision was successful?

• Metric 1: Target value
• Metric 2: Target value
• Metric 3: Target value

Example:

• Write latency: <50ms p95
• Read latency: <10ms p95
• Database uptime: >99.95%
• Zero data inconsistencies
• Query performance: <100ms for complex joins
• Successful migration with <1hr downtime

Risks and Mitigation

What could go wrong, and how will we handle it?

References

• PostgreSQL Documentation
• AWS RDS PostgreSQL Best Practices
• Internal: Database Comparison Spreadsheet (link)
• Internal: Performance Benchmarks (link)

Related ADRs

• ADR-001: Microservices Architecture
• ADR-015: API Design Standards
• Supersedes: ADR-008: SQLite for User Data

Notes

Any additional context, learnings, or future considerations

Example:

This decision assumes our current scale of 10k writes/second. If we exceed 50k writes/second, we should revisit sharding strategies (ADR-XXX) or evaluate NewSQL databases like CockroachDB.

>

PostgreSQL's LISTEN/NOTIFY feature may be useful for real-time updates in the future.

---

Author: John Doe

Date: 2025-01-15

Last Updated: 2025-01-15

Reviewers: Jane Smith (Tech Lead), Bob Johnson (DBA), Alice Williams (Security)

Docs-as-Code Structure Template (Core, Non-AI)

Purpose: define a maintainable documentation structure with ownership and freshness mechanisms.

Inputs

• Product/repo scope (modules, audiences, support burden)
• Tooling constraints (MkDocs/Docusaurus/README-only, CI availability)

Outputs

• Docs information architecture (IA) and folder structure
• Ownership model and freshness SLAs (who updates what, when)

Core

1) Suggested Information Architecture (Diátaxis-style)

• Tutorials: step-by-step learning paths
• How-to guides: task-oriented procedures
• Reference: exhaustive API/config specs
• Explanation: conceptual context and rationale

2) Suggested Repo Layout

docs/
  index.md
  tutorials/
  how-to/
  reference/
  explanation/
  runbooks/
  adr/
  _assets/

If docs live in the root:

• README.md (quick start + links)
• docs/ for deeper content

3) Required “Freshness” Metadata (per page)

• Owner: team or individual
• Last reviewed: date
• Review cadence: monthly / quarterly / yearly

4) CI Checks (recommended)

• Link checker (internal + external if allowed)
• Markdown linting and style guide checks
• “Stale docs” check (fails if last reviewed > cadence)

Decision Rules

• No docs without owners.
• Prefer small, frequently updated docs over giant “wiki pages”.
• If a runbook exists, it must be testable (commands verified and current).

Risks

• Docs drift: code changes, docs don’t
• Over-documentation: too much text, no one reads/updates
• Tooling lock-in: docs format prevents contribution

Optional: AI / Automation

Use only if allowed by policy and data handling rules.

• Generate doc diffs and summarize PR changes; humans review before merging.
• Suggest missing docs based on code changes; do not auto-publish without review.

Docs Ownership Model (Core, Non-AI)

Purpose: make documentation freshness a first-class operational responsibility.

Inputs

• Org structure (teams, on-call, product areas)
• Doc types in scope (README, runbooks, ADRs, API docs, user docs)

Outputs

• Ownership map for doc types and areas
• Review cadence and escalation path for stale docs

Core

Ownership Roles

• Directly Responsible Individual (DRI): accountable for updates and quality
• Approver: reviews for correctness (often tech lead or PM)
• Steward: maintains IA and standards (docs lead or platform team)

Ownership Table

Freshness SLAs

• Runbooks: reviewed at least monthly or after incidents
• API docs: updated with every backward-incompatible change
• README quick start: updated when install/run commands change

Enforcement Options

• CI checks for “last reviewed” dates
• Scheduled issues for upcoming reviews
• On-call post-incident action: update runbook + link

Decision Rules

• If a doc is used during incidents, it must have an owner and a cadence.
• If a doc page has no owner, it is either assigned or deleted.

Risks

• Ownership theatre (owners listed but no time allocated)
• Stale docs increase support burden and incident time

Optional: AI / Automation

Use only if allowed by policy and data handling rules.

• Generate “stale docs” reports and draft updates; humans review before publishing.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• New features that have been added but not yet released

Changed

• Changes to existing functionality

Deprecated

• Features that are marked for removal in upcoming releases

Removed

• Features that have been removed

Fixed

• Bug fixes

Security

• Security patches and improvements

[2.1.0] - 2025-01-20

Added

• User profile avatars with upload functionality (#234)
• Dark mode support across all pages (#245)
• Export data to CSV feature in admin dashboard (#256)
• Rate limiting middleware (100 req/min per user) (#267)
• GraphQL subscriptions for real-time updates (#278)

Changed

• Updated Node.js from 18.x to 20.x LTS (#289)
• Migrated from REST to GraphQL for user queries (breaking change) (#290)
• Improved database query performance by 40% with optimized indexes (#301)
• Refactored authentication flow to use JWT refresh tokens (#312)

Deprecated

• /api/v1/users/search endpoint (use GraphQL users query instead)
• XML response format (will be removed in v3.0.0)

Security

• Updated jsonwebtoken to 9.0.2 to fix CVE-2025-XXXX (#323)
• Implemented Content Security Policy headers (#334)
• Added CSRF protection to all state-changing endpoints (#345)

[2.0.0] - 2024-12-15

Added

• Multi-tenancy support with organization isolation (#123)
• Two-factor authentication via TOTP (#134)
• Comprehensive audit logging for compliance (#145)
• Webhook integration system for third-party apps (#156)
• New /api/v2/reports endpoint for generating analytics reports (#167)

Changed

• BREAKING: Minimum Node.js version is now 18.x (was 16.x)
• BREAKING: Database schema migration required (see migration guide)
• BREAKING: API authentication now requires Bearer token (removed API key support)
• Redesigned user interface with Material Design components
• Improved error messages with more context and troubleshooting steps
• Database connection pooling increased from 10 to 50 connections

Removed

• BREAKING: Legacy XML API endpoints (deprecated in v1.5.0)
• BREAKING: Support for IE11 browser
• Unused oldFeature configuration option
• Deprecated /api/v1/legacy/users endpoint

Fixed

• Memory leak in WebSocket connection handler (#178)
• Race condition in concurrent order processing (#189)
• Incorrect timezone handling for scheduled reports (#190)
• SQL injection vulnerability in search endpoint (CVE-2024-XXXX) (#201)

Security

• Migrated password hashing from bcrypt to Argon2id (#212)
• Implemented rate limiting to prevent brute force attacks (#223)
• Added automated security scanning in CI/CD pipeline (#234)

[1.5.0] - 2024-10-01

Added

• Email notification system with templating (#89)
• User preferences page for customization (#90)
• Bulk import/export functionality for admin users (#91)
• API documentation with interactive Swagger UI (#92)

Changed

• Updated all dependencies to latest versions
• Improved test coverage from 75% to 90%
• Enhanced logging with structured JSON format

Deprecated

• XML API endpoints (use JSON instead, will be removed in v2.0.0)

Fixed

• Pagination bug returning duplicate results (#93)
• Date formatting inconsistency across timezones (#94)
• File upload failing for files >10MB (#95)

[1.4.1] - 2024-09-15

Fixed

• Critical hotfix: Database connection pool exhaustion under high load (#81)
• User session expiring prematurely (#82)
• Incorrect currency conversion in checkout (#83)

Security

• Updated express to 4.18.2 to address ReDoS vulnerability (#84)

[1.4.0] - 2024-09-01

Added

• Search functionality with full-text search (#67)
• User activity dashboard with charts (#68)
• API versioning support (v1 and v2 endpoints) (#69)

Changed

• Improved Docker image size (reduced by 40%) (#70)
• Optimized database queries for better performance (#71)

Fixed

• Login redirect loop for certain edge cases (#72)
• Broken pagination on user list page (#73)

[1.3.0] - 2024-08-01

Added

• OAuth2 authentication with Google and GitHub (#45)
• User roles and permissions system (#46)
• Automated database backups to S3 (#47)

Changed

• Migrated from MongoDB to PostgreSQL (#48)
• Updated UI framework from Bootstrap 4 to Bootstrap 5 (#49)

Fixed

• Performance issues with large dataset exports (#50)
• CORS configuration blocking valid requests (#51)

[1.2.0] - 2024-07-01

Added

• RESTful API with JWT authentication (#23)
• File attachment support for user profiles (#24)
• Admin panel for user management (#25)

Changed

• Improved error handling with better error messages (#26)
• Updated branding and logo (#27)

Fixed

• Form validation errors not displaying correctly (#28)
• Email delivery failures for certain providers (#29)

[1.1.0] - 2024-06-01

Added

• User registration and login functionality (#12)
• Password reset via email (#13)
• Basic user profile management (#14)

Fixed

• Database migration script errors (#15)
• Broken CSS on mobile devices (#16)

[1.0.0] - 2024-05-01

Added

• Initial release of the application
• Basic CRUD operations for resources
• PostgreSQL database integration
• Express.js REST API
• User authentication with JWT
• Docker deployment configuration
• Comprehensive test suite
• CI/CD pipeline with GitHub Actions

---

Version Format

This project follows Semantic Versioning:

• MAJOR version for incompatible API changes
• MINOR version for new features (backward-compatible)
• PATCH version for bug fixes (backward-compatible)

Categories

• Added: New features
• Changed: Changes to existing functionality
• Deprecated: Features marked for removal
• Removed: Removed features
• Fixed: Bug fixes
• Security: Security patches and improvements

Issue References

Each change includes a reference to the related issue/PR number (e.g., #123).

Links

[Unreleased]: https://github.com/username/repo/compare/v2.1.0...HEAD [2.1.0]: https://github.com/username/repo/compare/v2.0.0...v2.1.0 [2.0.0]: https://github.com/username/repo/compare/v1.5.0...v2.0.0 [1.5.0]: https://github.com/username/repo/compare/v1.4.1...v1.5.0 [1.4.1]: https://github.com/username/repo/compare/v1.4.0...v1.4.1 [1.4.0]: https://github.com/username/repo/compare/v1.3.0...v1.4.0 [1.3.0]: https://github.com/username/repo/compare/v1.2.0...v1.3.0 [1.2.0]: https://github.com/username/repo/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/username/repo/compare/v1.0.0...v1.1.0 [1.0.0]: https://github.com/username/repo/releases/tag/v1.0.0

Contributing to [Project Name]

Thank you for your interest in contributing! We welcome contributions from everyone.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• How to Contribute
• Coding Standards
• Commit Message Guidelines
• Pull Request Process
• Testing Guidelines
• Documentation
• Community

Code of Conduct

This project adheres to the CODE_OF_CONDUCT.md. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@example.com.

Getting Started

Prerequisites

Before you begin, ensure you have:

• Node.js 18.0 or higher
• Git
• A GitHub account
• Familiarity with JavaScript/TypeScript
• Basic understanding of the project architecture

Finding Issues to Work On

• Good first issues: Check issues labeled `good first issue`
• Help wanted: Issues labeled `help wanted` are open for contribution
• Bug fixes: Look for issues labeled `bug`

Development Setup

1. Fork the Repository

Fork the repository to your GitHub account by clicking the "Fork" button.

2. Clone Your Fork

git clone https://github.com/YOUR_USERNAME/project-name.git
cd project-name

3. Add Upstream Remote

git remote add upstream https://github.com/original-owner/project-name.git

4. Install Dependencies

npm install

5. Create a Feature Branch

git checkout -b feature/your-feature-name

Branch naming conventions:

• feature/description - New features
• fix/description - Bug fixes
• docs/description - Documentation changes
• refactor/description - Code refactoring
• test/description - Test improvements

6. Run Development Server

npm run dev

The application will be available at http://localhost:3000

7. Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

How to Contribute

Reporting Bugs

Before creating a bug report, please check if the issue already exists.

When filing a bug report, include:

• Title: Clear, descriptive summary
• Description: Detailed description of the issue
• Steps to Reproduce: Step-by-step instructions
• Expected Behavior: What should happen
• Actual Behavior: What actually happens
• Environment: OS, Node.js version, browser (if applicable)
• Screenshots: If applicable
• Logs: Relevant error messages or logs

Bug Report Template:

## Description
A clear description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- OS: [e.g., macOS 13.0]
- Node.js: [e.g., 18.16.0]
- Browser: [e.g., Chrome 115]

## Additional Context
Any other context, screenshots, or logs.

Suggesting Enhancements

Enhancement suggestions are welcome! Please create an issue with:

• Clear title: Concise description of the enhancement
• Use case: Why this enhancement would be useful
• Detailed description: How it should work
• Mockups/Examples: If applicable

Submitting Code Changes

1. Create or find an issue: Ensure there's an issue for your change 2. Discuss your approach: Comment on the issue before starting work 3. Fork and create a branch: Follow the branching guidelines 4. Make your changes: Write code following our standards 5. Write tests: Add tests for new functionality 6. Update documentation: Update relevant docs 7. Run tests and linters: Ensure all checks pass 8. Commit your changes: Use conventional commit messages 9. Push to your fork: git push origin feature/your-feature 10. Open a Pull Request: From your fork to the main repository

Coding Standards

JavaScript/TypeScript Style

We follow the Airbnb JavaScript Style Guide with some modifications.

Key Points:

• Use 2 spaces for indentation
• Use single quotes for strings
• Always use semicolons
• Use camelCase for variables and functions
• Use PascalCase for classes and types
• Use UPPER_SNAKE_CASE for constants
• Prefer const over let, avoid var
• Use arrow functions for anonymous functions
• Use template literals for string interpolation

Example:

// Good
const getUserName = (user) => {
  return user.firstName + ' ' + user.lastName;
};

const MAX_RETRY_COUNT = 3;

// Bad
var get_user_name = function(user) {
  return user.firstName + " " + user.lastName
}

const maxRetryCount = 3;

Linting and Formatting

Run ESLint and Prettier before committing:

# Lint code
npm run lint

# Fix linting errors automatically
npm run lint:fix

# Format code
npm run format

# Type check (TypeScript)
npm run type-check

Pre-commit hook automatically runs these checks.

TypeScript Guidelines

• Use strict type checking
• Avoid any type (use unknown if type is truly unknown)
• Define interfaces for all object shapes
• Use type guards for type narrowing
• Document complex types with JSDoc comments

Example:

// Good
interface User {
  id: string;
  name: string;
  email: string;
}

function getUser(id: string): User | null {
  // implementation
}

// Bad
function getUser(id: any): any {
  // implementation
}

File and Folder Structure

src/
├── api/            # API routes and controllers
├── models/         # Database models
├── services/       # Business logic
├── utils/          # Helper functions
├── types/          # TypeScript type definitions
└── __tests__/      # Test files (co-located with source)

Commit Message Guidelines

We follow the Conventional Commits specification.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or updating tests
• build: Build system or dependency changes
• ci: CI configuration changes
• chore: Other changes that don't modify src or test files

Scope

Optional, indicates the area of the codebase (e.g., auth, api, ui).

Subject

• Use imperative mood ("add" not "added")
• Don't capitalize first letter
• No period at the end
• Limit to 50 characters

Body

• Optional, provides additional context
• Wrap at 72 characters
• Explain what and why, not how

Footer

• Optional, references issues or breaking changes
• Use Closes #123 to auto-close issues
• Use BREAKING CHANGE: for breaking changes

Examples

feat(auth): add OAuth2 authentication

Implements OAuth2 authorization code flow with Google and GitHub providers.
Includes token refresh and secure storage.

Closes #123

fix(api): handle null response from database

Adds null check before accessing user.email property to prevent TypeError.

Fixes #456

docs: update API documentation for v2 endpoints

BREAKING CHANGE: v1 endpoints are deprecated and will be removed in next major release

Pull Request Process

Before Submitting

• [ ] Create an issue if one doesn't exist
• [ ] Fork the repository
• [ ] Create a feature branch
• [ ] Write code following our standards
• [ ] Add tests for new functionality
• [ ] Update documentation
• [ ] Run tests: npm test
• [ ] Run linter: npm run lint
• [ ] Ensure type checking passes: npm run type-check
• [ ] Commit with conventional commit messages
• [ ] Rebase on latest main if needed

PR Title and Description

Title Format:

<type>(<scope>): <short summary>

Description Template:

## Description
Brief description of changes

## Related Issue
Closes #123

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] All tests pass locally
- [ ] Added tests for new functionality
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added and passing

## Screenshots (if applicable)

Review Process

1. Automated checks: CI must pass (tests, linting, type checking) 2. Code review: At least one maintainer approval required 3. Discussion: Address reviewer feedback 4. Approval: Once approved, a maintainer will merge

After PR is Merged

1. Delete your feature branch 2. Pull latest main: git pull upstream main 3. Thank the reviewers!

Testing Guidelines

Writing Tests

• Unit tests: Test individual functions and modules
• Integration tests: Test interactions between components
• E2E tests: Test complete user workflows

Test Structure

describe('Feature Name', () => {
  describe('functionName', () => {
    it('should do something specific', () => {
      // Arrange
      const input = 'test';

      // Act
      const result = functionName(input);

      // Assert
      expect(result).toBe('expected output');
    });

    it('should handle edge cases', () => {
      expect(() => functionName(null)).toThrow();
    });
  });
});

Test Coverage

• Aim for >80% code coverage
• All new features must include tests
• Bug fixes should include regression tests

# Check coverage
npm run test:coverage

# View HTML report
open coverage/index.html

Documentation

Code Documentation

• Add JSDoc comments for public APIs
• Explain complex logic with inline comments
• Keep comments up-to-date with code changes

User Documentation

• Update README.md for user-facing changes
• Add examples to docs/ folder
• Update API documentation for endpoint changes

Writing Good Documentation

• Use clear, concise language
• Include code examples
• Explain the "why" not just the "what"
• Keep documentation DRY (Don't Repeat Yourself)

Community

Getting Help

• Discord: https://discord.gg/project-name
• GitHub Discussions: https://github.com/username/repo/discussions
• Stack Overflow: Tag with project-name

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md
• GitHub contributor graph
• Release notes

License

By contributing, you agree that your contributions will be licensed under the project's LICENSE.

---

Questions? Feel free to ask in GitHub Discussions or on Discord.

Thank you for contributing! [CELEBRATE]

Project Name

Brief one-line description of what this project does and why it exists.

Features

• Key feature 1
• Key feature 2
• Key feature 3
• Key feature 4

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18.0 or higher
• PostgreSQL 14 or higher
• Redis 7.0 or higher (optional, for caching)

Installation

1. Clone the repository

git clone https://github.com/username/project-name.git
cd project-name

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Edit .env with your configuration:

PORT=3000
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
REDIS_URL=redis://localhost:6379
API_KEY=your-api-key-here

4. Initialize database

npm run db:migrate
npm run db:seed

5. Start development server

npm run dev

The application will be available at http://localhost:3000

Configuration

Environment Variables

Usage

Basic Example

const { Client } = require('@yourorg/package');

const client = new Client({
  apiKey: process.env.API_KEY
});

async function example() {
  const result = await client.doSomething({
    param: 'value'
  });
  console.log(result);
}

example();

Advanced Example

const { Client, Config } = require('@yourorg/package');

const config = new Config({
  apiKey: process.env.API_KEY,
  timeout: 5000,
  retries: 3
});

const client = new Client(config);

async function advancedExample() {
  try {
    const result = await client.doComplexOperation({
      filters: { category: 'example' },
      sort: 'name',
      limit: 10
    });

    result.items.forEach(item => {
      console.log(item.name);
    });
  } catch (error) {
    console.error('Operation failed:', error.message);
  }
}

advancedExample();

API Documentation

REST API Endpoints

Base URL: https://api.example.com/v1

Authentication

All requests require authentication via Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/users

Endpoints

• GET /api/v1/users - List all users
• POST /api/v1/users - Create a new user
• GET /api/v1/users/:id - Get user by ID
• PUT /api/v1/users/:id - Update user
• DELETE /api/v1/users/:id - Delete user

For complete API documentation, see docs/API.md.

Development

Project Structure

project-name/
├── src/
│   ├── api/           # API routes and controllers
│   ├── models/        # Database models
│   ├── services/      # Business logic
│   ├── utils/         # Helper functions
│   └── index.js       # Application entry point
├── tests/             # Test files
├── docs/              # Documentation
├── scripts/           # Build and deployment scripts
├── .env.example       # Example environment variables
├── package.json       # Dependencies and scripts
└── README.md          # This file

Available Scripts

# Development
npm run dev              # Start development server with hot reload
npm run dev:debug        # Start with debugger attached

# Building
npm run build            # Build for production
npm run build:watch      # Build with watch mode

# Testing
npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Run tests with coverage report
npm run test:e2e         # Run end-to-end tests

# Code Quality
npm run lint             # Run ESLint
npm run lint:fix         # Fix ESLint errors automatically
npm run format           # Format code with Prettier
npm run type-check       # Run TypeScript type checking

# Database
npm run db:migrate       # Run database migrations
npm run db:seed          # Seed database with sample data
npm run db:reset         # Reset database (drop + migrate + seed)

# Utilities
npm run clean            # Remove build artifacts
npm run docs             # Generate documentation

Testing

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- path/to/test.js

# Run tests in watch mode
npm run test:watch

Writing Tests

Tests are located in the tests/ directory and follow this naming convention: *.test.js

Example test:

const { calculateTotal } = require('../src/utils');

describe('calculateTotal', () => {
  it('should calculate total with tax', () => {
    const result = calculateTotal(100, 0.08);
    expect(result).toBe(108);
  });

  it('should throw error for negative price', () => {
    expect(() => calculateTotal(-10, 0.08)).toThrow();
  });
});

Deployment

Production Build

npm run build
npm start

Docker

# Build image
docker build -t project-name .

# Run container
docker run -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  -e API_KEY=... \
  project-name

Docker Compose

docker-compose up -d

For detailed deployment instructions, see docs/DEPLOYMENT.md.

Architecture

This project follows a layered architecture:

• API Layer: Express routes and controllers
• Service Layer: Business logic and orchestration
• Data Layer: Database models and queries
• Infrastructure: Configuration, logging, error handling

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

1. Fork the repository 2. Create a feature branch: git checkout -b feature/your-feature-name 3. Make your changes 4. Run tests: npm test 5. Commit with conventional commits: git commit -m "feat: add new feature" 6. Push to your fork: git push origin feature/your-feature-name 7. Open a Pull Request

Troubleshooting

Common Issues

Issue: Database connection fails

• Verify DATABASE_URL is correct
• Check PostgreSQL is running: pg_isready
• Ensure database exists: createdb dbname
• Check network connectivity and firewall rules

Issue: Port already in use

• Change PORT in .env file
• Or kill process using the port: lsof -ti:3000 | xargs kill

Issue: Module not found errors

• Delete node_modules and reinstall: rm -rf node_modules && npm install
• Clear npm cache: npm cache clean --force

Issue: TypeScript errors

• Regenerate types: npm run type-check
• Update @types/* packages: npm update @types/*

For more troubleshooting help, see docs/TROUBLESHOOTING.md or open an issue.

Performance

• Supports 1000+ requests/second
• Average response time: <50ms
• Database connection pooling enabled
• Redis caching for frequently accessed data

Security

• Input validation on all endpoints
• SQL injection protection via parameterized queries
• XSS protection with content security policy
• Rate limiting: 100 requests/min per IP
• API keys encrypted at rest

For security issues, please email security@example.com instead of opening a public issue.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: https://docs.example.com
• Issues: https://github.com/username/project-name/issues
• Discord: https://discord.gg/project-name
• Email: support@example.com

Changelog

See CHANGELOG.md for a list of changes.

Acknowledgments

• Express - Web framework
• PostgreSQL - Database
• Redis - Caching layer
• All our contributors

---

Built with ❤ by [Your Team Name](https://example.com)

Template: Documentation Sync Checklist

Use this after implementation milestones to keep docs consistent.

Context

• Milestone/feature set: _____________________________
• Canonical status doc: ____________________________
• Date: YYYY-MM-DD
• Owner: ________________________________________

Checklist

• [ ] Canonical status source updated with date and owner.
• [ ] Dependent docs checked for stale/conflicting status text.
• [ ] Temporary reports marked with lifecycle metadata.
• [ ] Integrated reports marked integrated or superseded.
• [ ] delete_by dates assigned for temporary docs.
• [ ] Links updated to canonical source (no duplicated policy prose).

Conflict Log

Closure

• [ ] Sync complete
• [ ] Follow-up required
• Follow-up owner/date: ____________________________

Architecture Decision Records (ADRs) - Writing Guide

Complete guide for documenting architectural and technical decisions using Architecture Decision Records (ADRs).

What Are ADRs?

Architecture Decision Records document important architectural decisions made during a project's lifecycle, including the context, decision, and consequences.

Purpose:

• Create searchable history of why decisions were made
• Onboard new team members quickly
• Prevent repeating past mistakes
• Document trade-offs and alternatives considered

When to write an ADR:

• [OK] Choosing a database technology
• [OK] Selecting a framework or library
• [OK] Architectural pattern changes (microservices, event-driven, etc.)
• [OK] Authentication/authorization approach
• [OK] Deployment strategy
• [OK] API design standards
• [OK] Testing strategy
• [FAIL] Minor refactoring (no ADR needed)
• [FAIL] Bug fixes (no ADR needed)
• [FAIL] Temporary workarounds (no ADR needed)

ADR Structure

Every ADR should follow this structure:

1. Title

Format: ADR-NNN: [Verb] [Technology/Pattern] for [Purpose]

Examples:

• ADR-001: Use PostgreSQL for Primary Database
• ADR-002: Implement Event-Driven Architecture with Kafka
• ADR-003: Adopt TypeScript for Frontend Development
• ADR-004: Use JWT for API Authentication

Best practices:

• Sequential numbering (001, 002, 003...)
• Action verb (Use, Implement, Adopt, Replace)
• Specific technology/pattern
• Clear purpose

2. Status

Purpose: Track the decision lifecycle.

Valid statuses:

• Proposed - Under discussion
• Accepted - Decision approved and active
• Deprecated - Still in use but being phased out
• Superseded - Replaced by another decision (link to new ADR)
• Rejected - Considered but not implemented

Format:

## Status

Accepted

Date: 2025-11-22

Status transitions:

Proposed → Accepted → Deprecated → Superseded
         ↓
       Rejected

3. Context

Purpose: Explain the problem, constraints, and requirements.

What to include:

• Problem statement
• Current situation
• Constraints (technical, business, time, budget)
• Requirements (functional and non-functional)
• Stakeholder concerns

Format:

## Context

We need a primary database for our e-commerce platform that will:

- Handle 10,000+ transactions per day
- Support complex queries with joins
- Provide ACID guarantees for financial data
- Scale to 1TB+ of data over 3 years
- Work with our Node.js backend

**Constraints**:
- Team has limited DBA expertise
- Budget: $500/month for managed hosting
- Must deploy in 3 months

**Current situation**:
- Using SQLite for prototype
- SQLite cannot handle production load
- Need production-ready solution

Best practices:

• Be specific with numbers (users, transactions, data size)
• Include timeline constraints
• Mention team expertise/limitations
• Reference business requirements

4. Decision

Purpose: State what was decided clearly and concisely.

Format:

## Decision

We will use PostgreSQL 14+ as our primary database.

**Implementation**:
- PostgreSQL 14.5 on managed AWS RDS
- Multi-AZ deployment for high availability
- Automated daily backups with 7-day retention
- Connection pooling with PgBouncer

Best practices:

• Start with declarative statement
• Include version numbers
• Specify deployment details
• Mention critical configuration

5. Consequences

Purpose: Document impacts (positive, negative, neutral).

Format:

## Consequences

### Positive

- **ACID compliance** - Full transaction guarantees for financial data
- **Rich ecosystem** - Extensive tooling (pgAdmin, PostgREST, TimescaleDB)
- **JSON support** - Native JSONB for semi-structured data
- **Performance** - Excellent query optimizer for complex joins
- **Community** - Large community, extensive documentation

### Negative

- **Vertical scaling limitations** - Single-node writes limit scale
- **Operational complexity** - More complex than MongoDB for simple CRUD
- **Cost** - $400/month for managed RDS Multi-AZ
- **Learning curve** - Team needs to learn SQL optimization

### Neutral

- **Migration effort** - 2-3 weeks to migrate from SQLite
- **Backup strategy** - Need to implement point-in-time recovery

Best practices:

• Be honest about negatives
• Include costs (time, money, complexity)
• Quantify impacts where possible
• Consider long-term implications

6. Alternatives Considered

Purpose: Document options that were rejected and why.

Format:

## Alternatives Considered

### MySQL 8.0

**Pros**:
- Similar to PostgreSQL in features
- Team has MySQL experience
- Slightly cheaper hosting

**Cons**:
- Weaker JSON support than PostgreSQL
- Oracle licensing concerns
- Less advanced query optimizer

**Why rejected**: PostgreSQL's superior JSON support and query optimizer outweigh familiarity with MySQL.

### MongoDB 6.0

**Pros**:
- Simpler schema-less design
- Horizontal scaling built-in
- Team has MongoDB experience

**Cons**:
- No ACID transactions across collections (until v4.0)
- Eventual consistency model risky for financial data
- Weak support for complex joins

**Why rejected**: Lack of strong ACID guarantees unacceptable for financial transactions.

### DynamoDB

**Pros**:
- Fully managed by AWS
- Excellent horizontal scaling
- Pay-per-use pricing

**Cons**:
- Vendor lock-in to AWS
- Complex query limitations
- Expensive for consistent workloads
- No joins or complex queries

**Why rejected**: Query limitations and vendor lock-in outweigh scaling benefits.

Best practices:

• Include at least 2-3 alternatives
• Be fair to alternatives (honest pros/cons)
• Explain rejection rationale clearly
• Consider similar complexity options

7. Implementation (Optional)

Purpose: Next steps and migration plan.

Format:

## Implementation

### Phase 1: Setup (Week 1)
- [ ] Provision PostgreSQL RDS instance
- [ ] Configure security groups and VPC
- [ ] Set up PgBouncer connection pooling
- [ ] Configure automated backups

### Phase 2: Migration (Weeks 2-3)
- [ ] Create PostgreSQL schema from SQLite
- [ ] Write data migration scripts
- [ ] Test migration on staging environment
- [ ] Migrate production data (scheduled downtime)

### Phase 3: Verification (Week 4)
- [ ] Performance testing
- [ ] Data integrity validation
- [ ] Monitoring and alerting setup
- [ ] Documentation update

**Owner**: Backend team
**Target date**: 2025-12-15

8. References

Purpose: Link to relevant documentation and resources.

Format:

## References

- PostgreSQL Documentation: https://www.postgresql.org/docs/
- AWS RDS Best Practices: https://docs.aws.amazon.com/rds/
- Internal database comparison spreadsheet: [Google Drive link]
- Slack discussion: #architecture channel, Nov 10-15
- Performance benchmarks: [Confluence link]

Complete ADR Example

# ADR-001: Use PostgreSQL for Primary Database

## Status

Accepted

Date: 2025-11-22

## Context

We need a primary database for our e-commerce platform that will:

- Handle 10,000+ transactions per day
- Support complex queries with joins (orders + products + users)
- Provide ACID guarantees for financial data
- Scale to 1TB+ of data over 3 years
- Work with our Node.js backend

**Constraints**:
- Team has limited DBA expertise
- Budget: $500/month for managed hosting
- Must deploy in 3 months
- Need high availability (99.9% uptime SLA)

**Current situation**:
- Using SQLite for prototype
- SQLite cannot handle production load (50 concurrent users)
- Need production-ready solution with automatic failover

## Decision

We will use PostgreSQL 14+ as our primary database.

**Implementation**:
- PostgreSQL 14.5 on managed AWS RDS
- Multi-AZ deployment for high availability
- db.t3.medium instance (2 vCPU, 4GB RAM)
- Automated daily backups with 7-day retention
- Connection pooling with PgBouncer (50 connections)

## Consequences

### Positive

- **ACID compliance** - Full transaction guarantees for financial data
- **Rich ecosystem** - Extensive tooling (pgAdmin, PostgREST, TimescaleDB)
- **JSON support** - Native JSONB for semi-structured data (product attributes)
- **Performance** - Excellent query optimizer for complex joins
- **Community** - Large community, extensive documentation, Stack Overflow support

### Negative

- **Vertical scaling limitations** - Single-node writes limit scale to ~10k writes/sec
- **Operational complexity** - More complex than MongoDB for simple CRUD
- **Cost** - $400/month for managed RDS Multi-AZ (within budget)
- **Learning curve** - Team needs to learn SQL optimization (2-week ramp-up)

### Neutral

- **Migration effort** - 2-3 weeks to migrate from SQLite (50k rows)
- **Backup strategy** - Need to implement point-in-time recovery (AWS RDS built-in)

## Alternatives Considered

### MySQL 8.0

**Pros**:
- Similar to PostgreSQL in features
- Team has MySQL experience (2 developers)
- Slightly cheaper hosting ($350/month)

**Cons**:
- Weaker JSON support than PostgreSQL (JSON vs JSONB)
- Oracle licensing concerns
- Less advanced query optimizer

**Why rejected**: PostgreSQL's superior JSON support and query optimizer outweigh familiarity with MySQL.

### MongoDB 6.0

**Pros**:
- Simpler schema-less design
- Horizontal scaling built-in (sharding)
- Team has MongoDB experience (1 developer)

**Cons**:
- No ACID transactions across collections (until v4.0)
- Eventual consistency model risky for financial data
- Weak support for complex joins (requires $lookup aggregation)

**Why rejected**: Lack of strong ACID guarantees unacceptable for financial transactions.

### DynamoDB

**Pros**:
- Fully managed by AWS (zero operational overhead)
- Excellent horizontal scaling (millions of requests/sec)
- Pay-per-use pricing (~$200/month for our workload)

**Cons**:
- Vendor lock-in to AWS
- Complex query limitations (no joins, limited filtering)
- Expensive for consistent workloads
- No complex queries or analytics

**Why rejected**: Query limitations and vendor lock-in outweigh scaling benefits. Analytics queries impossible.

## Implementation

### Phase 1: Setup (Week 1)
- [ ] Provision PostgreSQL RDS instance (db.t3.medium, Multi-AZ)
- [ ] Configure security groups and VPC (private subnet)
- [ ] Set up PgBouncer connection pooling (50 connections)
- [ ] Configure automated backups (daily, 7-day retention)

### Phase 2: Migration (Weeks 2-3)
- [ ] Create PostgreSQL schema from SQLite (using pg_dump equivalent)
- [ ] Write data migration scripts (Python with psycopg2)
- [ ] Test migration on staging environment (10k test records)
- [ ] Migrate production data (scheduled 2-hour downtime window)

### Phase 3: Verification (Week 4)
- [ ] Performance testing (10k concurrent users with k6)
- [ ] Data integrity validation (checksum comparison)
- [ ] Monitoring and alerting setup (CloudWatch + PagerDuty)
- [ ] Documentation update (runbooks, connection strings)

**Owner**: Backend team (John, Sarah)
**Target date**: 2025-12-15
**Estimated effort**: 80 hours

## References

- PostgreSQL Documentation: https://www.postgresql.org/docs/14/
- AWS RDS Best Practices: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_BestPractices.html
- Internal database comparison spreadsheet: https://docs.google.com/spreadsheets/d/xyz
- Slack discussion: #architecture channel, Nov 10-15
- Performance benchmarks: https://confluence.internal/benchmarks
- ADR template: [Link to this template]

ADR Naming Convention

File naming:

docs/adr/
├── 0001-use-postgresql-for-primary-database.md
├── 0002-implement-event-driven-architecture.md
├── 0003-adopt-typescript-for-frontend.md
└── README.md  # Index of all ADRs

Numbering:

• Zero-padded (0001, 0002, not 1, 2)
• Sequential (no gaps)
• Never reuse numbers

ADR Index (README)

Create an index in docs/adr/README.md:

# Architecture Decision Records

## Active ADRs

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-postgresql-for-primary-database.md) | Use PostgreSQL for Primary Database | Accepted | 2025-11-22 |
| [0002](0002-implement-event-driven-architecture.md) | Implement Event-Driven Architecture | Accepted | 2025-11-25 |

## Deprecated ADRs

| ADR | Title | Status | Date | Superseded By |
|-----|-------|--------|------|---------------|
| [0003](0003-use-mongodb.md) | Use MongoDB for Sessions | Superseded | 2025-10-01 | ADR-0001 |

Architecture Doc State Separation

Architecture documents (ADRs, design docs, migration specs) must distinguish three states:

• Verified current state: what has been confirmed against actual repos, contracts, and runtime behavior — not inherited from stale summaries.
• Selected target state: the decided direction, with explicit ADR or decision reference.
• Unresolved gaps: what is still open, who owns resolution, and when it is expected to close.

Flattening these together makes docs unsafe to trust. Cross-repo architecture claims (participating repo inventories, event flows, contract surfaces, publication-safety assertions) must be repo-verified, not copied from prior documentation.

For platform libraries, stale docs are not cosmetic — they change how future engineers and agents modify the code. Update docs and ADRs in the same delivery cycle as runtime behavior changes.

---

ADR Anti-Patterns

BAD: Avoid:

• No context - Decision without explaining why
• No alternatives - Looks like no research was done
• No consequences - Ignoring trade-offs
• Too vague - "Use a database" instead of "Use PostgreSQL 14"
• Too detailed - Implementation code in ADR (link to PRs instead)
• No date - Can't track when decision was made
• Retroactive ADRs - Writing ADRs for old decisions (acceptable for critical legacy decisions)

ADR Best Practices

GOOD: Do:

• Write ADRs when decision is made (not before, not after)
• Keep ADRs immutable (don't edit after acceptance)
• Supersede with new ADRs (don't delete old ADRs)
• Be specific with versions and dates
• Include quantitative data (numbers, metrics)
• Link to related ADRs
• Update index/README when adding ADRs
• Get team review before accepting
• Store ADRs in version control with code

ADR Tools

Generators:

• adr-tools - CLI for creating/managing ADRs
• log4brains - ADR management with web UI

Installation:

# adr-tools
npm install -g adr-log

# Create new ADR
adr new "Use PostgreSQL for Primary Database"

Templates:

• MADR - Markdown ADR format
• Nygard ADRs - Original format

ADR Review Checklist

Before accepting an ADR, verify:

• [ ] Title follows naming convention
• [ ] Status is set (Proposed/Accepted)
• [ ] Date is included
• [ ] Context explains the problem clearly
• [ ] Decision is specific (versions, technologies)
• [ ] Consequences include positives AND negatives
• [ ] At least 2-3 alternatives considered
• [ ] Alternatives have fair pros/cons
• [ ] References link to relevant docs
• [ ] File named with sequential number
• [ ] Index/README updated

After-Action Reviews (January 2026 Best Practice)

Purpose: Review each ADR one month after acceptance to compare documented expectations with actual outcomes.

When to conduct:

• 1 month after ADR acceptance (standard)
• After major milestone completion
• When unexpected issues arise related to the decision

Review Process:

1. Schedule the Review

## After-Action Review

**ADR**: ADR-001: Use PostgreSQL for Primary Database
**Review Date**: 2026-01-22 (30 days after acceptance)
**Attendees**: Backend team, Tech Lead

2. Review Questions

Ask these questions during the review:

• Did the decision achieve its stated goals?
• Were there unexpected consequences (positive or negative)?
• Did the predicted costs and benefits materialize?
• Would we make the same decision today with current knowledge?
• What should we document for future similar decisions?

3. Document Findings

### After-Action Review - 2026-01-22

**Goals Achieved**:
- [OK] ACID compliance working as expected for financial data
- [OK] Query performance meets requirements (avg 50ms)
- [PARTIAL] JSON support used less than expected

**Unexpected Consequences**:
- Positive: PgBouncer connection pooling reduced costs by 20%
- Negative: Backup restore took 4 hours (expected 1 hour)

**Lessons Learned**:
- Test backup restore procedures before production
- Consider read replicas earlier for reporting workloads

**Recommendation**: No changes to ADR status. Add backup testing to future ADR checklist.

4. Readout Meeting Style

AWS recommends a "readout meeting" approach:

1. Attendees spend 10-15 minutes reading the ADR silently 2. Written comments on sections requiring clarification 3. Discussion of differing opinions 4. Keep total participants under 10 people

After-Action Review Checklist:

• [ ] Review scheduled 30 days after acceptance
• [ ] Original decision-makers invited
• [ ] Affected teams represented
• [ ] Goals vs actuals documented
• [ ] Lessons learned captured
• [ ] ADR index updated if status changed

---

When to Update ADRs

Never edit accepted ADRs. Instead:

1. Status change: Create new ADR that supersedes it 2. New information: Create new ADR referencing the old one 3. Implementation details: Update separate implementation docs

Example:

• ADR-001: Use PostgreSQL (Accepted) → Later becomes (Superseded by ADR-010)
• ADR-010: Migrate to CockroachDB (Accepted)

ADR Success Criteria

A good ADR enables readers to:

1. [OK] Understand the problem and constraints 2. [OK] See what was decided and why 3. [OK] Know what alternatives were considered 4. [OK] Understand trade-offs and consequences 5. [OK] Find references for more context 6. [OK] Determine if decision is still valid

Quality metrics:

• Time to understand decision: < 5 minutes
• Completeness: All sections filled
• Clarity: No ambiguous statements
• Traceability: Links to discussions, docs, PRs

AI Documentation Tools (January 2026)

Guide for using AI-powered tools to create, maintain, and optimize technical documentation.

---

Overview

AI tools are transforming documentation workflows. Key trends for 2026:

• MCP-based tooling for context-aware docs maintenance
• Multi-agent workflows for writing and review
• Real-time content synchronization with product updates
• GEO (Generative Engine Optimization) for AI search visibility

---

Tool Categories

API & Developer Documentation Platforms

Code Documentation Tools

Documentation Site Generators (with AI features)

---

MCP Servers for Documentation

Model Context Protocol (MCP) enables AI agents to access documentation context directly.

What MCP Enables

• AI reads documentation files in real-time
• Automatic sync between code changes and docs
• Multi-agent documentation workflows
• Context-aware documentation suggestions

MCP Documentation Workflow

Code Change → MCP Server detects change → AI agent reads context
    ↓
AI generates doc update → Human review → Merge

Setting Up MCP for Docs

Treat this as a pattern, not a copy/paste contract: MCP packages, names, and configuration differ across ecosystems and versions.

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "env": {
        "DOCS_PATH": "./docs"
      }
    }
  }
}

Use cases:

• Auto-update API docs when endpoints change
• Generate changelog entries from commits
• Keep README installation steps in sync with package.json
• Suggest documentation improvements based on code patterns

---

AI Documentation Workflows

1. Draft Generation

Use AI to generate first drafts:

Human: Generate API documentation for the /users endpoint
AI: [Generates documentation based on code context]
Human: Review and refine → Merge

Best practices:

• Always human-review AI-generated content before publishing
• Use AI for structure and first draft, humans for accuracy
• Maintain terminology consistency with style guides

2. Documentation Maintenance

Automated sync workflows:

# .github/workflows/docs-sync.yml
name: Sync Docs with Code

on:
  push:
    paths:
      - 'src/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate API Docs
        run: npm run generate-docs
      - name: Create PR if changed
        uses: peter-evans/create-pull-request@v5
        with:
          title: "docs: Auto-update API documentation"
          body: "Automated documentation update based on code changes"

3. AI-Assisted Review

Use AI to review documentation quality:

• Check for outdated information
• Identify missing sections
• Suggest clarity improvements
• Validate code examples

---

GEO: Generative Engine Optimization

GEO optimizes content for AI-driven search and recommendation engines (not just traditional SEO).

GEO Principles for Docs

1. Structured data: Use consistent headers, lists, and tables 2. Clear definitions: Define terms explicitly for AI parsing 3. Complete examples: Include runnable code examples 4. Semantic markup: Use appropriate HTML/Markdown structure 5. Avoid ambiguity: Be explicit about concepts and relationships

GEO Checklist

• REQUIRED: Headers follow logical hierarchy (H1 → H2 → H3)
• REQUIRED: Code blocks have language tags
• REQUIRED: Tables use consistent formatting
• REQUIRED: Links have descriptive text (not "click here")
• REQUIRED: Terms are defined on first use
• REQUIRED: Examples are complete and runnable

---

Tool Evaluation Checklist

For API Documentation Platforms

• REQUIRED: OpenAPI/GraphQL/gRPC import or source-of-truth workflow that fits your stack
• REQUIRED: Versioning + changelog support (or an integration that provides it)
• REQUIRED: Search (and analytics for search quality in production)
• BEST: Auth-aware examples, SDK snippet generation, webhooks/events documentation support
• BEST: Link checking, style gates, and preview environments in CI

For Code Documentation Tools

• REQUIRED: Incremental updates (avoid regenerating everything on every run)
• REQUIRED: Repo integration (PRs, diff visibility, review workflows)
• BEST: Diagrams (UML/sequence), glossary support, and terminology enforcement
• BEST: Safe handling of secrets/PII (redaction, allowlists, access controls)

---

Best Practices

Do

• Use AI for first drafts, humans for final review
• Integrate AI tools into existing CI/CD pipelines
• Maintain human oversight for accuracy and compliance
• Train AI tools on your style guide and terminology
• Version control all documentation with code

Avoid

• Publishing AI-generated content without review
• Relying solely on AI for compliance-critical docs
• Ignoring AI suggestions without evaluation
• Using AI for confidential or proprietary content without safeguards

---

Getting Started

Quick Start with Mintlify

# Install Mintlify CLI
npm install -g mintlify

# Initialize docs
mintlify init

# Start local preview
mintlify dev

Quick Start with DocuWriter.ai

# Generate docs for a codebase
docuwriter generate ./src --output ./docs

# Watch mode for continuous updates
docuwriter watch ./src --output ./docs

Integrate AI with Existing Docs

1. Audit current docs: Identify gaps and outdated content 2. Choose tools: Select AI tools based on your stack 3. Set up automation: Configure CI/CD for doc generation 4. Establish review process: Define human review checkpoints 5. Monitor quality: Track metrics (freshness, coverage, accuracy)

---

Resources

• Mintlify: https://www.mintlify.com
• DocuWriter.ai: https://www.docuwriter.ai/
• Apidog: https://apidog.com/
• Document360 AI Trends 2026: https://document360.com/blog/ai-documentation-trends/
• MCP Documentation: https://docs.anthropic.com/claude/docs/mcp

---

Success Criteria: AI tools augment human documentation efforts, reducing time to first draft while maintaining accuracy and quality through human review.

API Documentation Standards

Comprehensive guide for documenting REST, GraphQL, and gRPC APIs with modern standards and tools.

Modern API Documentation Standards (January 2026)

Key Standards:

• OpenAPI 3.2.0 (latest, Sept 2025) - Streaming support, hierarchical tags, self-identifying documents
• OpenAPI 3.1.0 (stable) - JSON Schema compatibility, webhooks support
• AsyncAPI 3.0 - Event-driven and message-driven APIs
• GraphQL Schema - Self-documenting with introspection
• gRPC Protocol Buffers - Type-safe service definitions

Modern Tools:

• Interactive docs: Swagger UI, Redoc, Stoplight, RapiDoc
• AI-assisted: Mintlify, Readme.com (AI-powered search), Apidog (multi-protocol)
• Testing: Postman, Insomnia, Thunder Client
• Code generation: OpenAPI Generator, GraphQL Code Generator

---

OpenAPI 3.2.0 Features (September 2025)

OpenAPI 3.2.0 introduces significant improvements for streaming APIs and modern web patterns.

Streaming Support

New streaming capabilities:

• itemSchema: Define schema for individual items in streaming responses
• prefixEncoding: Specify encoding for streamed content prefixes
• Sequential media types: First-class support for SSE, JSON Lines, multipart feeds

Example - Server-Sent Events (SSE):

openapi: 3.2.0
paths:
  /events/stream:
    get:
      summary: Subscribe to real-time events
      responses:
        '200':
          description: Event stream
          content:
            text/event-stream:
              schema:
                type: array
                itemSchema:
                  $ref: '#/components/schemas/Event'
              encoding:
                prefixEncoding: "data: "

Example - JSON Lines (NDJSON):

paths:
  /logs/stream:
    get:
      summary: Stream log entries
      responses:
        '200':
          description: Log stream
          content:
            application/x-ndjson:
              schema:
                type: array
                itemSchema:
                  $ref: '#/components/schemas/LogEntry'

Tag Metadata (Replaces Vendor Extensions)

New standardized tag fields:

• summary: Brief description for navigation
• parent: Hierarchical tag organization
• kind: Tag category (resource, operation, domain)

tags:
  - name: users
    summary: User management
    kind: resource
    description: Operations for creating, reading, updating, and deleting users
  - name: users-admin
    summary: Admin user operations
    parent: users
    kind: operation

Query Operations

New query-related features:

• additionalOperations: Define custom operations beyond CRUD
• querystring parameter location: Explicit querystring handling

paths:
  /search:
    query:
      summary: Search across all resources
      parameters:
        - name: q
          in: querystring
          required: true
          schema:
            type: string
      additionalOperations:
        - facets
        - suggest

Migration Notes

Upgrading from 3.1.x:

• Old vendor extensions (x-summary, x-parent) still work but are deprecated
• Check linters and gateways for 3.2.0 compatibility
• Streaming payloads may require schema updates
• Test with Swagger UI 5.x+ or Redoc 2.x+ for full 3.2.0 support

Essential API Documentation Elements

Every API documentation should include:

1. Base URL - API endpoint base 2. Authentication - How to authenticate (Bearer, API key, OAuth) 3. Endpoints - All available endpoints with:

• HTTP method and path
• Request parameters
• Request body schema
• Response format with examples
• Status codes
• cURL/code examples

4. Error Responses - Standard error format 5. Rate Limiting - Limits and rate limit headers 6. Pagination - Cursor-based or offset-based 7. Webhooks (if applicable) - Event types and payloads 8. SDKs/Libraries - Client libraries for different languages 9. Changelog - API version history

REST API Documentation

Authentication Section

Purpose: Explain how to authenticate API requests.

Common methods:

• Bearer tokens (JWT)
• API keys
• OAuth 2.0
• Basic authentication (not recommended for production)

Example:

## Authentication

All API requests require authentication using a Bearer token.

### Getting a Token

**Request**:

POST /api/v1/auth/login Content-Type: application/json

{ "email": "user@example.com", "password": "your-password" }

**Response**:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 3600 }

### Using the Token

Include the token in the `Authorization` header:

GET /api/v1/users Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

### Token Expiration

- Tokens expire after 1 hour (3600 seconds)
- Refresh tokens valid for 7 days
- Use `/auth/refresh` endpoint to renew tokens

Endpoint Documentation Template

For each endpoint, document:

### GET /api/v1/users/:id

Get a user by ID.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string (UUID) | Yes | User unique identifier |

**Query Parameters**:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `include` | string | No | - | Comma-separated related resources (e.g., `orders,payments`) |
| `fields` | string | No | All fields | Comma-separated fields to return (e.g., `email,name`) |

**Request Headers**:

GET /api/v1/users/123e4567-e89b-12d3-a456-426614174000?include=orders Authorization: Bearer YOUR_ACCESS_TOKEN Accept: application/json

**Response (200 OK)**:

{ "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "user@example.com", "name": "John Doe", "createdAt": "2025-11-22T10:30:00Z", "orders": [ { "id": "order-001", "total": 99.99, "status": "completed" } ] } }

**Error Responses**:

| Status Code | Description | Response |
|-------------|-------------|----------|
| 400 Bad Request | Invalid UUID format | `{"error": {"code": "INVALID_ID", "message": "Invalid user ID format"}}` |
| 401 Unauthorized | Missing or invalid token | `{"error": {"code": "UNAUTHORIZED", "message": "Invalid authentication token"}}` |
| 404 Not Found | User not found | `{"error": {"code": "NOT_FOUND", "message": "User not found"}}` |
| 429 Too Many Requests | Rate limit exceeded | `{"error": {"code": "RATE_LIMIT", "message": "Too many requests"}}` |

**Rate Limit**: 1000 requests per hour per user

**Example cURL**:

curl -X GET \ https://api.example.com/v1/users/123e4567-e89b-12d3-a456-426614174000 \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Accept: application/json'

**Example JavaScript**:

const response = await fetch('https://api.example.com/v1/users/123e4567-e89b-12d3-a456-426614174000', { headers: { 'Authorization': Bearer ${token}, 'Accept': 'application/json' } });

const user = await response.json(); console.log(user.data);

**Example Python**:

import requests

headers = { 'Authorization': f'Bearer {token}', 'Accept': 'application/json' }

response = requests.get( 'https://api.example.com/v1/users/123e4567-e89b-12d3-a456-426614174000', headers=headers )

user = response.json() print(user['data'])

Error Response Format (RFC 7807)

Standard error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "not-an-email"
      }
    ],
    "requestId": "req_abc123xyz",
    "timestamp": "2025-11-22T10:30:00Z"
  }
}

Error code standards:

• VALIDATION_ERROR - Request validation failed
• AUTHENTICATION_ERROR - Authentication failed
• AUTHORIZATION_ERROR - Insufficient permissions
• NOT_FOUND - Resource not found
• CONFLICT - Resource conflict (duplicate)
• RATE_LIMIT_EXCEEDED - Too many requests
• INTERNAL_ERROR - Server error

Rate Limiting

Document:

• Limit (requests per time period)
• Time window
• Rate limit headers
• Behavior when limit exceeded

Example:

## Rate Limiting

All endpoints are rate-limited to prevent abuse.

**Limits**:
- **Authenticated users**: 1000 requests per hour
- **Unauthenticated users**: 100 requests per hour

**Rate Limit Headers**:

Every response includes rate limit information:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1700654400

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Total requests allowed per hour |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when limit resets |

**Rate Limit Exceeded (429)**:

{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Try again in 300 seconds.", "retryAfter": 300 } }

**Best Practices**:
- Monitor `X-RateLimit-Remaining` header
- Implement exponential backoff when rate limited
- Cache responses when possible to reduce API calls

Pagination

Cursor-based pagination (recommended):

## Pagination

All list endpoints support cursor-based pagination for consistent results.

**Query Parameters**:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `cursor` | string | - | Pagination cursor from previous response |
| `limit` | integer | 20 | Items per page (max: 100) |

**Request**:

GET /api/v1/users?limit=20

**Response**:

{ "data": [ { "id": "user-1", "name": "John" }, { "id": "user-2", "name": "Jane" } ], "pagination": { "cursor": "eyJpZCI6InVzZXItMjAifQ==", "hasMore": true, "total": 150 } }

**Next Page**:

GET /api/v1/users?cursor=eyJpZCI6InVzZXItMjAifQ==&limit=20

**Benefits**:
- Consistent results (no missing/duplicate items)
- Works with real-time data
- Better performance than offset pagination

Offset-based pagination (simpler but less reliable):

## Pagination

**Query Parameters**:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-indexed) |
| `perPage` | integer | 20 | Items per page (max: 100) |

**Response**:

{ "data": [...], "meta": { "page": 1, "perPage": 20, "total": 150, "totalPages": 8 } }

Webhooks

Document webhook events and payloads:

## Webhooks

Subscribe to events by configuring webhook endpoints in your account settings.

**Supported Events**:

| Event | Description | Payload |
|-------|-------------|---------|
| `user.created` | New user registered | `User` object |
| `order.completed` | Order completed | `Order` object |
| `payment.succeeded` | Payment successful | `Payment` object |
| `payment.failed` | Payment failed | `Payment` object with error |

**Webhook Payload Format**:

{ "event": "order.completed", "timestamp": "2025-11-22T10:30:00Z", "data": { "id": "order-123", "userId": "user-456", "total": 99.99, "status": "completed" }, "webhookId": "wh_abc123" }

**Webhook Signature Verification**:

All webhooks include an `X-Webhook-Signature` header for verification:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex');

return signature === expectedSignature; }

**Retry Policy**:
- Failed webhooks retry with exponential backoff
- Retries: immediately, 5 min, 1 hour, 6 hours, 24 hours
- After 5 failures, webhook is disabled

GraphQL API Documentation

GraphQL benefits: Self-documenting through introspection.

Example documentation:

# GraphQL API

**Endpoint**: `https://api.example.com/graphql`

## Authentication

Include Bearer token in Authorization header:

POST /graphql Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json

## Schema Introspection

Explore the full schema using GraphQL Playground or GraphiQL:

- **GraphQL Playground**: https://api.example.com/graphql
- **Schema docs**: Auto-generated from schema

## Example Queries

### Get User

query GetUser($id: ID!) { user(id: $id) { id email name orders { id total status } } }

**Variables**:

{ "id": "user-123" }

**Response**:

{ "data": { "user": { "id": "user-123", "email": "user@example.com", "name": "John Doe", "orders": [...] } } }

### Create Order (Mutation)

mutation CreateOrder($input: CreateOrderInput!) { createOrder(input: $input) { id total status } }

**Variables**:

{ "input": { "userId": "user-123", "items": [ { "productId": "prod-456", "quantity": 2 } ] } }

## Error Handling

GraphQL returns errors in `errors` array:

{ "errors": [ { "message": "User not found", "extensions": { "code": "NOT_FOUND", "userId": "user-999" } } ], "data": null }

gRPC API Documentation

gRPC: Define services in Protocol Buffers (.proto files).

Example documentation:

# gRPC API

**Server**: `api.example.com:50051`

## Protocol Buffers Definition

syntax = "proto3";

package user.v1;

service UserService { rpc GetUser (GetUserRequest) returns (User) {} rpc ListUsers (ListUsersRequest) returns (ListUsersResponse) {} rpc CreateUser (CreateUserRequest) returns (User) {} }

message User { string id = 1; string email = 2; string name = 3; int64 created_at = 4; }

message GetUserRequest { string id = 1; }

message ListUsersRequest { int32 page_size = 1; string page_token = 2; }

message ListUsersResponse { repeated User users = 1; string next_page_token = 2; }

## Authentication

Use gRPC metadata to pass authentication:

const metadata = new grpc.Metadata(); metadata.add('authorization', Bearer ${token});

client.getUser({ id: 'user-123' }, metadata, callback);

## Example Calls

### Get User (Go)

import ( pb "path/to/proto/user/v1" "google.golang.org/grpc" )

conn, _ := grpc.Dial("api.example.com:50051", grpc.WithInsecure()) client := pb.NewUserServiceClient(conn)

user, err := client.GetUser(ctx, &pb.GetUserRequest{ Id: "user-123", })

OpenAPI 3.1 Specification

Use OpenAPI for REST APIs:

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: API for managing users and orders

servers:
  - url: https://api.example.com/v1
    description: Production server

security:
  - bearerAuth: []

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string

Generate interactive docs:

# Swagger UI
npx @redocly/cli preview-docs openapi.yaml

# Redoc
npx @redocly/cli build-docs openapi.yaml

API Documentation Checklist

Before publishing API docs:

• [ ] All endpoints documented
• [ ] Authentication explained with examples
• [ ] Request/response schemas complete
• [ ] Error responses documented
• [ ] Rate limiting explained
• [ ] Pagination documented
• [ ] Code examples in 2-3 languages
• [ ] cURL examples for all endpoints
• [ ] Webhooks documented (if applicable)
• [ ] Changelog included
• [ ] Interactive docs available (Swagger/Redoc)
• [ ] SDKs listed with links
• [ ] Versioning strategy explained
• [ ] Deprecation notices added
• [ ] Contact/support information included

API Documentation Success Criteria

Great API documentation enables developers to:

1. [OK] Authenticate successfully in < 5 minutes 2. [OK] Make first API call in < 10 minutes 3. [OK] Find all endpoints and parameters 4. [OK] Understand error responses 5. [OK] Copy-paste working code examples 6. [OK] Handle rate limits appropriately 7. [OK] Implement webhooks correctly

Quality metrics:

• Time to first successful API call: < 10 minutes
• Support questions about authentication: < 5%
• Completeness: All endpoints documented
• Code examples: 3+ languages
• Error clarity: All status codes explained

Backlog Status Sync Pattern

Use this pattern to keep implementation status accurate across canonical documentation after feature delivery waves.

Canonical-First Model

1. Choose one canonical status source (for example feature matrix or roadmap doc). 2. Apply status update there first with date + owner. 3. Update dependent docs by linking to canonical source instead of duplicating status text.

Required Metadata for Temporary Reports

Include in dated report files:

• Status: pending-integration | integrated | superseded
• Integrates-into: canonical path
• Owner
• Delete-by

Sync Audit Steps

• grep for stale status phrases in docs
• reconcile conflicts against canonical source
• mark integrated reports and schedule deletion

Failure Modes Prevented

• docs claiming old backlog state after implementation
• duplicate contradictory status statements in multiple files
• LLM agents consuming stale report snapshots as truth

Changelog Best Practices

Comprehensive guide for maintaining changelogs using the "Keep a Changelog" format and semantic versioning.

What Is a Changelog?

A changelog is a file documenting all notable changes made to a project in chronological order.

Purpose:

• Help users understand what changed between versions
• Communicate breaking changes clearly
• Show project activity and maintenance status
• Enable informed upgrade decisions

Standard: Keep a Changelog v1.1.0

Keep a Changelog Format

Basic Structure

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features that are not yet released

## [1.2.0] - 2025-11-22

### Added
- Feature descriptions

### Changed
- Changes to existing functionality

### Deprecated
- Features marked for removal in future versions

### Removed
- Features removed in this version

### Fixed
- Bug fixes

### Security
- Security vulnerability patches

## [1.1.0] - 2025-10-15
...

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/repo/compare/v1.0.0...v1.1.0

Change Categories

Added

Purpose: New features or capabilities.

Examples:

### Added
- OAuth2 authentication with Google and GitHub providers
- Rate limiting with Redis (100 requests per minute per user)
- Webhook support for order completion events
- Export functionality for user reports (CSV and JSON formats)
- Dark mode toggle in user settings

Best practices:

• Start with verb (passive voice acceptable)
• Be specific about what was added
• Include relevant details (providers, formats, limits)

Changed

Purpose: Changes to existing functionality.

Examples:

### Changed
- Improved search performance by 60% using Elasticsearch
- Updated Node.js requirement from 16+ to 18+
- Changed default pagination limit from 10 to 20 items
- Refactored authentication flow for better security
- Updated UI design to match new brand guidelines

Best practices:

• Explain the change clearly
• Include performance improvements with metrics
• Mention requirement changes
• Note visual/UX changes

Deprecated

Purpose: Features that will be removed in future versions.

Examples:

### Deprecated
- Legacy API v1 endpoints (will be removed in v2.0.0)
  - Use API v2 endpoints instead: `/api/v2/users`
- `getUserData()` function (use `fetchUserProfile()` instead)
- XML response format (JSON is now the standard)
- Support for Node.js 14 (end-of-life 2023-04-30)

Best practices:

• State removal timeline
• Provide migration path/alternative
• Explain reason for deprecation

Removed

Purpose: Features removed in this version.

Examples:

### Removed
- API v1 endpoints (deprecated in v1.5.0)
- Internet Explorer 11 support
- Legacy authentication using session cookies
- `/legacy-api/*` routes
- Deprecated `config.old.json` format

Best practices:

• Reference when it was deprecated
• Keep brief (removal was communicated in deprecation)
• List breaking changes prominently

Fixed

Purpose: Bug fixes.

Examples:

### Fixed
- Memory leak in WebSocket connections (#456)
- Race condition in order processing queue (#789)
- Incorrect timezone handling in date picker (#321)
- XSS vulnerability in comment rendering (CVE-2025-12345)
- 404 error when navigating to user profiles with special characters

Best practices:

• Link to issue numbers
• Describe the bug clearly
• Include CVE numbers for security fixes
• Mention user-facing impact

Security

Purpose: Security vulnerability patches.

Examples:

### Security
- Updated jsonwebtoken to 9.0.0 (CVE-2022-23529)
- Fixed SQL injection vulnerability in search endpoint (CVSS 8.1)
- Patched XSS vulnerability in markdown renderer (CVE-2025-1234)
- Upgraded axios to 1.6.0 to fix SSRF vulnerability
- Added rate limiting to prevent brute-force attacks on login

Best practices:

• Always list security fixes in a dedicated section
• Include CVE numbers if assigned
• Include CVSS scores for severity
• Link to security advisories
• Don't expose exploit details

Version Numbering (Semantic Versioning)

Format: MAJOR.MINOR.PATCH

MAJOR (Breaking Changes)

Increment when making incompatible API changes.

Examples:

• Removing deprecated endpoints
• Changing function signatures
• Changing response formats
• Removing configuration options
• Requiring new dependencies

Changelog entry:

## [2.0.0] - 2025-11-22

### Removed
- API v1 endpoints (use v2 instead)

### Changed
- `createUser()` now returns Promise instead of callback
- Changed response format from XML to JSON

MINOR (New Features)

Increment when adding functionality in a backward-compatible manner.

Examples:

• Adding new endpoints
• Adding optional parameters
• Adding new features
• Extending functionality

Changelog entry:

## [1.3.0] - 2025-11-22

### Added
- OAuth2 authentication support
- Export to PDF functionality
- GraphQL API endpoint

PATCH (Bug Fixes)

Increment when making backward-compatible bug fixes.

Examples:

• Fixing bugs
• Security patches
• Performance improvements
• Documentation updates

Changelog entry:

## [1.2.1] - 2025-11-22

### Fixed
- Memory leak in connection pooling (#234)
- Incorrect date formatting in exports

### Security
- Updated dependencies to patch vulnerabilities

Complete Changelog Example

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Bulk user import from CSV files
- Email notifications for order status changes

### Changed
- Improved dashboard loading time by 40%

## [1.2.0] - 2025-11-22

### Added
- OAuth2 authentication with Google and GitHub (#123)
- Rate limiting with Redis: 100 requests per minute per user (#145)
- Webhook support for `order.completed` and `user.created` events (#167)
- Export user reports in CSV and JSON formats (#189)
- Dark mode toggle in user settings (#201)

### Changed
- Improved search performance by 60% using Elasticsearch instead of PostgreSQL full-text search (#134)
- Updated minimum Node.js version from 16.x to 18.x (#156)
- Changed default pagination limit from 10 to 20 items per page (#178)
- Refactored authentication flow to use JWT instead of sessions (#192)

### Deprecated
- Legacy API v1 endpoints under `/api/v1/*` (will be removed in v2.0.0)
  - Migrate to `/api/v2/*` endpoints
  - See migration guide: [MIGRATION.md](MIGRATION.md)

### Fixed
- Memory leak in WebSocket connections after 24 hours of runtime (#456)
- Race condition in order processing queue causing duplicate charges (#489)
- Incorrect timezone handling in date picker component (#321)
- 404 error when navigating to user profiles with special characters (#367)

### Security
- Updated jsonwebtoken from 8.5.1 to 9.0.0 (CVE-2022-23529, CVSS 7.5)
- Fixed SQL injection vulnerability in search endpoint (CVE-2025-1234, CVSS 8.1)
- Patched XSS vulnerability in markdown renderer (CVE-2025-5678)
- Upgraded axios to 1.6.0 to fix SSRF vulnerability

## [1.1.0] - 2025-10-15

### Added
- Two-factor authentication (2FA) with TOTP (#98)
- User profile customization options (#112)
- Admin dashboard for user management (#134)

### Changed
- Migrated from JavaScript to TypeScript (#87)
- Updated UI design to match new brand guidelines (#101)

### Fixed
- Email verification links expiring too quickly (#76)
- Pagination breaking on last page (#89)

## [1.0.0] - 2025-09-01

### Added
- Initial release
- User authentication and registration
- Product catalog with search
- Shopping cart functionality
- Stripe payment integration
- Order management system
- Admin panel
- Email notifications

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Unreleased Section

Purpose: Track upcoming changes before release.

Usage:

## [Unreleased]

### Added
- Feature X that will be in next release

### Fixed
- Bug Y that will be in next release

When releasing: 1. Create new version section 2. Move Unreleased items to version section 3. Add release date 4. Clear Unreleased section

Example transformation:

Before release:

## [Unreleased]

### Added
- Dark mode support

After 1.3.0 release:

## [Unreleased]

## [1.3.0] - 2025-11-22

### Added
- Dark mode support

Linking to Commits

At the bottom of CHANGELOG.md:

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Benefits:

• Click version to see all changes on GitHub
• Visual diff between versions
• Traceability to commits

Changelog Anti-Patterns

BAD: Avoid:

Commit dumps:

### Changed
- Fixed typo
- Updated package.json
- Refactored code
- Fixed bug
- Updated README

Instead, group related changes:

### Changed
- Improved user authentication security
  - Implemented rate limiting
  - Added 2FA support
  - Fixed session timeout bug

Vague entries:

### Fixed
- Fixed bugs
- Performance improvements
- Various updates

Instead, be specific:

### Fixed
- Memory leak in WebSocket connections (#456)
- Search performance improved by 60%

No dates:

## [1.2.0]  ← Missing date

Instead:

## [1.2.0] - 2025-11-22

Missing links:

[1.2.0]: Missing

Instead:

[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0

Automated Changelog Generation

semantic-release

Installation:

npm install --save-dev semantic-release

Configuration (.releaserc.json):

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git"
  ]
}

Commit format (Conventional Commits):

feat: add OAuth2 authentication
fix: resolve memory leak in WebSocket
docs: update API documentation
chore: upgrade dependencies

standard-version

Installation:

npm install --save-dev standard-version

Usage:

npm run release

What it does: 1. Bumps version in package.json 2. Generates/updates CHANGELOG.md 3. Creates git tag 4. Commits changes

Writing Style Guidelines

Audience

Write for:

• Users upgrading to new version
• Developers integrating your library
• Product managers tracking features

Tone

• Clear and concise - No marketing fluff
• Technical but accessible - Avoid jargon when possible
• Action-oriented - Start with verbs
• User-focused - Explain impact on users

Format

Good:

### Added
- OAuth2 authentication with Google and GitHub providers
- Rate limiting: 100 requests per minute per user (configurable)

Bad:

### Added
- We've added the amazing new feature of OAuth2! Now you can log in with Google or GitHub!

Breaking Changes

Always highlight breaking changes prominently:

## [2.0.0] - 2025-11-22 - BREAKING CHANGES

### Removed
- [WARNING] **BREAKING**: API v1 endpoints removed (use v2 instead)
- [WARNING] **BREAKING**: Node.js 14 support dropped (requires 18+)

### Changed
- [WARNING] **BREAKING**: `createUser()` signature changed
  - **Old**: `createUser(name, email, callback)`
  - **New**: `createUser({ name, email }): Promise<User>`

Changelog Maintenance Checklist

When releasing:

• [ ] Move Unreleased items to new version section
• [ ] Add release date in YYYY-MM-DD format
• [ ] Update version number (semantic versioning)
• [ ] Add comparison link at bottom
• [ ] Update Unreleased link
• [ ] Verify all issue/PR links work
• [ ] Check for typos and formatting
• [ ] Highlight breaking changes
• [ ] Include migration guide link if needed
• [ ] Tag release in Git

Tools for Changelog Management

Generators:

• semantic-release - Automated versioning and changelog
• standard-version - Conventional Commits to changelog
• auto-changelog - Generate from Git history
• conventional-changelog - Changelog from commits

Validators:

• changelogithub - Validate changelog format
• Custom CI scripts to enforce format

Example CI check:

# Verify CHANGELOG.md was updated
git diff --name-only HEAD~1 | grep CHANGELOG.md || {
  echo "Error: CHANGELOG.md not updated"
  exit 1
}

Examples of Great Changelogs

Open Source Projects:

• Rust: https://github.com/rust-lang/rust/blob/master/RELEASES.md
• React: https://github.com/facebook/react/blob/main/CHANGELOG.md
• Next.js: https://github.com/vercel/next.js/releases
• fastify: https://github.com/fastify/fastify/blob/main/CHANGELOG.md

Changelog Success Criteria

A great changelog enables readers to:

1. [OK] Understand what changed in 30 seconds 2. [OK] Identify breaking changes immediately 3. [OK] Find relevant issues/PRs for more context 4. [OK] Decide whether to upgrade 5. [OK] Plan migration for breaking changes 6. [OK] Trust the project is actively maintained

Quality metrics:

• Completeness: All notable changes documented
• Clarity: Changes easy to understand
• Consistency: Follows Keep a Changelog format
• Traceability: Links to issues/commits
• Timeliness: Updated with every release