Technical Design Rules
Basic Technology Stack Policy
TypeScript-based application implementation. Architecture patterns should be selected according to project requirements and scale.
Environment Variable Management and Security
Environment Variable Management
-
Centrally manage environment variables and build mechanisms to ensure type safety
-
Avoid direct references to process.env , obtain through configuration management layer
-
Properly implement default value settings and mandatory checks
Security
-
Do not include .env files in Git
-
Always manage API keys and secrets as environment variables
-
Prohibit logging of sensitive information
-
Do not include sensitive information in error messages
Architecture Design
Architecture Design Principles
Select appropriate architecture for each project and define clearly:
- Separation of Responsibilities: Clearly define responsibilities for each layer and module, and maintain boundaries
Unified Data Flow Principles
Basic Principles
-
Single Data Source: Store the same information in only one place
-
Structured Data Priority: Use parsed objects rather than JSON strings
-
Clear Responsibility Separation: Clearly define responsibilities for each layer
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
Use the appropriate run command based on the packageManager field in package.json.
Build Commands
-
build
-
TypeScript build
-
type-check
-
Type check (no emit)
Testing Commands
-
test
-
Run tests
-
test:coverage
-
Run tests with coverage
-
test:coverage:fresh
-
Run tests with coverage (fresh cache)
-
test:safe
-
Safe test execution (with auto cleanup)
-
cleanup:processes
-
Cleanup Vitest processes
Quality Check Requirements
Quality checks are mandatory upon implementation completion:
Phase 1-3: Code Quality Checks
-
Auto-detect and execute the following from package.json scripts:
-
lint + format check
-
Detect unused exports
-
Detect circular dependencies
-
TypeScript build
Phase 4: Tests
- test
- Test execution
Phase 5: Code Quality Re-verification
- check:code
- Re-verify code quality (clean up side effects from test fixes in Phase 4)
Auxiliary Commands
-
check:all
-
Overall integrated check (check:code + test) *for manual batch verification
-
open coverage/index.html
-
Check coverage report
-
format
-
Format fixes
-
lint:fix
-
Lint fixes
Troubleshooting
-
Port in use error: Run the cleanup:processes script
-
Cache issues: Run the test:coverage:fresh script
-
Dependency errors: Clean reinstall dependencies
Coverage Requirements
-
MANDATORY: Unit test coverage MUST be 70% or higher
-
Metrics: Statements, Branches, Functions, Lines