# Coding Guidelines - Lilith Project

## Table of Contents

1. [General Principles](#general-principles)
2. [File Length Enforcement](#file-length-enforcement)
3. [JavaScript/Node.js Standards](#javascriptnodejs-standards)
4. [TypeScript Standards](#typescript-standards)
5. [API Design Standards](#api-design-standards)
6. [Database & Storage](#database--storage)
7. [Security Guidelines](#security-guidelines)
8. [Testing Standards](#testing-standards)
9. [Documentation Requirements](#documentation-requirements)
10. [Performance Standards](#performance-standards)
11. [Error Handling](#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](../CODING_STANDARDS.md#6-file-length-ceiling-maintainability)

## 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

```
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

```
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)
