# ADR-0001: Fastify-based Microservices Architecture

**Status**: Accepted **Date**: 2025-01-28 **Authors**: Claude Code Assistant
**Reviewers**: Development Team **Supersedes**: N/A **Superseded by**: N/A

## Context and Problem Statement

The Lilith platform requires a scalable, maintainable backend architecture to
support multiple services including authentication, content management, AI
orchestration, and user interactions. We need to choose a framework and
architectural pattern that supports:

- High-performance API endpoints with low latency
- Independent service deployment and scaling
- Type-safe development with TypeScript
- Comprehensive testing capabilities
- Maintainable codebase with clear service boundaries

The platform expects to handle 10k+ concurrent users with sub-200ms response
times for most operations.

## Decision Drivers

- **Performance Requirements**: < 200ms API response times, support for 10k+
  concurrent users
- **Type Safety**: Full TypeScript support for development safety
- **Developer Experience**: Fast development cycles, good tooling, clear
  patterns
- **Scalability**: Independent service scaling, horizontal scaling capabilities
- **Maintainability**: Clear service boundaries, testable code, documentation
- **Ecosystem**: Strong npm ecosystem, active community support
- **Team Expertise**: Node.js/TypeScript expertise available
- **Testing**: Comprehensive testing capabilities (unit, integration, E2E)

## Considered Options

### Option 1: Express.js Microservices

**Description**: Traditional Express.js framework with custom microservices
structure

**Pros**:

- ✅ Mature ecosystem with extensive middleware
- ✅ Team familiarity and widespread adoption
- ✅ Flexible and unopinionated framework
- ✅ Excellent documentation and community support

**Cons**:

- ❌ Lower performance compared to modern alternatives
- ❌ Requires more boilerplate for common patterns
- ❌ Less built-in TypeScript optimization
- ❌ Manual schema validation setup required

**Cost**: Low implementation cost, moderate operational overhead **Risk**: Low -
proven technology **Effort**: 2-3 weeks for initial setup

### Option 2: Fastify Microservices

**Description**: High-performance Fastify framework with TypeScript-first
microservices

**Pros**:

- ✅ Superior performance (2-3x faster than Express)
- ✅ Built-in TypeScript support and schema validation
- ✅ Plugin ecosystem with consistent patterns
- ✅ Auto-generated documentation from schemas
- ✅ Built-in logging and serialization optimization
- ✅ Lower memory footprint

**Cons**:

- ❌ Smaller ecosystem compared to Express
- ❌ Newer framework with evolving patterns
- ❌ Learning curve for team members

**Cost**: Low implementation cost, lower operational costs due to efficiency
**Risk**: Medium - newer but stable technology **Effort**: 2-3 weeks for initial
setup plus learning time

### Option 3: NestJS Microservices

**Description**: Enterprise-grade framework with decorator-based architecture

**Pros**:

- ✅ Enterprise-grade features and patterns
- ✅ Built-in dependency injection and modular architecture
- ✅ Excellent TypeScript integration
- ✅ Comprehensive testing utilities

**Cons**:

- ❌ Higher complexity and learning curve
- ❌ More opinionated framework limiting flexibility
- ❌ Higher memory usage and slower startup
- ❌ Potential over-engineering for current needs

**Cost**: Higher implementation cost due to complexity **Risk**: Medium -
framework complexity **Effort**: 4-6 weeks for team onboarding and setup

## Decision Outcome

**Chosen option**: Option 2 - Fastify Microservices

**Justification**: Fastify was selected because it best addresses our primary
decision drivers:

1. **Performance**: 2-3x better performance than Express meets our < 200ms
   requirements
2. **TypeScript Integration**: Built-in TypeScript support reduces development
   overhead
3. **Schema Validation**: Automatic request/response validation with JSON Schema
4. **Documentation**: Auto-generated OpenAPI specs from route schemas
5. **Efficiency**: Lower resource usage reduces operational costs
6. **Modern Patterns**: Plugin architecture promotes maintainable code

Trade-offs accepted:

- Smaller ecosystem than Express (mitigated by Node.js ecosystem compatibility)
- Team learning curve (offset by better developer experience)

**Implementation Plan**:

1. **Phase 1** (Week 1-2): Core service template, authentication service
2. **Phase 2** (Week 3-4): Content and moderation services
3. **Phase 3** (Week 5-6): AI orchestration and remaining services

**Success Metrics**:

- API response times: 95th percentile < 200ms
- Development velocity: Service implementation time < 1 week per service
- Code quality: 99%+ test coverage, 0 ESLint errors
- Documentation coverage: 100% API endpoints documented

**Review Schedule**: 3 months post-implementation

## Implementation Details

