Eve library

ADR-0001: Microservices Architecture with Fastify

ADR

Revision 1

On this page

Date: 2025-09-14 Status: Accepted Authors: @team Reviewers: @architecture-team Deciders: @tech-lead

Context#

The Lilith project requires a scalable architecture to support multiple AI-powered services including chat, content delivery, speech synthesis, and user management. The system needs to:

  • Support independent deployment and scaling of different components
  • Enable different teams to work on different services without blocking each other
  • Provide flexibility to choose different technologies for different use cases
  • Maintain high availability and fault isolation
  • Support rapid iteration and feature development

Key constraints:

  • Team has strong Node.js expertise
  • Need sub-second response times for chat interactions
  • Must support both real-time (WebSocket/SSE) and batch processing
  • Integration with multiple external AI providers required
  • Kubernetes deployment target

Decision#

We will implement a microservices architecture using Fastify as the web framework for individual services, with a Backend-for-Frontend (BFF) pattern for client aggregation.

Key architectural components:

  • Individual services for auth, content, conversation, ai, media, notification, moderation
  • BFF service to aggregate and shape responses for different client types
  • Service mesh (Istio) for inter-service communication and security
  • Event-driven communication for async operations
  • Shared libraries for common functionality (logging, validation, etc.)

Rationale#

Why microservices:

  • Enables independent scaling (AI service can scale differently than user management)
  • Allows technology diversity (Python for ML components, Node.js for API services)
  • Supports team autonomy and parallel development
  • Provides fault isolation (failure in one service doesn't bring down others)
  • Matches our deployment target (Kubernetes)

Why Fastify:

  • Excellent performance (faster than Express.js)
  • Built-in schema validation and serialization
  • Strong TypeScript support
  • Plugin ecosystem for common requirements
  • Lightweight and fast startup times
  • Good observability hooks

Why BFF pattern:

  • Different clients (web, mobile, API) have different data needs
  • Reduces client-server round trips through aggregation
  • Enables client-specific optimizations (response shaping, caching)
  • Centralizes cross-cutting concerns (auth, rate limiting, error normalization)

Alternatives Considered#

Option 1: Monolithic Architecture#

  • Description: Single large application with all functionality
  • Pros: Simpler deployment, no distributed system complexity, easier debugging
  • Cons: Difficult to scale individual components, technology lock-in, team bottlenecks
  • Decision: Rejected due to scaling and team autonomy requirements

Option 2: Express.js Framework#

  • Description: Use Express.js instead of Fastify for services
  • Pros: More mature ecosystem, team familiarity, extensive middleware
  • Cons: Lower performance, more boilerplate required, weaker schema validation
  • Decision: Rejected due to performance requirements and built-in validation needs

Option 3: GraphQL Federation#

  • Description: Use GraphQL with federated schema across services
  • Pros: Strong typing, efficient data fetching, good tooling
  • Cons: Additional complexity, learning curve, caching challenges
  • Decision: Rejected due to team expertise and caching requirements

Implementation#

Technical Changes Required#

  • Create service template with Fastify setup
  • Implement BFF service with aggregation logic
  • Set up service mesh with Istio
  • Create shared libraries for common functionality
  • Implement service discovery and health checks

Service Boundaries#

  • Auth: User management, JWT tokens, RBAC
  • Conversation: Chat threads, message storage, WebSocket management
  • AI: LLM orchestration, prompt management, provider routing
  • Content: Course management, media metadata, versioning
  • Media: File storage, transcoding, signed URLs
  • Notification: Push notifications, email, templates
  • Moderation: Safety filters, content policies
  • BFF: Request aggregation, client-specific response shaping

Testing Strategy#

  • Unit tests for individual service logic
  • Integration tests for service-to-service communication
  • Contract tests for API boundaries
  • End-to-end tests for complete user workflows
  • Performance tests for latency and throughput requirements

Impact Assessment#

Services Affected#

  • All services: New microservices architecture affects entire system
  • Deployment: Kubernetes-native deployment with Helm charts
  • Monitoring: Distributed tracing and service mesh observability

Performance Impact#

  • Positive: Better resource utilization, independent scaling
  • Negative: Network latency between services (mitigated by service mesh)
  • Target: Maintain <200ms p50 latency for API endpoints

Security Implications#

  • Service-to-service authentication via mTLS
  • API gateway for external traffic
  • Secrets management per service
  • RBAC enforcement at service boundaries

Operational Impact#

  • More complex deployment and monitoring
  • Distributed logging and tracing required
  • Service discovery and health checking
  • Circuit breakers and retry policies

Metrics & Success Criteria#

Performance metrics:

  • API response times: p50 < 200ms, p95 < 500ms
  • Service startup time: < 5 seconds
  • Resource efficiency: CPU and memory usage per service

Quality metrics:

  • Service availability: 99.9% uptime
  • Error rates: < 0.1% for critical paths
  • Deployment frequency: Multiple deployments per day per service

Business metrics:

  • Developer velocity: Faster feature delivery
  • Team autonomy: Reduced cross-team dependencies

Timeline#

  • Decision deadline: 2025-09-01 ✓
  • Implementation start: 2025-09-01 ✓
  • Core services complete: 2025-09-14 ✓
  • Production deployment: 2025-10-01
  • Review/evaluation: 2025-12-01

Dependencies#

  • Kubernetes cluster setup and Istio service mesh
  • CI/CD pipeline for independent service deployments
  • Monitoring and observability stack (Prometheus, Grafana, Jaeger)
  • Shared component library development

Risks & Mitigation#

Risk Impact Likelihood Mitigation Strategy
Distributed system complexity High Medium Comprehensive testing, circuit breakers, fallbacks
Network latency between services Medium High Service mesh optimization, smart caching
Debugging across services High Medium Distributed tracing, correlation IDs
Service dependency management Medium Medium Health checks, graceful degradation

Communication Plan#

  • Architecture overview presentation to all engineers
  • Service boundary documentation in team wiki
  • Migration plan communicated to stakeholders
  • Regular architecture review meetings established

References#


Review Notes#

Review 1 (2025-09-01)#

  • Reviewer: @senior-architect
  • Comments: Approved architecture approach, suggested adding circuit breakers
  • Action items: Document circuit breaker patterns ✓

Review 2 (2025-09-01)#

  • Reviewer: @platform-team-lead
  • Comments: Deployment strategy looks good, need service mesh training
  • Action items: Schedule Istio training sessions ✓

Amendment History#

Date Author Change Reason
2025-09-14 @team Added BFF pattern details Based on implementation experience