# Technical Defaults & Standards This document provides default technical decisions to reduce clarification cycles during planning and specification phases. Use these defaults unless explicitly overridden by requirements. --- ## Technology Stack Defaults ### TypeScript Projects (Node.js/React) **Mandated Stack** (not negotiable): ```yaml package_manager: pnpm # NEVER npm or yarn dev_environment: devcontainer # Required for consistency unit_testing: vitest # NEVER jest, mocha e2e_testing: playwright # NEVER cypress, puppeteer container_testing: testcontainers # For database/service tests ``` **Default Stack** (use unless specified otherwise): ```yaml validation: zod # Input/schema validation http_client: axios # For external API calls logging: pino # Structured logging state_management_react: zustand # Lightweight, simple forms_react: react-hook-form # With zod resolver query_client_react: tanstack-query # Server state management ui_components_react: radix-ui # Headless, accessible styling_react: css-modules # Or tailwindcss ``` **Reasoning**: These tools are already proven, well-documented, and align with project standards. --- ## Architecture Defaults ### Project Structure **Backend (Node.js/Express)**: ``` src/ ├── types/ # TypeScript types and interfaces ├── models/ # Database models/entities ├── repositories/ # Data access layer ├── services/ # Business logic ├── controllers/ # Request handlers ├── routes/ # Route definitions ├── middleware/ # Express middleware ├── utils/ # Helper functions └── config/ # Configuration ``` **Frontend (React)**: ``` src/ ├── components/ │ ├── atoms/ # Basic building blocks │ ├── molecules/ # Composite components │ ├── organisms/ # Complex components │ ├── templates/ # Page layouts │ └── pages/ # Full pages ├── hooks/ # Custom React hooks ├── services/ # API clients ├── stores/ # State management ├── types/ # TypeScript types └── utils/ # Helper functions ``` **Reasoning**: Atomic Design for frontend, layered architecture for backend. --- ## Naming Conventions ### Files and Directories **Default Conventions**: ```yaml files: kebab-case # user-profile.ts directories: kebab-case # user-profile/ components: PascalCase # UserProfile.tsx test_files: .test.ts # user-profile.test.ts types: .types.ts # user-profile.types.ts styles: .module.css # user-profile.module.css ``` ### Code **TypeScript/JavaScript**: ```typescript // Classes/Interfaces: PascalCase (nouns) class UserRepository {} interface PaymentGateway {} // Functions/Methods: camelCase (verbs for actions, nouns for getters) function calculateTotal() {} function userName() {} // Constants: UPPER_SNAKE_CASE const MAX_RETRIES = 3; const API_BASE_URL = 'https://api.example.com'; // Variables: camelCase const userEmail = 'test@example.com'; let retryCount = 0; ``` **Avoid**: - ❌ Hungarian notation: `IPaymentGateway`, `strUserName` - ❌ Verbs for classes: `ProcessData`, `HandleRequest` - ❌ Abbreviations: `usr`, `btn`, `msg` (unless extremely common: `id`, `url`, `api`) --- ## Testing Defaults ### Test Organization **File naming**: ``` src/services/user.ts → tests/unit/services/user.test.ts src/routes/auth.ts → tests/integration/routes/auth.test.ts src/components/LoginForm.tsx → tests/e2e/login.spec.ts ``` **Test structure** (Vitest): ```typescript describe('UserService', () => { describe('createUser', () => { it('should create user with valid data', async () => { // Arrange const userData = { email: 'test@example.com', name: 'Test' }; // Act const result = await userService.createUser(userData); // Assert expect(result.email).toBe(userData.email); }); it('should throw error for invalid email', async () => { // Arrange const invalidData = { email: 'invalid', name: 'Test' }; // Act & Assert await expect(userService.createUser(invalidData)).rejects.toThrow('Invalid email'); }); }); }); ``` ### Coverage Targets **Minimum Requirements**: ```yaml line_coverage: 80% branch_coverage: 75% function_coverage: 90% statement_coverage: 80% ``` **Test Types Required**: - ✅ Unit tests for all business logic - ✅ Integration tests for all API endpoints - ✅ E2E tests for critical user flows - ✅ Accessibility tests (vitest-axe) for all UI components --- ## Error Handling Defaults ### Standard Error Response (APIs) **Format**: ```typescript interface ErrorResponse { error: { code: string; // e.g., "VALIDATION_ERROR", "NOT_FOUND" message: string; // Human-readable message details?: unknown; // Optional additional context timestamp: string; // ISO 8601 path: string; // Request path }; } ``` **Example**: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Email address is invalid", "details": { "field": "email", "value": "invalid-email" }, "timestamp": "2025-01-30T12:34:56.789Z", "path": "/api/users" } } ``` ### HTTP Status Codes **Use these by default**: ```yaml 200: Successful GET, PUT, PATCH 201: Successful POST (resource created) 204: Successful DELETE (no content) 400: Bad request (validation error) 401: Unauthorized (missing/invalid auth) 403: Forbidden (insufficient permissions) 404: Not found (resource doesn't exist) 409: Conflict (duplicate resource) 422: Unprocessable entity (semantic error) 500: Internal server error 503: Service unavailable ``` --- ## Security Defaults ### Authentication **Default Approach**: JWT tokens **Token Structure**: ```typescript interface JWTPayload { sub: string; // User ID email: string; // User email role: string; // User role (e.g., "user", "admin") iat: number; // Issued at exp: number; // Expiration } ``` **Token Expiration**: ```yaml access_token: 15 minutes refresh_token: 7 days email_verification: 24 hours password_reset: 1 hour ``` ### Password Hashing **Default Algorithm**: Argon2 **Fallback**: bcrypt (10 rounds minimum) **Never Use**: MD5, SHA1, plain bcrypt < 10 rounds ### Input Validation **Always Validate**: - ✅ All user inputs (body, query, params) - ✅ Email addresses (use regex + DNS check) - ✅ URLs (whitelist protocols: https, http) - ✅ File uploads (type, size, extension) - ✅ JSON payloads (schema validation with Zod) **Never Trust**: - ❌ Client-side validation alone - ❌ User-provided IDs without authorization check - ❌ File extensions (check MIME type) - ❌ Redirect URLs (whitelist domains) --- ## Database Defaults ### ORM/Query Builder **Default**: Prisma (for TypeScript projects) **Migrations**: ```bash # Create migration pnpm prisma migrate dev --name add_user_email_verified # Apply migration (production) pnpm prisma migrate deploy # Rollback (if supported) pnpm prisma migrate reset ``` ### Indexing Strategy **Always Index**: - Primary keys (automatic) - Foreign keys - Columns in WHERE clauses - Columns in ORDER BY clauses - Frequently joined columns **Index Naming**: ```sql -- Format: idx___ CREATE INDEX idx_users_email ON users(email); CREATE INDEX idx_posts_author_created ON posts(author_id, created_at); ``` ### Query Performance **Default Rules**: - ✅ Use `SELECT` with specific columns (not `SELECT *`) - ✅ Add `LIMIT` to queries returning multiple rows - ✅ Use pagination (offset/limit or cursor-based) - ✅ Avoid N+1 queries (use joins or eager loading) - ✅ Use database transactions for multi-step operations **Pagination Default**: ```typescript interface PaginationParams { page: number; // Default: 1 limit: number; // Default: 20, Max: 100 sortBy?: string; // Default: "created_at" sortOrder?: 'asc' | 'desc'; // Default: "desc" } ``` --- ## Logging Defaults ### Log Levels **When to Use Each Level**: ```yaml error: Operation failures, exceptions warn: Recoverable issues, deprecation warnings info: Key business events (user registered, order placed) debug: Detailed debugging info (dev/staging only) trace: Very verbose debugging (dev only) ``` ### Structured Logging Format **Use JSON** (parseable by log aggregators): ```typescript logger.info('User registered', { userId: user.id, email: user.email, timestamp: new Date().toISOString(), source: 'auth-service', action: 'register' }); ``` **Don't Log**: - ❌ Passwords or tokens - ❌ Full credit card numbers - ❌ Social Security Numbers - ❌ PII without anonymization (in production) --- ## API Design Defaults ### RESTful Conventions **Resource Naming**: ```yaml # Plural nouns for collections GET /api/users # List users POST /api/users # Create user GET /api/users/:id # Get user PUT /api/users/:id # Replace user (full update) PATCH /api/users/:id # Update user (partial) DELETE /api/users/:id # Delete user # Nested resources GET /api/users/:id/posts # User's posts POST /api/users/:id/posts # Create post for user GET /api/users/:id/posts/:postId # Specific post ``` **Query Parameters**: ```yaml # Filtering GET /api/users?role=admin&status=active # Sorting GET /api/users?sortBy=created_at&sortOrder=desc # Pagination GET /api/users?page=2&limit=20 # Search GET /api/users?search=john ``` ### Request/Response Format **Request Body (POST/PUT/PATCH)**: ```json { "email": "user@example.com", "name": "John Doe", "role": "user" } ``` **Success Response**: ```json { "data": { "id": "usr_123", "email": "user@example.com", "name": "John Doe", "role": "user", "createdAt": "2025-01-30T12:34:56.789Z" }, "meta": { "timestamp": "2025-01-30T12:34:56.789Z" } } ``` **Collection Response (with pagination)**: ```json { "data": [ { "id": "usr_1", "email": "user1@example.com" }, { "id": "usr_2", "email": "user2@example.com" } ], "meta": { "total": 50, "page": 1, "limit": 20, "totalPages": 3 } } ``` --- ## Performance Defaults ### Caching Strategy **Default TTLs**: ```yaml static_content: 1 year # CSS, JS, images (with cache busting) api_responses: 5 minutes # Frequently changing data user_sessions: 1 hour # User-specific data database_queries: 10 minutes # Expensive queries ``` **Cache Headers**: ```http # Immutable static assets Cache-Control: public, max-age=31536000, immutable # API responses Cache-Control: public, max-age=300 # Private user data Cache-Control: private, max-age=3600 # Never cache Cache-Control: no-store ``` ### Rate Limiting **Default Limits**: ```yaml # Per IP address public_endpoints: 100 requests/15 minutes auth_endpoints: 5 requests/15 minutes (login, register) api_general: 1000 requests/hour api_burst: 10 requests/second # Per user (authenticated) api_general: 10000 requests/hour api_burst: 100 requests/second ``` --- ## Accessibility Defaults ### WCAG Compliance **Target Level**: WCAG 2.1 AA **Required Attributes**: ```html Email

``` ### Keyboard Navigation **Required Support**: - ✅ Tab: Navigate forward - ✅ Shift+Tab: Navigate backward - ✅ Enter: Activate button/link - ✅ Space: Activate button, check/uncheck checkbox - ✅ Escape: Close modals/dialogs - ✅ Arrow keys: Navigate within components (lists, menus) --- ## Git Workflow Defaults ### Commit Message Format **Convention**: Conventional Commits **Format**: ``` ():