# ADR-0001: Microservices Architecture with Fastify

**Date**: 2025-09-14  
**Status**: Accepted  
**Deciders**: Architecture Team

## Context

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

- Independent deployment and scaling of components
- Team autonomy for parallel development
- High availability and fault isolation
- Sub-second response times for chat
- Integration with multiple AI providers

## Decision

Adopt a **microservices architecture** using **Fastify** as the web framework
with a **Backend-for-Frontend (BFF)** pattern.

### Key Components

- Individual services: auth, content, conversation, ai, media, notification,
  moderation
- BFF service for client aggregation
- Istio service mesh for inter-service communication
- Event-driven communication for async operations

## Rationale

### Why Microservices

- Enables independent scaling (AI vs. user management)
- Supports technology diversity where needed
- Provides fault isolation
- Matches Kubernetes deployment target

### Why Fastify

- Superior performance vs Express.js
- Built-in schema validation
- Strong TypeScript support
- Good observability hooks

### Why BFF

- Different clients need different data shapes
- Reduces client-server round trips
- Centralizes cross-cutting concerns

## Alternatives Considered

1. **Monolith**: Rejected due to scaling requirements
2. **Express.js**: Rejected for performance reasons
3. **GraphQL Federation**: Rejected due to caching complexity

## Consequences

### Positive

- Better scalability and resilience
- Team autonomy
- Technology flexibility

### Negative

- Distributed system complexity
- Network latency between services
- More complex debugging

### Mitigations

- Comprehensive distributed tracing
- Circuit breakers and retries
- Service mesh for reliability

## Related

- [Architecture Documentation](../architecture.md)
- [Original ADR in docs/](../../docs/adr/adr-0001-microservices-architecture.md)
