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