Eve library

ADR-0001: Fastify-based Microservices Architecture

ADR

Revision 1

On this page

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

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#

Internal Resources#


Revision History#

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