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
• API documentation: OpenAPI, code-first from Zod schemas and route metadata

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

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:e2e
pnpm build
pnpm openapi:check
pnpm secrets:scan

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.