TypeScript Software Architecture & Design Baseline

This repository documentation package defines the shared TypeScript engineering baseline for backend, frontend, AI, automation and fullstack projects.

Purpose

The goal is to create projects that are secure by default, deployable from day one, easy to evolve, easy to test, and understandable by both humans and AI coding assistants.

Status

Baseline documentation package: Accepted.

Default Stack

• Runtime: Node.js
• Package manager: pnpm
• Module system: ESM
• Validation: Zod
• Linting: ESLint
• Formatting: Prettier
• Unit/component/integration tests: Vitest
• E2E tests: Playwright
• Default database: PostgreSQL
• Default BaaS: Supabase
• Default ORM for PostgreSQL/Supabase: Drizzle
• Delivery intent: Spec Kit 1.0.5 living specifications
• Spec Kit integrations: OpenCode (dogfooded), plus the supported upstream integrations
• Acceptance behavior: Cucumber/Gherkin
• Implementation TDD: Vitest
• External interfaces: selectable contract-first OpenAPI, AsyncAPI, GraphQL, and gRPC profiles

Documentation

• Architecture
• Engineering Standards
• Product Delivery Standard
• API Standard
• Security Standard
• Testing Standard
• Database Standard
• Deployment Standard
• Observability Standard
• Product Context Template
• Architecture Decision Records
• Engineering Baseline Quickstart

Required Repository Files

• .github/CODEOWNERS
• .github/pull_request_template.md
• .github/copilot-instructions.md
• docs/adr/*
• docs/engineering-standards.md

Common Commands

pnpm install
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:bdd:dry
pnpm test:bdd
pnpm test:e2e
pnpm build
pnpm contracts:check
pnpm baseline:verify
pnpm baseline:check
pnpm secrets:scan

OpenCode Spec Kit Integration

This repository dogfoods the official Spec Kit 1.0.5 OpenCode integration. Spec Kit commands are installed under .opencode/commands/, and the active integration is recorded in .specify/integration.json and .specify/integrations/opencode.manifest.json.

Use commands such as /speckit.specify, /speckit.plan, and /speckit.implement from OpenCode. After changing OpenCode commands or configuration, restart OpenCode so it reloads the project files.

Core Principle

Architecture should keep business policy at the center. Frameworks, databases, SDKs, APIs, UI libraries, queues, caches and AI providers are implementation details and should remain replaceable through clear boundaries.

How to use with VS Code Agent Skills

This repository contains project-level Agent Skills for TypeScript software architecture, coding, and review workflows.

VS Code supports project skills from the following locations:

.github/skills/
.claude/skills/
.agents/skills/

Use the delivery skills according to the decision being made:

• validate-poc tests one to three high-impact uncertainties with explicit success, failure and inconclusive criteria. It ends with a Go, Pivot, Stop or Inconclusive recommendation and does not imply production readiness.
• build-mvp delivers the smallest releasable end-to-end outcome for a defined early audience. It minimizes feature scope while retaining the applicable security, data integrity, validation, testing, observability, deployment, rollback and support requirements.

Use validate-poc before build-mvp when a critical feasibility assumption remains unresolved. See the Product Delivery Standard and ADR-0017 for the governing policy.

For delivery work, use the Spec Kit commands and the reusable bundle under tooling/spec-kit/typescript-engineering-baseline/. The workflow combines specification-driven scope, Gherkin behavior, Vitest TDD, and contract-first design. Stable 1.0.0 remains gated by the documented release matrix.