Technical Spec

Technical Design Rules

Prerequisite Detection

Inspect manifests, lockfiles, build/test configuration, CI definitions, and representative source files before applying a technology- or command-specific rule. Treat a tool, script, path alias, or runtime as observed only when repository evidence names it. Label conclusions from surrounding patterns as inferred. When a missing decision changes architecture, compatibility, security, or verification, stop and name the exact configuration or user decision required.

Basic Technology Stack Policy

These rules apply to a TypeScript application when repository configuration confirms that stack. Select architecture by mapping current requirements and accepted constraints to explicit module responsibilities, dependency direction, data flow, and verification boundaries.

Environment Variable Management and Security

Environment Variable Management

• Centrally manage environment variables and the build-time validation mechanism that enforces their type safety
• Read environment variables through one typed configuration boundary; application code consumes validated configuration values
• Give a variable a default only when requirements define valid behavior for absence; otherwise fail configuration validation with the variable name and expected format

Security

• Keep local .env files outside version control and provide non-secret example files for required variable names
• Load API keys and secrets from the configured secret store or runtime environment boundary
• Log and return only fields approved for the current trust boundary; redact credentials, tokens, personal data, and internal diagnostics before returning data across an untrusted boundary

Architecture Design

Architecture Design Principles

Select architecture using these observable decisions:

• Responsibilities: Each module/layer names the behavior it owns and the behavior it delegates
• Dependency direction: Imports and runtime calls follow the project boundary rules observed in configuration or representative implementations
• State/data ownership: Each persisted or mutable value has one authoritative owner
• Verification boundary: Each public contract has a unit, integration, or E2E check that can observe it

Unified Data Flow Principles

Basic Principles

1. Single Data Source: Store the same information in only one place
2. Structured Data Priority: Use parsed objects rather than JSON strings
3. Responsibility Separation: Each layer names the data or behavior it owns and the boundary through which other layers use it

Data Flow Best Practices

• Validation at Input: Validate data at input layer and pass internally in type-safe form
• Centralized Transformation: Consolidate data transformation logic in dedicated utilities
• Structured Logging: Output structured logs at each stage of data flow

Build and Testing

Select the package manager from the packageManager field, lockfile, or established CI command in that order. Execute only scripts present in the selected manifest.

Build Commands

• build - TypeScript build
• type-check - Type check (no emit)

Testing Commands

• test - Run tests