​

COOKBOOK & REACTOR

​

Universal Multi-Language Infrastructure Ecosystem

​

Systems Requirements Specification (SRS)

​

📋 TABLE OF CONTENTS

1. Executive Summary
2. Document Overview
3. System Architecture
4. Functional Requirements
5. Non-Functional Requirements
6. Requirements Traceability Matrix
7. Verification & Validation Plan
8. MCP & Agent Specifications
9. Acceptance Criteria
10. Glossary & Definitions

​

EXECUTIVE SUMMARY

​

Vision

​

Scope

​

Key Objectives

1. ✅ Establish COOKBOOK.DEV as universal pattern library (5 languages, N concepts)
2. ✅ Establish REACTOR.DEV as polyglot tool ecosystem (production distribution)
3. ✅ Enable seamless cross-language pattern discovery (content addressable)
4. ✅ Support agent/LLM automation (MCP + XML schemas)
5. ✅ Maintain 100% code coverage for all recipes (working examples required)

​

DOCUMENT OVERVIEW

​

Document Type

​

Classification

​

Standards Compliance

• IEEE 830-1998: Software Requirements Specifications
• NIST SP 800-53: Control Objectives for Security
• ISO/IEC 25010: Software Quality Model
• NASA NPR 2220.1: Software Engineering Standards
• GCHQ: Secure Development Principles

​

Audience

• Implementers: Engineers building the system
• Validators: QA teams verifying requirements
• Agents: LLM/Claude querying via MCP
• Community: Open-source contributors

​

SYSTEM ARCHITECTURE

​

High-Level System Diagram

┌──────────────────────────────────────────────────────────────┐
│              COOKBOOK & REACTOR ECOSYSTEM                    │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │     CENTRAL DISCOVERY & INDEX LAYER                   │ │
│  │  (Airtable: Unified metadata, cross-language tagging) │ │
│  └─────────────────┬──────────────────────────────────────┘ │
│                    │                                         │
│      ┌─────────────┼──────────┬─────────────┐               │
│      │             │          │             │               │
│  ┌───▼────┐  ┌────▼─────┐ ┌─▼──────┐ ┌───▼────────┐      │
│  │COOKBOOK │  │ REACTOR  │ │  n8n   │ │ Mintlify   │      │
│  │  .dev   │  │  .dev    │ │WORKFLOW│ │    DOCS    │      │
│  │         │  │          │ │        │ │            │      │
│  │ Recipes │  │ PyPI     │ │Sync &  │ │  Auto-gen  │      │
│  │Patterns │  │ npm      │ │Publish │ │     API    │      │
│  │Blueprint│  │ crates   │ │ Notify │ │   Refs     │      │
│  └────┬────┘  │ GitHub   │ └────────┘ └────────────┘      │
│       │       │ Releases │                                   │
│       │       └──────┬───┘                                   │
│       │              │                                       │
│  ┌────┼──────────────┴──────────┬──────────────┐            │
│  │    │                         │              │            │
│ ┌▼────▼────┐      ┌────────────▼──┐    ┌──────▼─────┐    │
│ │ GitHub   │      │ Blog/Content   │    │ Obsidian   │    │
│ │Org(Multi)│      │ (Reactor brand)│    │ Knowledge  │    │
│ │          │      │                │    │ Vault      │    │
│ └──────────┘      └────────────────┘    └────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │      AGENT/LLM INTERFACE LAYER                      │   │
│  │                                                     │   │
│  │  • MCP Server (mcp.reactor.dev)                    │   │
│  │  • REST API (api.reactor.dev)                      │   │
│  │  • XML Schemas (api.reactor.dev/schemas/)          │   │
│  │  • Tool Specifications (OpenAPI 3.1.0)             │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

​

COOKBOOK vs REACTOR

​

Component Relationships

COOKBOOK RECIPE (Week 1-2)
  └─ Experimental code, rough docs
  └─ "Does this idea work?"
       ↓
COOKBOOK PATTERN (Week 3-4)
  └─ Cleaned code, comprehensive docs
  └─ "This pattern is solid"
       ↓
REACTOR TOOL (Month 2+)
  └─ Production package, published
  └─ "This solves a real problem"
       ↓
