Table of Contents#
- General Principles
- File Length Enforcement
- JavaScript/Node.js Standards
- TypeScript Standards
- API Design Standards
- Database & Storage
- Security Guidelines
- Testing Standards
- Documentation Requirements
- Performance Standards
- Error Handling
General Principles#
Code Quality#
- Readability over cleverness: Code should be self-documenting
- Consistency: Follow established patterns within the codebase
- Single Responsibility: Each function/module should have one clear purpose
- DRY (Don't Repeat Yourself): Extract common patterns into reusable components
- YAGNI (You Aren't Gonna Need It): Don't build features until they're needed
Architecture Principles#
- Microservices: Each service should be independently deployable
- Fail Fast: Validate inputs early and provide clear error messages
- Idempotency: Operations should be safely retryable
- Observability: All services must provide health checks, metrics, and structured logging
File Length Enforcement#
The 500-line limit ensures files remain testable, reviewable, and maintainable.
Quick Rules#
- ✅ Maximum 500 lines per source file (TypeScript, JavaScript, Python, Go, Rust, etc.)
- ✅ Auto-ignored: Build outputs, lock files, generated code, coverage reports, caches
- ❌ Enforced in CI:
npm run lint:file-length:repoblocks new violations on every commit - 🔧 Refactor strategy: Extract related functionality into focused modules with dedicated tests
Running the Audit#
bash
# Check for new violations (what CI runs)
npm run lint:file-length:repo
# Audit entire repo without failing
node scripts/file-length-audit.js --root . --max 500
# Audit a specific service
node scripts/file-length-audit.js --root services/bff --max 500 --json
When Your File Gets Too Large#
- Identify concerns: Break down what the file does (validation, storage, notifications, etc.)
- Extract modules: Create separate files for each concern
- Write tests: Add unit tests for extracted modules (≥95% coverage)
- Organize: Group related modules in a directory with clear names
Example: A 520-line ChatService.ts can be refactored into:
services/chat/validators.ts(100 lines, tests in__tests__/validators.test.ts)services/chat/storage.ts(150 lines, tests in__tests__/storage.test.ts)services/chat/notifications.ts(120 lines, tests in__tests__/notifications.test.ts)services/chat/index.ts(150 lines, orchestrates the above)
CI Enforcement#
Every PR:
- Runs
npm run lint:file-length:repoautomatically - Fails if any new files exceed 500 lines
- Passes if all new files are ≤500 lines
Existing violations are tracked in scripts/file-length-baseline.repo.json
(which should remain empty).
For more details, see File Length Policy in CODING_STANDARDS.md
JavaScript/Node.js Standards#
Code Style#
- Use ESLint configuration (see
eslint.config.js) - Use Prettier for formatting (see
.prettierrc.js) - Use CommonJS (
require/module.exports) for services - Use ESM (
import/export) for SDK and frontend code
Variable Naming#
javascript
// Use camelCase for variables and functions
const userId = 'user-123';
const getUserProfile = (id) => {
/* ... */
};
// Use PascalCase for constructors and classes
class UserService {
/* ... */
}
// Use UPPER_SNAKE_CASE for constants
const MAX_RETRY_ATTEMPTS = 3;
const JWT_SECRET = process.env.JWT_SECRET;
// Use kebab-case for file names
// user-service.js, conversation-manager.js
Function Guidelines#
javascript
// Prefer async/await over callbacks
async function fetchUserData(userId) {
try {
const user = await userRepository.findById(userId);
return user;
} catch (error) {
throw new Error(`Failed to fetch user: ${error.message}`);
}
}
// Use descriptive parameter names
function createChat(conversationId, messageText, persona) {
// Implementation
}
// Document complex functions
/**
* Normalizes service errors for client consumption
* @param {Error} originalError - The original error from service
* @param {string} clientType - Type of client (web, mobile, api)
* @param {object} requestContext - Request context for tracing
* @returns {object} Normalized error response
*/
function normalizeError(originalError, clientType, requestContext) {
// Implementation
}
Error Handling#
javascript
// Use structured error objects
class ValidationError extends Error {
constructor(message, field) {
super(message);
this.name = 'ValidationError';
this.code = 'VALIDATION_ERROR';
this.field = field;
this.statusCode = 400;
}
}
// Always handle promise rejections
app.get('/api/endpoint', async (req, reply) => {
try {
const result = await someAsyncOperation();
return result;
} catch (error) {
app.log.error('Operation failed:', error);
return reply.code(500).send({ error: 'Internal server error' });
}
});
TypeScript Standards#
Type Definitions#
typescript
// Use interfaces for object shapes
interface UserProfile {
id: string;
email_hash: string;
display_name: string;
created_at: string;
preferences: UserPreferences;
}
// Use types for unions and primitives
type PersonaId = 'zen' | 'stoic' | 'sufi';
type Environment = 'development' | 'staging' | 'production';
// Use generics for reusable types
interface ApiResponse<T> {
data: T;
meta: {
timestamp: string;
correlation_id: string;
};
}
File Organization#
text
src/
├── types/ # Shared type definitions
│ ├── api.ts # API response types
│ ├── models.ts # Domain model types
│ └── index.ts # Re-exports
├── utils/ # Utility functions
├── services/ # Business logic
└── api/ # API clients
API Design Standards#
REST Conventions#
text
GET /v1/conversations # List conversations
POST /v1/conversations # Create conversation
GET /v1/conversations/:id # Get specific conversation
PUT /v1/conversations/:id # Update conversation
DELETE /v1/conversations/:id # Delete conversation
# Use query parameters for filtering/pagination
GET /v1/conversations?user_id=123&limit=20&offset=0
# Use nested resources appropriately
GET /v1/conversations/:id/messages
POST /v1/conversations/:id/messages
Request/Response Format#
javascript
// Request headers
{
"content-type": "application/json",
"x-correlation-id": "uuid-v4",
"x-user-id": "user-123",
"idempotency-key": "uuid-v4" // For non-idempotent operations
}
// Success response
{
"data": { /* actual data */ },
"meta": {
"timestamp": "2025-09-14T12:00:00Z",
"correlation_id": "abc-123"
}
}
// Error response
{
"error": {
"code": "validation_error",
"message": "User-friendly error message",
"details": { /* additional context */ }
},
"meta": {
"timestamp": "2025-09-14T12:00:00Z",
"correlation_id": "abc-123"
}
}
Correlation IDs#
- All requests must include or generate a correlation ID
- Propagate correlation IDs through service calls
- Include in all log messages and error responses
Database & Storage#
Schema Design#
javascript
// Use consistent naming conventions
const userSchema = {
id: 'string', // Primary keys always 'id'
email_hash: 'string', // Use snake_case for columns
display_name: 'string', // Be explicit about names
created_at: 'datetime', // Always include timestamps
updated_at: 'datetime',
};
// Use soft deletes when appropriate
const conversationSchema = {
id: 'string',
title: 'string',
deleted_at: 'datetime', // null = not deleted
created_at: 'datetime',
updated_at: 'datetime',
};
Migration Guidelines#
- Migrations must be backward compatible
- Use transactions for multi-step migrations
- Test migrations on production-sized datasets
- Always include rollback procedure
Security Guidelines#
Input Validation#
javascript
// Validate all inputs at API boundaries
app.post('/v1/chat', async (req, reply) => {
const { persona, input, options } = req.body;
if (!persona || !['zen', 'stoic', 'sufi'].includes(persona)) {
return reply.code(400).send({ error: 'Invalid persona' });
}
if (!input?.text || input.text.length > 5000) {
return reply.code(400).send({ error: 'Invalid input text' });
}
// Continue with validated data
});
Secrets Management#
- NEVER commit secrets to version control
- Use environment variables for configuration
- Rotate secrets regularly
- Use KMS/Vault for production secrets
javascript
// ❌ Never do this
const apiKey = 'sk-1234567890abcdef';
// ✅ Use environment variables
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
throw new Error('OPENAI_API_KEY environment variable is required');
}
Authentication & Authorization#
javascript
// Use middleware for authentication
app.addHook('preHandler', async (req, reply) => {
const token = req.headers.authorization?.replace('Bearer ', '');
if (!token) {
return reply.code(401).send({ error: 'Authentication required' });
}
try {
req.user = await verifyJWT(token);
} catch (error) {
return reply.code(401).send({ error: 'Invalid token' });
}
});
Testing Standards#
Test Structure#
javascript
// Use descriptive test names
describe('User authentication', () => {
describe('when valid credentials are provided', () => {
test('should return JWT token and user profile', async () => {
// Arrange
const credentials = {
email: 'user@example.com',
password: 'password123',
};
// Act
const response = await request(app)
.post('/v1/auth/login')
.send(credentials);
// Assert
expect(response.status).toBe(200);
expect(response.body).toHaveProperty('token');
expect(response.body.user).toHaveProperty('id');
});
});
describe('when invalid credentials are provided', () => {
test('should return 401 with error message', async () => {
// Implementation
});
});
});
Test Categories#
- Unit Tests: Test individual functions/modules
- Integration Tests: Test service interactions
- End-to-End Tests: Test complete user workflows
- Performance Tests: Validate latency and throughput requirements
Coverage Requirements#
- Minimum 80% code coverage for new code
- 100% coverage for critical security functions
- All public API endpoints must have tests
Documentation Requirements#
Code Comments#
javascript
// Use JSDoc for public functions
/**
* Retrieves user profile with caching
* @param {string} userId - Unique user identifier
* @param {object} options - Retrieval options
* @param {boolean} options.skipCache - Bypass cache if true
* @returns {Promise<UserProfile>} User profile object
* @throws {UserNotFoundError} When user doesn't exist
*/
async function getUserProfile(userId, options = {}) {
// Implementation comments for complex logic
if (options.skipCache) {
// Direct database query when cache is bypassed
return await userRepository.findById(userId);
}
// Check cache first for better performance
return await cacheManager.getOrSet(
`user:${userId}`,
() => userRepository.findById(userId),
{ ttl: 300 } // 5 minutes
);
}
README Requirements#
Each service must include:
- Purpose and responsibilities
- API endpoints documentation
- Environment variables
- Local development setup
- Testing instructions
Performance Standards#
Response Time Requirements#
- API endpoints: p50 < 200ms, p95 < 500ms
- Health checks: < 50ms
- Chat completion: p50 < 2s, p95 < 4s
- TTS first byte: < 600ms
Resource Usage#
javascript
// Use streaming for large responses
app.get('/v1/chat', async (req, reply) => {
reply.raw.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
});
for await (const token of generateResponse(prompt)) {
reply.raw.write(`data: ${JSON.stringify({ token })}\n\n`);
}
reply.raw.end();
});
// Use connection pooling for databases
const dbPool = createPool({
host: process.env.DB_HOST,
min: 5,
max: 20,
acquireTimeout: 10000,
});
Caching Strategy#
- Use Redis for session storage and fast lookups
- Implement cache warming for frequently accessed data
- Set appropriate TTL values based on data freshness requirements
Error Handling#
Service Error Codes#
javascript
// Use consistent error codes across services
const ErrorCodes = {
// Validation errors (400)
VALIDATION_ERROR: 'validation_error',
MISSING_PARAMETER: 'missing_parameter',
// Authentication errors (401)
INVALID_TOKEN: 'invalid_token',
TOKEN_EXPIRED: 'token_expired',
// Authorization errors (403)
INSUFFICIENT_PERMISSIONS: 'insufficient_permissions',
RESOURCE_ACCESS_DENIED: 'resource_access_denied',
// Not found errors (404)
USER_NOT_FOUND: 'user_not_found',
CONVERSATION_NOT_FOUND: 'conversation_not_found',
// Rate limiting (429)
RATE_LIMIT_EXCEEDED: 'rate_limit_exceeded',
QUOTA_EXCEEDED: 'quota_exceeded',
// Server errors (500)
INTERNAL_ERROR: 'internal_error',
SERVICE_UNAVAILABLE: 'service_unavailable',
DATABASE_ERROR: 'database_error',
};
Logging Standards#
javascript
// Use structured logging
app.log.info(
{
event: 'user_login',
user_id: user.id,
ip_address: req.ip,
user_agent: req.headers['user-agent'],
correlation_id: req.headers['x-correlation-id'],
},
'User logged in successfully'
);
app.log.error(
{
event: 'database_error',
error: error.message,
stack: error.stack,
query: sanitizeQuery(query),
correlation_id: req.headers['x-correlation-id'],
},
'Database query failed'
);
Enforcement#
These guidelines are enforced through:
- ESLint and Prettier in CI pipeline
- Code reviews - all PRs require approval
- Pre-commit hooks - prevent commits that violate standards
- Automated testing - failing tests block deployments
For questions about these guidelines, please:
- Check existing code patterns in similar contexts
- Discuss in team Slack channel
- Propose changes via ADR (Architecture Decision Record)