8 Templates

System Specs

Reusable Markdown blueprints for documenting foundational architecture decisions. Schema-validated, status-tracked, and ready for your project.

How It Works

Cross-cutting documentation

Structured templates for every architectural concern

Template-Based

Copy templates from templates/specs/ to your project's specs/ directory. Each template covers a different cross-cutting concern.

Schema Validated

System specs validate against schemas/system-spec.schema.json with required fields: spec_type, title, status, last_updated.

Status Tracked

Specs carry a lifecycle: draft → approved → deprecated. Enforced by vb validate --only-specs.

Jump to spec

Tech Stack Local Dev Hosting CI/CD Database Caching Security Observability

Template Catalog

All spec templates

Click any template to see its full section structure. Copy to specs/ and fill in your project's decisions.

Tech Stack

17 sections

Languages, runtimes, frameworks, data stores, messaging, and third-party integrations

▶

Template file

templates/specs/tech-stack.md

spec_type

tech-stack

Sections

Purpose Why this stack exists and how it enables product strategy across all platforms

Scope & Assumptions Products/platforms covered, out-of-scope constraints

Delivery Context Product Surface Matrix (Web, iOS, Android, Desktop, APIs) with status

Guiding Principles High-level guardrails for technology selection

Architecture Overview Canonical diagrams and runtime topology

Languages, Frameworks & Tooling Backend, Web, Mobile, Desktop, shared libraries, build tools, testing stack

Data & Storage Technologies Relational, non-relational, caches, file/object storage

Messaging & Integrations Internal queues/streams and external partner integrations

Third-Party Services & SDKs Analytics, payments, auth, observability tools with support tiers

Security & Compliance Data classification, dependency governance, license compliance

Operational Considerations Deployment targets, orchestration, capacity planning

Extensibility & Future Options Technology bets and sunset plans

Decision Drivers & Trade-Offs Stack justification with measurable outcomes

Risks & Mitigations Skill gaps, vendor lock-in, maturity concerns

Adoption & Rollout Plan Phased adoption with milestones and success metrics

Local Development

14 sections

Developer onboarding, toolchain requirements, secrets management, and troubleshooting

▶

Template file

templates/specs/local-development.md

spec_type

local-development

Sections

Purpose DX goals, onboarding time targets, problems the environment solves

Success Criteria Target onboarding time, staging/production parity, supported OS/hardware

Environment Support Matrix macOS, Windows, Linux, Cloud DevBox support status

Prerequisites Accounts, access groups, VPN, SSO, tooling versions

Quick Start Checklist 6-step bootstrap: clone, toolchains, dependencies, secrets, services, tests

Tooling & Services Overview Commands table for Backend, Frontend, Mobile, Desktop

Configuration & Secrets Config locations, env var conventions, .env templates, secret rotation

Data & Seed Strategy Fixtures, snapshots, synthetic data tooling, reset/reseed commands

Running the Stack Boot commands, debugger hooks, hot reload, CORS, emulators, background jobs

Testing Workflows Unit/integration/e2e/perf commands, coverage, watch mode

Troubleshooting & Diagnostics Common failures, log locations, network tips, clean-room reset

Automation & Tooling Linting, formatting, DB migrations, dev containers, Nix flakes

Security & Compliance Notes PII redaction, GDPR/HIPAA/PCI requirements, machine hardening

Hosting & Infrastructure

14 sections

Cloud/on-prem topology, networking, disaster recovery, and scaling strategy

▶

Template file

templates/specs/hosting-and-infrastructure.md

spec_type

hosting-and-infrastructure

Sections

Purpose Where the app runs and how providers satisfy availability, latency, sovereignty

Environment Overview Dev, Stage, Prod, DR environments with provider, regions, purpose

Provider Selection & Rationale Evaluation criteria and alternatives considered

Reference Architecture Load balancers, gateways, compute, data layers, CDN, IaC repos

Network Topology & Security VPC layout, subnets, peering, WAF, zero-trust, certificate management

Compute & Runtime Targets Kubernetes, serverless, VM families, autoscaling, GPU use cases

Platform Services Database, Cache, Queue, CDN services with provisioning method

Data Residency & Compliance Regulatory constraints, multi-region strategy, encryption requirements

Resilience & Disaster Recovery RPO/RTO, backup cadence, failover automation, chaos testing

Cost Management Budget owners, tagging strategy, reserved capacity, visibility tools

Access & Governance IAM roles, break-glass procedures, OPA/SCP guardrails

CI/CD Pipeline

12 sections

Build/test/deploy stages, quality gates, security checks, and rollback strategy

▶

Template file

templates/specs/ci-cd-pipeline.md

spec_type

ci-cd-pipeline

Sections

Purpose Products served, release cadence goals (continuous, scheduled, nightly)

Goals & Non-Goals Release frequency, lead time, failure rate, MTTR targets

Pipeline Overview Stage table with triggers, tooling, inputs, outputs, environments

Triggers & Branching Strategy Branch naming, protection rules, required checks, release model

Build & Package Commands, caching, artifact naming, SBOM generation, signing

Test & Quality Gates Unit/integration/e2e/perf suites, coverage thresholds, flaky test handling

Security & Compliance Checks SAST, DAST, dependency scanning, container scanning, license checks

Deployment Stages Environment promotion, gating, blue/green, canary, feature flags

Secrets & Configuration Vault providers, rotation policies, parameterized configs per environment

Failure Handling & Recovery Auto-retry, rollback commands, artifact retention, incident escalation

Compliance & Auditability Logs, approvals, evidence retention, change management tickets