REACTOR ENTERPRISE (Month 6+)
  └─ Commercial licensing, consulting
  └─ "Companies pay for this"

​

FUNCTIONAL REQUIREMENTS

​

FR-1: Multi-Language Repository Organization

​

FR-1.1: Language-Segregated Directory Structure

• github.com/your-name/cookbook/ exists with /python, /go, /rust, /typescript, /shell directories
• github.com/reactor-python/ (or -polyglot) exists with tool repos organized by language
• Each recipe/tool has standard file structure: README.md, src/, tests/, examples/, language-specific manifest (pyproject.toml/Cargo.toml/package.json)
• Language-specific metadata declares runtime requirements (Python version, Go version, etc.)
• Directory structure validates against schema in CI/CD

• FR-2.1 (Unified metadata catalog)
• NFR-3 (Scalability)

​

FR-1.2: Cross-Language Linking & Discovery

• Each recipe/pattern metadata includes list of all language implementations
• Documentation site (cookbook.dev) provides language selector for each recipe
• Search results include language filter and language indicators
• Recipe detail pages show parallel code examples (Python | Go | Rust | TypeScript | Shell)
• Navigation enables browsing recipes by concept across all languages
• Backlinks from each implementation point to other language variants

• Links to: User story “As an engineer, I want to see how a pattern looks in all 5 languages”

​

FR-2: Knowledge Management & Cataloging

​

FR-2.1: Unified Metadata Catalog (Airtable)

• Automated syncing of GitHub metrics (stars, forks, last commit)
• Unified search across all content
• Agentic querying (MCP server reads from Airtable)
• Content discoverability

• Airtable base “Reactor Portfolio” exists with table “Knowledge Index”
• Schema includes all required fields (see Section C.1 of Technical Specifications)
• All 50+ Python tools + new recipes indexed with cross-language references
• n8n syncs GitHub metrics hourly (stars, forks, last commit, issues)
• Airtable views enable filtering by Status, Language, Concept, Difficulty, Monetization
• Airtable API accessible to MCP server (read-only for agents)

• n8n instance configured
• GitHub API access
• Airtable API key secured

​

FR-2.2: Content Addressability & Versioning

• Persistent URLs for bookmarking/sharing
• Agent discovery (“Get recipe-async-retry-001 in Python”)
• Semantic versioning for recipe evolution
• API-first access

• HTTP endpoints follow pattern: /cookbook/{language}/recipes/{recipe-name}/
  • Example: /cookbook/python/recipes/async-retry/, /cookbook/go/patterns/circuit-breaker/
• Each recipe has persistent semantic ID and version (recipe-async-retry-001 v1.2.3)
• JSON API endpoint: /api/v1/recipes?language=python&concept=concurrency&difficulty=intermediate
• URL routing enables both concept-based and language-based navigation
• Redirect handling for moved/renamed recipes (301 redirect with deprecation notice)

• cookbook.dev/python/recipes/async-retry/
• cookbook.dev/go/patterns/circuit-breaker/
• cookbook.dev/concepts/concurrency/ (shows all implementations)
• api.reactor.dev/v1/recipes/recipe-async-retry-001?language=python

​

FR-3: Documentation Generation & Architecture Diagrams

​

FR-3.1: Auto-Generated API Documentation

• Mintlify integration reads from GitHub repos and auto-generates docs
• Generated docs include: function signatures, parameter descriptions, return types, exceptions, examples
• Language-specific formatters: Python (pydoc), Go (GoDoc), Rust (rustdoc), TypeScript (TSDoc), Shell (ShellDoc)
• Docstring style validation in CI (all functions/methods must have docs)
• docs.reactor.dev and cookbook.reactor.dev render correctly on desktop/tablet/mobile
• Search indexes generated docs for full-text search

• NFR-6 (Discoverability)

​

FR-3.2: Architecture Diagrams & System Context

• Each recipe includes architecture-diagram.md or architecture-diagram.mmd (Mermaid format)
• Diagrams render in documentation site via Mermaid interpreter
• Mermaid/PlantUML source included (not just images) for version control
• Diagram shows: major components, data flows, interaction patterns, state machines
• Style guide defines standard shapes/colors for boxes & arrows (consistency)
• Diagram validation in CI (valid Mermaid syntax)