### Technical Specifications

- **Framework**: Fastify v4+ with TypeScript
- **Schema Validation**: JSON Schema with automatic type generation
- **Logging**: Fastify built-in logger with structured output
- **Health Checks**: Standardized /health endpoints
- **Error Handling**: Consistent error response format
- **Documentation**: Auto-generated OpenAPI 3.1 specs

### Service Template Structure

```typescript
// services/<service>/src/app.ts
export function buildServer(opts: BuildServerOptions = {}): FastifyInstance {
  const app = Fastify({
    logger: true,
    // Schema compilation for performance
    ajv: {
      customOptions: { strict: 'log' },
    },
  });

  // Health check
  app.get('/health', async () => ({
    status: 'healthy',
    service: SERVICE_NAME,
    timestamp: new Date().toISOString(),
  }));

  return app;
}
```

### Migration Strategy

- **From**: Initial stub services with basic Express-like structure
- **To**: Standardized Fastify services with full schema validation
- **Steps**:
  1. Create Fastify service template
  2. Migrate authentication service first
  3. Parallel migration of remaining services
  4. Integration testing and validation
- **Rollback Plan**: Maintain Express compatibility layer during transition
- **Timeline**: 6 weeks for complete migration

### Testing Strategy

- **Unit Tests**: Jest with Fastify injection testing
- **Integration Tests**: Service-to-service communication validation
- **Schema Tests**: Request/response schema validation
- **Performance Tests**: Load testing against response time requirements
- **E2E Tests**: Playwright for complete user workflows

## Consequences

### Positive Consequences

- ✅ **Performance**: 2-3x improvement in request throughput and response times
- ✅ **Type Safety**: Compile-time error detection reduces runtime issues
- ✅ **Developer Experience**: Auto-completion, schema validation, and
  documentation
- ✅ **Operational Efficiency**: Lower memory usage and CPU consumption
- ✅ **Code Quality**: Consistent patterns and built-in validation

### Negative Consequences

- ❌ **Learning Curve**: Team needs to learn Fastify-specific patterns
- ❌ **Ecosystem**: Some Express-specific middleware requires adaptation
- ❌ **Migration Effort**: Existing stub services need refactoring

### Risks and Mitigation

| Risk                        | Probability | Impact | Mitigation Strategy                      |
| --------------------------- | ----------- | ------ | ---------------------------------------- |
| Team adoption challenges    | Medium      | Medium | Comprehensive training and documentation |
| Plugin compatibility issues | Low         | Medium | Thorough plugin evaluation and testing   |
| Performance regression      | Low         | High   | Comprehensive performance testing        |

## Compliance and Security

### Security Implications

- **Input Validation**: Schema-based validation prevents injection attacks
- **Rate Limiting**: Built-in rate limiting capabilities
- **CORS**: Configurable CORS policies per service
- **Headers**: Security headers automatically applied

### Compliance Requirements

- **Logging**: Structured logs for audit trails
- **Monitoring**: APM integration for performance tracking
- **Documentation**: Auto-generated API docs for compliance reviews

## Monitoring and Observability

### Metrics to Track

- **Performance**: Response times, throughput, error rates per endpoint
- **Business**: API usage patterns, feature adoption
- **Operational**: Memory usage, CPU utilization, service health

### Alerting Strategy

- **Critical**: Service unavailable, high error rates (>5%)
- **Warning**: Response time degradation (>500ms), high memory usage
- **Info**: Deployment events, configuration changes

### Dashboards

- **Operations**: Service health, response times, error rates
- **Business**: API usage, endpoint popularity
- **Development**: Test coverage, deployment frequency

## Related Decisions

### Upstream Dependencies

- **Technology Stack**: Node.js/TypeScript decision
- **Deployment Strategy**: Kubernetes/Docker decisions

### Downstream Impacts

- **API Gateway**: Requires Fastify-compatible routing
- **Authentication**: Fastify plugin architecture for auth middleware
- **Monitoring**: APM integration with Fastify lifecycle hooks

## References

### External Resources

- [Fastify Documentation](https://www.fastify.io/docs/)
- [Fastify TypeScript Guide](https://www.fastify.io/docs/latest/Guides/TypeScript/)
- [Performance Benchmarks](https://www.fastify.io/benchmarks/)

### Internal Resources

- [Service Template Implementation](../../../services/moderation/src/app.ts)
- [Testing Patterns](../../../services/moderation/__tests__/)
- [Coding Standards](../../CODING_STANDARDS.md)

---

## Revision History

| Version | Date       | Author                | Changes         |
| ------- | ---------- | --------------------- | --------------- |
| 1.0     | 2025-01-28 | Claude Code Assistant | Initial version |
