# ADR-0001: Microservices Architecture with Fastify

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

- [x] Create service template with Fastify setup
- [x] Implement BFF service with aggregation logic
- [x] Set up service mesh with Istio
- [x] Create shared libraries for common functionality
- [x] 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

- [Microservices.io patterns](https://microservices.io/patterns/)
- [Fastify documentation](https://fastify.dev/)
- [Backend-for-Frontend pattern](https://samnewman.io/patterns/architectural/bff/)
- Internal service template repository
- Kubernetes deployment guides

---

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