​

FR-4: Distribution & Package Management

​

FR-4.1: Multi-Registry Publishing

• Python tools: GitHub Actions publishes to PyPI on git tag (workflow: publish-pypi.yml)
• Go tools: Published to GitHub releases with go-gettable import paths (e.g., github.com/reactor-python/tool/v1.0.0)
• Rust tools: Published to crates.io on cargo release via GitHub Actions
• TypeScript tools: Published to npm on version bump with GitHub Actions
• Shell tools: Distributed as scripts via GitHub releases + Homebrew formula
• All tools include checksum verification (SHA-256)
• Publish workflow includes smoke tests (verify tool can be installed + runs)

git tag v1.2.3
git push origin v1.2.3
# → GitHub Actions triggered
# → Publishes to PyPI, npm, crates.io simultaneously

​

FR-5: Search & Discovery

​

FR-5.1: Full-Text Search with Language & Concept Filtering

• Search page at cookbook.dev/search with filter UI
• Filters: language (dropdown), concept (multi-select), difficulty (slider), status (checkbox)
• Results return recipes in all matching languages with language badges
• Response time < 100ms p95 (measured with load testing)
• Search index updated within 5 minutes of new recipe push
• Typo tolerance enabled (fuzzy matching for common misspellings)
• Relevance ranking considers match position, recency, popularity (stars)

• NFR-1 (Performance: < 100ms)

​

FR-5.2: Concept-Based Navigation

• cookbook.dev/concepts/ lists all concepts with recipe counts
• cookbook.dev/concepts/concurrency/ shows all concurrency recipes/patterns across languages
• Each concept page groups implementations by language
• Concept pages linked from recipe detail pages (reciprocal linking)
• Concepts themselves versioned/updated (add new concepts as recipes added)

​

FR-6: Automation & Workflow Integration

​

FR-6.1: n8n Workflow Automation

• Workflow 1: GitHub → Airtable (hourly metadata sync)
  • Queries all tool repos, extracts stars/forks/last-commit
  • Updates Airtable records (Last Updated, GitHub Stars fields)
  • Posts summary to Slack
• Workflow 2: Release tag → PyPI/npm/crates (automated publishing)
  • Triggered by GitHub webhook (release created)
  • Extracts version, calls package registry APIs
  • Verifies install succeeds
  • Posts announcement to Slack/Twitter
• Workflow 3: New recipe added → Documentation updated
  • Triggered by Airtable webhook (record created)
  • Generates doc template in Mintlify
  • Creates GitHub issue if docs incomplete
• Workflow 4: Weekly summary → Email + Slack
  • Aggregates metrics (production tools, avg stars, docs coverage)
  • Calculates week-over-week growth
  • Sends formatted report

• n8n instance (cloud or self-hosted)
• GitHub API tokens
• Airtable API key
• Slack webhook

​

FR-7: Agent & LLM Support

​

FR-7.1: MCP Server Interface

• MCP server deployed at mcp.reactor.dev:8080 (HTTP SSE transport)
• Resources exposed: /recipes, /patterns, /blueprints, /tools, /concepts
• Tools exposed:
  • search_recipe(query: str, language?: str) → Recipe[]
  • get_recipe(recipe_id: str, language?: str) → Recipe
  • get_implementations(pattern: str) → ImplementationMatrix
  • recommend_recipe(problem: str, language: str) → Recipe[]
  • validate_recipe(recipe: Recipe) → ValidationResult
• Authentication via Bearer token (API key)
• Rate limiting: 10 req/sec per token
• Agents can execute recipes by parsing JSON response

​

FR-7.2: Structured XML Schemas

• XSD schema file at api.reactor.dev/schemas/recipe.xsd
• API endpoints return JSON + XML formats (?format=json|xml)
• Recipes serialized to XML must validate against XSD (automated in CI)
• Schema enforces: required fields, enumerated types, data types, cardinality
• Schema versioning: /schemas/recipe.xsd (v1) allows future /schemas/recipe-v2.xsd

