Eve library

Coding Guidelines - Lilith Project

Guide

Revision 1

On this page

Table of Contents#

  1. General Principles
  2. File Length Enforcement
  3. JavaScript/Node.js Standards
  4. TypeScript Standards
  5. API Design Standards
  6. Database & Storage
  7. Security Guidelines
  8. Testing Standards
  9. Documentation Requirements
  10. Performance Standards
  11. 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:repo blocks 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#

  1. Identify concerns: Break down what the file does (validation, storage, notifications, etc.)
  2. Extract modules: Create separate files for each concern
  3. Write tests: Add unit tests for extracted modules (≥95% coverage)
  4. 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:

  1. Runs npm run lint:file-length:repo automatically
  2. Fails if any new files exceed 500 lines
  3. 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:

  1. Check existing code patterns in similar contexts
  2. Discuss in team Slack channel
  3. Propose changes via ADR (Architecture Decision Record)