sema-api / docs /ARCHITECTURE.md
kamau1's picture
update: Fastapi codebase structure with api endpoints
a7d24e3
# Sema Translation API - Architecture Overview
## πŸ—οΈ Project Structure
This FastAPI application follows industry best practices for maintainable, scalable APIs:
### Directory Structure
```
app/
β”œβ”€β”€ main.py # Application entry point & FastAPI instance
β”œβ”€β”€ api/v1/endpoints.py # API route handlers (versioned)
β”œβ”€β”€ core/ # Core configuration & setup
β”‚ β”œβ”€β”€ config.py # Settings management
β”‚ β”œβ”€β”€ logging.py # Structured logging setup
β”‚ └── metrics.py # Prometheus metrics definitions
β”œβ”€β”€ middleware/ # Custom middleware
β”‚ └── request_middleware.py # Request tracking & metrics
β”œβ”€β”€ models/schemas.py # Pydantic data models
β”œβ”€β”€ services/translation.py # Business logic & model management
└── utils/helpers.py # Utility functions
```
## πŸ”§ Design Principles
### 1. Separation of Concerns
- **API Layer**: Route definitions and request/response handling
- **Service Layer**: Business logic and model operations
- **Core Layer**: Configuration, logging, and metrics
- **Models Layer**: Data validation and serialization
### 2. Dependency Injection
- Settings injected via Pydantic Settings
- Services accessed through proper imports
- Middleware applied declaratively
### 3. Configuration Management
- Environment-based configuration
- Type-safe settings with Pydantic
- Centralized configuration in `core/config.py`
### 4. Observability
- Structured JSON logging with structlog
- Prometheus metrics for monitoring
- Request tracking with unique IDs
- Health check endpoints
## πŸš€ Key Features
### Enterprise-Grade Features
- **Rate Limiting**: IP-based rate limiting with SlowAPI
- **Request Tracking**: Unique request IDs for debugging
- **Metrics Collection**: Prometheus metrics for monitoring
- **Structured Logging**: JSON logs for easy parsing
- **Health Checks**: Comprehensive health monitoring
### API Design
- **Versioned Routes**: `/api/v1/` for future compatibility
- **OpenAPI Documentation**: Auto-generated Swagger UI
- **Type Safety**: Full Pydantic validation
- **Error Handling**: Graceful error responses
### Performance
- **Async/Await**: Full asynchronous request handling
- **Model Caching**: Models loaded once at startup
- **Efficient Translation**: CTranslate2 optimization
## πŸ”’ Security (Testing Phase)
### Current State
- Authentication **removed** for testing phase
- Rate limiting active (60 req/min per IP)
- Input validation with Pydantic
- CORS configured for development
### Future Integration Points
- Supabase authentication ready
- User tracking infrastructure in place
- Usage analytics for billing prepared
## πŸ“Š Monitoring & Observability
### Metrics Available
- Request count by endpoint and status
- Request duration histograms
- Translation count by language pair
- Character count tracking
- Error count by type
### Logging
- Structured JSON logs
- Request/response tracking
- Translation event logging
- Error logging with context
## πŸ”„ Development Workflow
### Local Development
```bash
cd backend/sema-api
pip install -r requirements.txt
uvicorn app.main:app --reload
```
### Docker Development
```bash
docker build -t sema-api .
docker run -p 8000:8000 sema-api
```
### Testing
- Health check: `GET /health`
- Documentation: `GET /docs`
- Metrics: `GET /metrics`
- Translation: `POST /translate`
## 🎯 Future Enhancements
### Authentication Integration
- Supabase JWT validation
- User-based rate limiting
- API key authentication
### Scaling Considerations
- Database integration for usage tracking
- Redis caching for performance
- Load balancer compatibility
- Horizontal scaling support
### Monitoring Enhancements
- Grafana dashboards
- Alerting rules
- Performance profiling
- Usage analytics
## πŸ“ Maintenance
### Code Organization Benefits
- **Testability**: Each component can be tested independently
- **Maintainability**: Clear separation of concerns
- **Scalability**: Easy to add new features and endpoints
- **Debugging**: Structured logging and request tracking
- **Documentation**: Self-documenting code structure
### Adding New Features
1. **New Endpoints**: Add to `api/v1/endpoints.py`
2. **Business Logic**: Add to appropriate service in `services/`
3. **Data Models**: Add to `models/schemas.py`
4. **Configuration**: Add to `core/config.py`
5. **Middleware**: Add to `middleware/`
This architecture provides a solid foundation for a production-ready translation API that can scale and evolve with your needs.