• FR-7.1 (MCP Server)

​

FR-7.3: Agentic Tool Specifications (OpenAPI)

• Understand what tools exist and what they do
• Call tools with correct parameters
• Parse responses reliably
• Generate code that uses tools

• OpenAPI spec at api.reactor.dev/openapi/reactor-tools.yaml (v3.1.0)
• Each tool defined with operationId, parameters, response schema, errors
• Parameter validation (required, types, constraints)
• Error responses documented (400, 404, 422, 429)
• Security scheme defined (Bearer token)
• Rate limit headers documented
• Spec validates against OpenAPI 3.1.0 schema (in CI)

​

NON-FUNCTIONAL REQUIREMENTS

​

NFR-1: Performance Requirements

​

NFR-1.1: Search Response Time

​

NFR-1.2: Documentation Site Load Time

​

NFR-1.3: Package Publishing Latency

​

NFR-1.4: Metadata Synchronization

​

NFR-2: Availability Requirements

​

NFR-2.1: Documentation Site Uptime

​

NFR-2.2: Source of Truth

​

NFR-2.3: Graceful Degradation

• MCP server has local cache of recipes (updated daily)
• If Airtable API fails, cached data served with staleness warning
• If GitHub API fails, use previously cached metrics
• Degraded mode logged and alerted

​

NFR-3: Scalability Requirements

​

NFR-3.1: Recipe Scaling

• Search < 100ms (still holds at 500 recipes)
• Page load < 2s (still holds)
• Airtable sync < 30 minutes

​

NFR-3.2: Concurrent User Load

​

NFR-3.3: Repository Management

​

NFR-4: Security Requirements

​

NFR-4.1: Branch Protection

• Master/main branch requires 1 approval before merge
• Require status checks pass (CI/CD)
• Dismiss stale reviews on new commits
• Require up-to-date branches before merge

​

NFR-4.2: Package Publishing Security

• PyPI API token limited to specific package(s)
• npm token with publish permission only (no delete)
• crates.io token with publish permission only
• Tokens rotated quarterly
• Tokens stored in GitHub Secrets (encrypted)
• Tokens never logged

​

NFR-4.3: MCP Authentication & Rate Limiting

• Bearer token authentication required
• Rate limit: 10 req/sec per token
• Rate limit headers in responses: X-RateLimit-Remaining, X-RateLimit-Reset
• 429 (Too Many Requests) response on limit exceeded
• Token revocation/rotation possible

​

NFR-4.4: Principle of Least Privilege

• GitHub Actions workflows use minimal scopes (contents: read, pull-requests: read)
• n8n workflows use separate API keys per integration
• Airtable API key has read-only scope for agents
• No hardcoded secrets (use GitHub Secrets)

​

NFR-5: Maintainability Requirements

​

NFR-5.1: Test Coverage

• Python: pytest --cov
• Go: go test -cover
• Rust: cargo tarpaulin
• TypeScript: jest --coverage
• Shell: bats + statement coverage

​

NFR-5.2: Code Linting

• Python: pylint score >= 9.0
• Go: golangci-lint run passes
• Rust: cargo clippy with no warnings
• TypeScript: eslint with strict config
• Shell: shellcheck with no violations

​

NFR-5.3: Documentation Completeness

• Docstring coverage tool (pydocstyle, etc.)
• README exists and has minimum 500 characters
• At least 1 working example per recipe
• API docs auto-generated and rendering

​

NFR-5.4: Dependency Management

• Dependency versions pinned in pyproject.toml, Cargo.toml, package.json, etc.
• Automated dependency updates (Dependabot) create PRs weekly
• Security scanning enabled (Trivy, snyk)
• Outdated dependencies flagged and updated quarterly

​

NFR-6: Discoverability Requirements

​

NFR-6.1: Search Indexing

• Search endpoint: cookbook.dev/search?q={query}&language={lang}&concept={concept}&difficulty={difficulty}
• All fields indexed: name, description, code, examples, concepts, languages
• Search returns results in < 100ms

​

NFR-6.2: SEO Optimization