Database Schema

14 sections

Entity catalog, migration strategy, lifecycle, retention policies, and performance planning

▶

Template file

templates/specs/database-schema.md

spec_type

database-schema

Sections

Purpose Authoritative data model, scalability, integrity, governance expectations

Data Classification & Compliance Sensitivity levels, residency, encryption, regulatory mapping (GDPR, HIPAA, PCI)

System Overview Database engines, versions, replication, ERD/UML/Mermaid definitions

Entity Inventory Per-table docs: columns, types, constraints, indexes, partitioning

Relationships & Data Flows Foreign keys, cascades, cardinality, polymorphic relationships, caching

Stored Routines & Business Logic Functions, triggers, versioning, test coverage, idempotency

Migrations & Change Management Tooling (Prisma, Flyway, Atlas), review process, backward compatibility

Performance & Capacity Planning Data volumes, growth rates, sharding, benchmarks, slow query budgets

Data Lifecycle & Retention Archival, deletion windows, legal holds, backups, data masking

Observability & Quality Replication lag, deadlocks, queue depth, data quality checks

Caching & Performance

13 sections

Performance targets, cache layers, invalidation strategy, and performance budgets

▶

Template file

templates/specs/caching-and-performance.md

spec_type

caching-and-performance

Sections

Purpose How the app meets latency, throughput, and cost targets

Performance Targets SLIs/SLOs per surface (web, mobile, APIs), p95 latency, FPS

Workload & Access Patterns Read/write mix, burst behavior, multi-region, offline considerations

Caching Layers Edge CDN, application cache (Redis/Memcached), client cache with TTL strategies

Invalidation & Consistency Push vs pull, cache busting, read-after-write consistency, multi-device sync

Warm-Up & Precomputation Cache priming workflows, pre-generated data refresh cadence

Failure & Fallback Behavior Circuit breakers, exponential backoff, offline UX guidance

Instrumentation & Monitoring Hit ratio, eviction rate, memory usage, latency dashboards, alerts

Performance Testing Load testing plans, regression guardrails, perf gates, profiling cadence

Security & Compliance PII/PCI in caches, encryption, key rotation, multi-tenant isolation

Security & Compliance

13 sections

Threat modeling, access control, data protection, compliance controls, and incident response

▶

Template file

templates/specs/security-and-compliance.md

spec_type

security-and-compliance

Sections

Purpose How the system protects data and satisfies regulatory obligations

Scope & Assumptions Trust boundaries, shared vendor responsibilities, attacker capabilities

Data Classification & Handling Categories, retention, residency, encryption, GDPR/HIPAA/PCI/SOC 2 mapping

Threat Modeling Assets, actors, attack vectors via STRIDE/PASTA with trust boundary diagrams

Identity, AuthN & AuthZ MFA, SSO, session lifetimes, revocation, RBAC/ABAC/ReBAC models

Data Protection Controls TLS versions, cipher suites, KMS/HSM, secrets management (Vault, SSM)

Application Security Practices Secure coding, dependency governance, SBOM, SAST/DAST/IAST/fuzzing

Infrastructure & Network Security Segmentation, WAF, DDoS mitigation, zero-trust, container hardening

Compliance Controls & Evidence Policy owners, monitoring hooks, audit cadence, external assessments

Vulnerability & Incident Response Intake sources, SLAs, severity matrix, IR steps, tabletop schedule

Third-Party Risk Management Vendor inventory, data sharing agreements, offboarding

Observability & Incident Response

12 sections

SLIs/SLOs, telemetry coverage, alerting strategy, and incident management lifecycle

▶

Template file

templates/specs/observability-and-incident-response.md

spec_type

observability-and-incident-response

Sections

Purpose Instrumentation, monitoring, and incident support goals

Objectives & SLIs Business-aligned SLIs, SLOs/SLAs, reliability budgets, burn alerts

Telemetry Coverage Client, Edge, API, Data/Infra layers with metrics, logging, tracing columns

Instrumentation Standards OpenTelemetry, sampling rules, naming conventions, correlation IDs, privacy

Dashboards & Reporting Canonical dashboards per service, business KPIs vs system KPIs, release health

Alerting Strategy PagerDuty/OpsGenie routing, severity levels, escalation, noise budgets

Incident Response Lifecycle Detection, communication, mitigation (rollback, feature flags, kill switches), resolution

Runbooks & Playbooks Service-specific runbooks, synthetic checks, emergency access, load shedding

Post-Incident Review Postmortem template, timeline capture, action item tracking, learning distribution

Testing & Validation Chaos experiments, game days, failover drills, alert SLO reviews

Schema

Spec frontmatter

Every spec file starts with validated YAML frontmatter

---
spec_type: tech-stack
title: "Acme Corp Tech Stack"
owner: platform-team
status: approved
last_updated: 2026-04-12
applicability:
  - all-services
related_initiatives:
  - FTR-0001
---

Required fields

spec_type — one of 8 recognized types
title — human-readable name
status — draft, approved, or deprecated
last_updated — YYYY-MM-DD format
applicability — which services/products

Validated by: schemas/system-spec.schema.json via vb validate --only-specs

Getting Started

Use specs in your project

Copy templates

cp -r templates/specs/* specs/

Fill in decisions

Replace placeholder text with your project's specific decisions. Update status from draft to approved as decisions are reviewed.

Validate

vb validate --only-specs
vb validate tech-stack.md

Maintain over time

Specs are living documents. Update last_updated when decisions change. Set status: deprecated for replaced decisions — keep them as historical record.