• Meta tags on all recipe pages (title, description, og:image)
• Target keywords in content: “circuit breaker pattern python async”, “error handling rust tokio”, etc.
• Sitemap.xml generated and submitted to Google Search Console
• Mobile-first responsive design
• Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1

​

NFR-6.3: Structured Data Markup

• JSON-LD markup for Article schema (recipe pages)
• Includes: headline, description, author, datePublished, keywords
• Validates with Google Structured Data Testing Tool

​

NFR-7: Interoperability Requirements

​

NFR-7.1: Data Export Formats

• JSON export: GET /api/v1/recipes?format=json returns JSON array
• XML export: GET /api/v1/recipes?format=xml returns XML
• CSV export: GET /api/v1/recipes?format=csv returns spreadsheet
• All formats include complete metadata (no truncation)

​

NFR-7.2: MCP Transport Flexibility

• HTTP/SSE transport (for browser clients)
• stdio transport (for subprocess integration)
• Both transports authenticated and rate-limited

​

NFR-7.3: Airtable API Access

• Airtable API key configured for MCP server
• Read-only access (no create/update/delete)
• Queries return consistent schema
• Pagination supported for large result sets

​

REQUIREMENTS TRACEABILITY MATRIX

​

Overview

​

VERIFICATION & VALIDATION PLAN

​

V&V Strategy Overview

​

Phase 1: Static Verification

​

Code Linting

• Tools: pylint, golangci-lint, clippy, eslint, shellcheck
• Criteria: No violations, pass on every commit
• Execution: CI/CD (GitHub Actions)

​

Schema Validation

• Targets: Recipe metadata, XML schemas, Airtable structure
• Tools: JSON Schema validator, XSD validator, custom validators
• Execution: CI/CD

​

Diagram Syntax

• Targets: Mermaid/PlantUML diagrams
• Tools: Mermaid validator, PlantUML compiler
• Execution: CI/CD

​

Phase 2: Unit Testing

​

Coverage Requirement

• Target: 100% code coverage per recipe
• Tools: pytest, go test, cargo tarpaulin, jest, bats
• Acceptance: All lines executed at least once

​

Test Execution Time

• Target: < 30 seconds per recipe
• Measurement: CI/CD logs
• Acceptance: p95 < 30s

​

Phase 3: Integration Testing

​

Multi-Language Composition

• Scenario: Python calls Go service via HTTP
• Verification: Service responds correctly, error handling works
• Tools: Integration test framework (pytest, go test)

​

CI/CD Pipeline

• Scenario: Push code → test → lint → publish
• Verification: Pipeline executes without manual intervention
• Tools: GitHub Actions logs

​

Package Publishing

• Scenario: Git tag v1.0.0 → appears on PyPI/npm/crates
• Verification: Smoke test (install + run tool)
• Tools: Custom verification script

​

Phase 4: API Testing

​

MCP Compliance

• Tools: Anthropic MCP test suite
• Criteria: All tools callable, responses match schema, error handling correct

​

REST API

• Tools: Postman, curl, automated testing
• Scenarios: GET recipes, search, filter, paginate

​

XML Schema Validation

• Tools: XSD validator
• Criteria: All recipe XML validates against schema

​

Phase 5: Performance Testing

​

Search Latency

• Test: 10,000 recipes indexed, 50 concurrent users, 1000 search requests
• Tool: wrk, vegeta, or similar load tester
• Success Criterion: p95 < 100ms

​

Page Load Time

• Test: WebPageTest with 4G throttle, multiple page types
• Tool: WebPageTest, Lighthouse
• Success Criterion: < 2s load time

​

Airtable Sync

• Test: Sync 100 repos hourly
• Tool: n8n execution logs
• Success Criterion: Completes within 30 minutes

​

Phase 6: User Acceptance Testing (UAT)

​

Discoverability

• Scenario: New engineer lands on cookbook.dev, finds async-retry pattern in Python
• Success: Finds recipe within 2 minutes, understands purpose/usage

​

Forking & Adaptation

• Scenario: Engineer forks recipe, modifies for their project
• Success: Recipe code runs with minimal changes, examples work

​

Cross-Language Comparison

• Scenario: Engineer views circuit-breaker in Python, Go, Rust, TypeScript
• Success: Can compare implementations and understand tradeoffs

​

Phase 7: Agent Testing (New)

​

MCP Server Connectivity

• Scenario: Claude connects to MCP server, queries recipes
• Tool: Anthropic Claude + MCP test client
• Success: Agent receives recipes, can parse and use them

​

Autonomous Recipe Finding

• Scenario: Agent asked “Show me async patterns for Python”
• Tool: Claude with MCP integration
• Success: Agent finds relevant recipes, provides code samples

​

Schema Validation

• Scenario: Agent receives XML recipe, parses into typed object
• Tool: Agent test harness
• Success: Deserialization succeeds, types correct

​

MCP & AGENT SPECIFICATIONS

​

MCP Server Definition

​

Available Resources

/recipes
  → List all recipes with filtering

/recipes/{recipe_id}
  → Get single recipe details + implementations

/search
  → Full-text search with AI ranking

/recipes/{recipe_id}/implementations
  → Get recipe across all languages

/concepts
  → Browse all concepts

/validate
  → Validate recipe against schema

​

Available Tools

search_recipe(query: str, language?: str) → Recipe[]
  Search recipes by full-text query

get_recipe(recipe_id: str, language?: str) → Recipe
  Retrieve complete recipe including code, tests, examples

get_implementations(pattern: str) → ImplementationMatrix
  Get all implementations of a pattern across languages

recommend_recipe(problem: str, language: str) → Recipe[]
  Get AI-powered recipe recommendations (Claude-powered)

validate_recipe(recipe: Recipe) → ValidationResult
  Validate recipe against schema, return warnings/errors

​

Agent Example

# Agent (Claude with MCP integration)
Agent: "Show me how to implement async retry in Python"

Claude: [calls MCP tool]
  search_recipe(
    query="async retry exponential backoff",
    language="python"
  )

MCP Response:
{
  "recipes": [
    {
      "id": "recipe-async-retry-001",
      "name": "Async Retry with Exponential Backoff",
      "language": "python",
      "code": "...",
      "examples": ["basic_usage.py", "with_timeout.py"],
      "tests": ["test_retry.py"]
    }
  ]
}

Claude: [renders response to user with code examples]

​

ACCEPTANCE CRITERIA

​

Phase 1 Acceptance (Week 1-2)

​

Foundation Criteria

• cookbook.dev and reactor.dev domains registered and resolving
• GitHub organizations created
  • github.com/your-name/cookbook
  • github.com/reactor-python (or -polyglot)
• Airtable base created with schema
• 5 initial recipes added (1 per language: Python, Go, Rust, TypeScript, Shell)
  • Each has: README.md, src/, tests/, examples/, architecture-diagram.mmd

​

Phase 2 Acceptance (Week 3-4)

​

Infrastructure Criteria

• Mintlify documentation site live and rendering recipes
• n8n workflows deployed:
  • GitHub → Airtable sync (hourly)
  • Release → publish to package registries
• GitHub Actions CI/CD pipelines green for all recipes
• Search functionality working (filter by language, concept, difficulty)

​

Phase 3 Acceptance (Week 5-6)

​

Agent & Testing Criteria

• MCP server deployed and responding to tool calls
• Claude successfully queries Cookbook recipes via MCP
• JSON API at api.reactor.dev returning data
• XML schemas at api.reactor.dev/schemas/ validating recipes
• All 40+ requirements traced in RTM
• V&V report generated (100% requirements tested)

​

Phase 4 Acceptance (Week 7-8)

​

Production Readiness Criteria

• 20+ recipes indexed in Airtable
• 5+ patterns with implementations in 3+ languages
• 100% test coverage for all recipes (CI enforced)
• 80%+ documentation completeness
• Performance benchmarks passed:
  • Search < 100ms p95
  • Page load < 2s
  • Publish < 5min latency
• Security audit completed (branch protection, secrets management)
• Dependency scan clean (Trivy)

​

GLOSSARY & DEFINITIONS

​

DOCUMENT CONTROL

​

Change Log

​

END OF DOCUMENT

​

Quick Navigation

• ↑ Back to Top
• GitHub: cookbook.dev →
• GitHub: reactor.dev →
• MCP Server →