docs/ARCHITECTURE.md

# 🏛️ Chronos2 Server - Architecture Documentation

**Version**: 3.0.0  
**Date**: 2025-11-09  
**Author**: Claude AI  
**Status**: Production Ready

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Architecture Principles](#architecture-principles)
3. [System Architecture](#system-architecture)
4. [Layer Details](#layer-details)
5. [Design Patterns](#design-patterns)
6. [Data Flow](#data-flow)
7. [Component Diagrams](#component-diagrams)
8. [SOLID Principles](#solid-principles)
9. [Testing Strategy](#testing-strategy)
10. [Deployment Architecture](#deployment-architecture)

---

## 🎯 Overview

Chronos2 Server is a **time series forecasting API** powered by Amazon's Chronos-2 model. The system follows **Clean Architecture** principles with strict layer separation and **SOLID** design principles.

### Key Features

- ✅ **Probabilistic forecasting** with quantile predictions
- ✅ **Anomaly detection** using forecast bounds
- ✅ **Backtesting** for model evaluation
- ✅ **Multi-series forecasting** support
- ✅ **Excel integration** via Office Add-in
- ✅ **REST API** with OpenAPI documentation

### Technology Stack

**Backend:**
- FastAPI (Python 3.10+)
- Chronos-2 (Amazon ML model)
- Pandas (Data manipulation)
- Pydantic (Data validation)

**Frontend:**
- Office.js (Excel Add-in)
- Vanilla JavaScript (ES6+)
- HTML5/CSS3

**Testing:**
- pytest (Unit & Integration tests)
- pytest-cov (Coverage reports)
- FastAPI TestClient (API testing)

**Deployment:**
- Docker (Containerization)
- HuggingFace Spaces (Hosting)

---

## 🏗️ Architecture Principles

### Clean Architecture

The system follows **Clean Architecture** (Uncle Bob) with 4 distinct layers:

```
┌─────────────────────────────────────────────────────────┐
│                   Presentation Layer                     │
│  (API Routes, Controllers, Excel UI)                     │
└──────────────────┬──────────────────────────────────────┘
                   │ Depends on ↓
┌──────────────────▼──────────────────────────────────────┐
│                  Application Layer                       │
│  (Use Cases, DTOs, Mappers)                             │
└──────────────────┬──────────────────────────────────────┘
                   │ Depends on ↓
┌──────────────────▼──────────────────────────────────────┐
│                    Domain Layer                          │
│  (Business Logic, Models, Services, Interfaces)          │
└──────────────────┬──────────────────────────────────────┘
                   │ Depends on ↓
┌──────────────────▼──────────────────────────────────────┐
│                 Infrastructure Layer                     │
│  (External Services, ML Models, Config, DB)              │
└─────────────────────────────────────────────────────────┘
```

**Dependency Rule**: Dependencies point **inward** only. Inner layers know nothing about outer layers.

### Design Goals

1. **Maintainability**: Easy to understand and modify
2. **Testability**: Components can be tested in isolation
3. **Scalability**: Easy to add new features
4. **Flexibility**: Easy to swap implementations
5. **Reliability**: Robust error handling

---

## 🎨 System Architecture

### High-Level Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                          │
│  ┌────────────────────┐         ┌────────────────────┐       │
│  │   Excel Add-in     │         │   REST Clients     │       │
│  │   (Office.js)      │         │   (curl, Postman)  │       │
│  └────────┬───────────┘         └────────┬───────────┘       │
└───────────┼──────────────────────────────┼───────────────────┘
            │                              │
            └──────────────┬───────────────┘
                           │ HTTP/HTTPS
            ┌──────────────▼──────────────┐
            │       FastAPI Server         │
            │    (API Gateway/Router)      │
            └──────────────┬──────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        │                                     │
┌───────▼────────┐                   ┌────────▼────────┐
│  API Routes    │                   │  Static Files   │
│  /forecast     │                   │  (Excel UI)     │
│  /anomaly      │                   └─────────────────┘
│  /backtest     │
│  /health       │
└───────┬────────┘
        │
        │ Dependency Injection
        │
┌───────▼────────────────────────────────────────┐
│           APPLICATION LAYER                     │
│  ┌──────────────┐  ┌──────────────┐           │
│  │  Use Cases   │  │    Mappers   │           │
│  │  (Business   │  │  (DTO ↔      │           │
│  │  Workflows)  │  │   Domain)    │           │
│  └──────┬───────┘  └──────────────┘           │
└─────────┼──────────────────────────────────────┘
          │
┌─────────▼──────────────────────────────────────┐
│            DOMAIN LAYER                         │
│  ┌──────────────┐  ┌──────────────┐           │
│  │   Services   │  │    Models    │           │
│  │  - Forecast  │  │  - TimeSeries│           │
│  │  - Anomaly   │  │  - Config    │           │
│  │  - Backtest  │  │  - Result    │           │
│  └──────┬───────┘  └──────────────┘           │
│         │                                       │
│  ┌──────▼───────────────────┐                 │
│  │      Interfaces          │                 │
│  │  - IForecastModel        │                 │
│  │  - IDataTransformer      │                 │
│  └──────────────────────────┘                 │
└────────────────────────────────────────────────┘
          │
┌─────────▼──────────────────────────────────────┐
│         INFRASTRUCTURE LAYER                    │
│  ┌──────────────┐  ┌──────────────┐           │
│  │  ML Models   │  │    Config    │           │
│  │  - Chronos2  │  │  - Settings  │           │
│  │  - Factory   │  │  - Logger    │           │
│  └──────────────┘  └──────────────┘           │
│  ┌──────────────┐  ┌──────────────┐           │
│  │  Transformers│  │  Generators  │           │
│  │  - DataFrame │  │  - Timestamp │           │
│  │  - Builder   │  │              │           │
│  └──────────────┘  └──────────────┘           │
└────────────────────────────────────────────────┘
```

---

## 📦 Layer Details

### 1. Presentation Layer (API)

**Location**: `app/api/`

**Responsibilities**:
- HTTP request/response handling
- Input validation (Pydantic)
- Error handling and formatting
- API documentation (OpenAPI)
- CORS middleware

**Components**:
```
app/api/
├── dependencies.py       # Dependency injection setup
├── routes/
│   ├── health.py         # Health check endpoints
│   ├── forecast.py       # Forecasting endpoints
│   ├── anomaly.py        # Anomaly detection endpoints
│   └── backtest.py       # Backtesting endpoints
└── middleware/
    └── cors.py           # CORS configuration
```

**Example Route**:
```python
@router.post("/forecast/univariate")
async def forecast_univariate(
    request: ForecastUnivariateRequest,
    use_case: ForecastUseCase = Depends(get_forecast_use_case)
) -> ForecastUnivariateResponse:
    """Univariate forecasting endpoint"""
    # 1. Validate request (Pydantic)
    # 2. Execute use case
    # 3. Return response
    result = use_case.execute(request)
    return result
```

**Key Principles**:
- ✅ **SRP**: Routes only handle HTTP concerns
- ✅ **DIP**: Depends on use cases (abstractions)
- ✅ No business logic in routes

---

### 2. Application Layer

**Location**: `app/application/`

**Responsibilities**:
- Orchestrate business workflows (Use Cases)
- Transform between API and Domain models (Mappers)
- Coordinate multiple domain services
- Transaction boundaries

**Components**:
```
app/application/
├── dtos/                 # Data Transfer Objects
│   ├── forecast_dtos.py  # Forecast DTOs
│   ├── anomaly_dtos.py   # Anomaly DTOs
│   └── backtest_dtos.py  # Backtest DTOs
├── use_cases/            # Business workflows
│   ├── forecast_use_case.py
│   ├── anomaly_use_case.py
│   └── backtest_use_case.py
└── mappers/              # DTO ↔ Domain mapping
    ├── forecast_mapper.py
    ├── anomaly_mapper.py
    └── backtest_mapper.py
```

**Example Use Case**:
```python
class ForecastUnivariateUseCase:
    """Orchestrates univariate forecasting workflow"""
    
    def __init__(self, forecast_service: ForecastService):
        self.forecast_service = forecast_service
    
    def execute(self, input_dto: ForecastInputDTO) -> ForecastOutputDTO:
        # 1. Validate DTO
        input_dto.validate()
        
        # 2. Map DTO → Domain
        series = mapper.to_time_series(input_dto)
        config = mapper.to_forecast_config(input_dto)
        
        # 3. Execute domain logic
        result = self.forecast_service.forecast_univariate(series, config)
        
        # 4. Map Domain → DTO
        output_dto = mapper.to_output_dto(result)
        
        return output_dto
```

**Key Principles**:
- ✅ **SRP**: Use cases orchestrate, don't implement logic
- ✅ **OCP**: New use cases without modifying existing
- ✅ **DIP**: Depends on domain interfaces

---

### 3. Domain Layer (Core)

**Location**: `app/domain/`

**Responsibilities**:
- Define business rules
- Implement core algorithms
- Define domain models (entities, value objects)
- Define interfaces (ports)

**Components**:
```
app/domain/
├── models/               # Domain models
│   ├── time_series.py    # TimeSeries entity
│   ├── forecast_config.py # ForecastConfig value object
│   ├── forecast_result.py # ForecastResult entity
│   └── anomaly.py        # Anomaly models
├── services/             # Business logic
│   ├── forecast_service.py
│   ├── anomaly_service.py
│   └── backtest_service.py
└── interfaces/           # Abstractions (ports)
    ├── forecast_model.py  # IForecastModel
    └── data_transformer.py # IDataTransformer
```

**Example Domain Service**:
```python
class ForecastService:
    """Domain service for forecasting logic"""
    
    def __init__(
        self,
        model: IForecastModel,  # Abstraction (DIP)
        transformer: IDataTransformer
    ):
        self.model = model
        self.transformer = transformer
    
    def forecast_univariate(
        self,
        series: TimeSeries,  # Domain model
        config: ForecastConfig
    ) -> ForecastResult:
        # 1. Validate domain rules
        if not series.validate():
            raise ValueError("Invalid time series")
        
        # 2. Transform to ML format
        context_df = self.transformer.build_context_df(
            series.values, series.timestamps
        )
        
        # 3. Call ML model
        pred_df = self.model.predict(
            context_df, 
            config.prediction_length,
            config.quantile_levels
        )
        
        # 4. Transform back to domain
        result = self.transformer.parse_prediction_result(pred_df)
        
        # 5. Return domain model
        return ForecastResult(**result)
```

**Key Principles**:
- ✅ **SRP**: Each service has one business responsibility
- ✅ **DIP**: Depends on interfaces, not implementations
- ✅ **ISP**: Small, focused interfaces
- ✅ No dependencies on outer layers

---

### 4. Infrastructure Layer

**Location**: `app/infrastructure/`

**Responsibilities**:
- Implement domain interfaces (adapters)
- External service integration (ML models, databases)
- Configuration management
- Logging, monitoring

**Components**:
```
app/infrastructure/
├── ml/                   # ML model implementations
│   ├── chronos_model.py  # Chronos2 adapter
│   └── model_factory.py  # Factory pattern
├── config/               # Configuration
│   └── settings.py       # Pydantic settings
└── persistence/          # Data persistence (future)
    └── cache.py          # Caching layer
```

**Example Infrastructure**:
```python
class ChronosModel(IForecastModel):
    """Adapter for Chronos-2 model (DIP)"""
    
    def __init__(self, model_id: str, device_map: str):
        self.pipeline = Chronos2Pipeline.from_pretrained(
            model_id, device_map=device_map
        )
    
    def predict(
        self,
        context_df: pd.DataFrame,
        prediction_length: int,
        quantile_levels: List[float]
    ) -> pd.DataFrame:
        """Implements IForecastModel interface"""
        return self.pipeline.predict_df(
            context_df,
            prediction_length=prediction_length,
            quantile_levels=quantile_levels
        )
```

**Factory Pattern**:
```python
class ModelFactory:
    """Factory for creating forecast models (OCP)"""
    
    _models = {
        "chronos2": ChronosModel,
        # Future: "prophet": ProphetModel,
        # Future: "arima": ARIMAModel,
    }
    
    @classmethod
    def create(cls, model_type: str, **kwargs) -> IForecastModel:
        """Create model instance"""
        if model_type not in cls._models:
            raise ValueError(f"Unknown model: {model_type}")
        
        model_class = cls._models[model_type]
        return model_class(**kwargs)
    
    @classmethod
    def register_model(cls, name: str, model_class: Type[IForecastModel]):
        """Register new model (OCP - extension)"""
        cls._models[name] = model_class
```

**Key Principles**:
- ✅ **DIP**: Implements domain interfaces
- ✅ **OCP**: Factory allows extension without modification
- ✅ **SRP**: Each adapter has one external responsibility

---

## 🎨 Design Patterns

### 1. Dependency Injection (DI)

**Implementation**: FastAPI `Depends()`

```python
# Define dependencies
def get_forecast_model() -> IForecastModel:
    """Singleton model instance"""
    return ModelFactory.create("chronos2", model_id=settings.model_id)

def get_forecast_service(
    model: IForecastModel = Depends(get_forecast_model),
    transformer: IDataTransformer = Depends(get_data_transformer)
) -> ForecastService:
    """Inject dependencies"""
    return ForecastService(model=model, transformer=transformer)

# Use in routes
@router.post("/forecast/univariate")
async def forecast(
    use_case: ForecastUseCase = Depends(get_forecast_use_case)
):
    return use_case.execute(...)
```

**Benefits**:
- ✅ Loose coupling
- ✅ Easy testing (mock dependencies)
- ✅ Configurable at runtime

---

### 2. Factory Pattern

**Implementation**: `ModelFactory`

```python
# Create model
model = ModelFactory.create("chronos2", model_id="amazon/chronos-2")

# Extend without modifying factory
ModelFactory.register_model("custom", CustomModel)
model = ModelFactory.create("custom", ...)
```

**Benefits**:
- ✅ OCP compliance (Open for extension)
- ✅ Centralized model creation
- ✅ Easy to add new models

---

### 3. Repository Pattern (Implicit)

**Implementation**: `DataFrameBuilder`

```python
class DataFrameBuilder(IDataTransformer):
    """Repository-like interface for data"""
    
    def build_context_df(self, values, timestamps):
        """Build context from raw data"""
        ...
    
    def parse_prediction_result(self, pred_df):
        """Parse model output"""
        ...
```

**Benefits**:
- ✅ Data access abstraction
- ✅ Easy to swap data sources
- ✅ Testable with mocks

---

### 4. Strategy Pattern (Implicit)

**Implementation**: `IForecastModel` interface

```python
# Different strategies
model1 = ChronosModel(...)
model2 = ProphetModel(...)  # Future

# Same interface
service = ForecastService(model=model1)  # ✅
service = ForecastService(model=model2)  # ✅
```

**Benefits**:
- ✅ LSP compliance (Liskov Substitution)
- ✅ Interchangeable implementations
- ✅ Easy A/B testing

---

## 🔄 Data Flow

### Forecast Request Flow

```
1. Client Request
   ↓
   POST /forecast/univariate
   Body: {"values": [100, 102, 105], "prediction_length": 3}

2. API Layer (Route)
   ↓
   - Validate request (Pydantic)
   - Inject use case
   ↓
   ForecastUnivariateUseCase

3. Application Layer (Use Case)
   ↓
   - Validate DTO
   - Map DTO → Domain models
   ↓
   ForecastService

4. Domain Layer (Service)
   ↓
   - Validate business rules
   - Call transformer
   ↓
   DataFrameBuilder.build_context_df()
   
5. Infrastructure Layer (Transformer)
   ↓
   - Build DataFrame
   ↓
   Back to Domain (Service)
   ↓
   - Call model
   ↓
   IForecastModel.predict()

6. Infrastructure Layer (Model)
   ↓
   - Chronos2Pipeline.predict_df()
   ↓
   Back to Domain (Service)
   ↓
   - Parse result
   ↓
   DataFrameBuilder.parse_prediction_result()
   
7. Domain Layer (Service)
   ↓
   - Create ForecastResult (domain model)
   ↓
   Back to Application (Use Case)

8. Application Layer (Use Case)
   ↓
   - Map Domain → DTO
   ↓
   Back to API (Route)

9. API Layer (Route)
   ↓
   - Serialize response (Pydantic)
   ↓
   200 OK
   Body: {"timestamps": [...], "median": [...], "quantiles": {...}}

10. Client Response
```

**Key Observations**:
- ✅ Clear layer boundaries
- ✅ Each layer has specific responsibility
- ✅ Dependencies point inward
- ✅ Domain models never leak to API

---

## 📊 Component Diagrams

### Forecasting Component Interaction

```
┌─────────────────────────────────────────────────────────┐
│                    CLIENT                                │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP POST
          ┌──────────▼──────────┐
          │  ForecastController │ (API Layer)
          └──────────┬──────────┘
                     │ execute()
          ┌──────────▼──────────────┐
          │  ForecastUseCase        │ (Application Layer)
          └──────────┬──────────────┘
                     │ forecast_univariate()
          ┌──────────▼──────────────┐
          │  ForecastService        │ (Domain Layer)
          │  ┌──────────────────┐   │
          │  │ TimeSeries       │   │
          │  │ ForecastConfig   │   │
          │  │ ForecastResult   │   │
          │  └──────────────────┘   │
          └──────┬──────────┬───────┘
                 │          │
    build_df()   │          │  predict()
                 │          │
      ┌──────────▼────┐  ┌─▼──────────────┐
      │ DataFrame      │  │ ChronosModel   │ (Infrastructure)
      │ Builder        │  │ (IForecastModel)│
      └────────────────┘  └────────────────┘
                                │
                          ┌─────▼──────┐
                          │ Chronos2   │
                          │ Pipeline   │
                          └────────────┘
```

---

## 🎯 SOLID Principles

### Single Responsibility Principle (SRP) ✅

**Each class has ONE reason to change**

```python
# ✅ Good: Separate responsibilities
class ForecastService:
    """Only forecasting logic"""
    def forecast_univariate(self, series, config):
        ...

class DataFrameBuilder:
    """Only data transformation"""
    def build_context_df(self, values):
        ...

class ChronosModel:
    """Only ML inference"""
    def predict(self, context_df):
        ...
```

**Violations to avoid**:
```python
# ❌ Bad: Multiple responsibilities
class ForecastServiceBad:
    def forecast(self, values):
        # Data transformation (should be separate)
        df = self._build_dataframe(values)
        # ML inference (should be separate)
        pred = self._call_model(df)
        # HTTP response (should be in API layer)
        return {"status": 200, "data": pred}
```

---

### Open/Closed Principle (OCP) ✅

**Open for extension, closed for modification**

```python
# ✅ Good: Extension without modification
class ModelFactory:
    _models = {"chronos2": ChronosModel}
    
    @classmethod
    def register_model(cls, name, model_class):
        """Extend by registering new models"""
        cls._models[name] = model_class

# Add new model without modifying factory
ModelFactory.register_model("prophet", ProphetModel)
```

**Example extension**:
```python
# New model type (no changes to existing code)
class ProphetModel(IForecastModel):
    def predict(self, context_df, prediction_length, quantile_levels):
        # Prophet-specific implementation
        ...

# Register and use
ModelFactory.register_model("prophet", ProphetModel)
model = ModelFactory.create("prophet")
service = ForecastService(model=model)  # Works!
```

---

### Liskov Substitution Principle (LSP) ✅

**Subtypes must be substitutable for their base types**

```python
# ✅ Good: Any IForecastModel works
def forecast_with_any_model(model: IForecastModel):
    result = model.predict(df, 7, [0.5])
    # Works with ChronosModel, ProphetModel, etc.
    return result

# All implementations honor the contract
model1 = ChronosModel(...)
model2 = ProphetModel(...)  # Future

forecast_with_any_model(model1)  # ✅ Works
forecast_with_any_model(model2)  # ✅ Works
```

---

### Interface Segregation Principle (ISP) ✅

**Clients shouldn't depend on methods they don't use**

```python
# ✅ Good: Small, focused interfaces
class IForecastModel(ABC):
    """Only forecasting methods"""
    @abstractmethod
    def predict(self, context_df, prediction_length, quantile_levels):
        pass
    
    @abstractmethod
    def get_model_info(self):
        pass

class IDataTransformer(ABC):
    """Only transformation methods"""
    @abstractmethod
    def build_context_df(self, values):
        pass
    
    @abstractmethod
    def parse_prediction_result(self, pred_df):
        pass
```

**Violations to avoid**:
```python
# ❌ Bad: Fat interface
class IForecastModelBad(ABC):
    @abstractmethod
    def predict(self, ...): pass
    
    @abstractmethod
    def build_dataframe(self, ...): pass  # Should be separate
    
    @abstractmethod
    def validate_input(self, ...): pass   # Should be separate
    
    @abstractmethod
    def format_response(self, ...): pass  # Should be separate
```

---

### Dependency Inversion Principle (DIP) ✅

**Depend on abstractions, not concretions**

```python
# ✅ Good: Depends on abstraction
class ForecastService:
    def __init__(
        self,
        model: IForecastModel,  # Abstract interface
        transformer: IDataTransformer  # Abstract interface
    ):
        self.model = model
        self.transformer = transformer
```

**Violations to avoid**:
```python
# ❌ Bad: Depends on concrete implementation
class ForecastServiceBad:
    def __init__(self):
        # Coupled to Chronos2Pipeline directly
        self.model = Chronos2Pipeline.from_pretrained(...)
        # Coupled to DataFrameBuilder directly
        self.transformer = DataFrameBuilder()
```

---

## 🧪 Testing Strategy

### Test Pyramid

```
         ╱╲
        ╱  ╲
       ╱ E2E ╲             10 tests (Integration)
      ╱────────╲
     ╱          ╲
    ╱ Integration╲         25 tests (API, Services)
   ╱──────────────╲
  ╱                ╲
 ╱   Unit Tests     ╲     45 tests (Fast, Isolated)
╱────────────────────╲
```

### Unit Tests (45+)

**Focus**: Individual components in isolation

**Tools**: pytest, unittest.mock

**Example**:
```python
def test_forecast_service(mock_model, mock_transformer):
    """Test service logic with mocks"""
    service = ForecastService(mock_model, mock_transformer)
    
    series = TimeSeries(values=[100, 102, 105])
    config = ForecastConfig(prediction_length=3)
    
    result = service.forecast_univariate(series, config)
    
    assert len(result.timestamps) == 3
    mock_model.predict.assert_called_once()
```

### Integration Tests (25+)

**Focus**: Multiple components working together

**Tools**: FastAPI TestClient

**Example**:
```python
@patch('app.infrastructure.ml.chronos_model.Chronos2Pipeline')
def test_forecast_endpoint_e2e(mock_pipeline):
    """Test complete API flow"""
    mock_pipeline.predict_df.return_value = sample_df
    
    response = client.post("/forecast/univariate", json={
        "values": [100, 102, 105],
        "prediction_length": 3
    })
    
    assert response.status_code == 200
    data = response.json()
    assert "timestamps" in data
```

### Test Coverage

- **Domain Layer**: 80%
- **Application Layer**: 70%
- **Infrastructure Layer**: 85%
- **API Layer**: 90%
- **Overall**: ~80%

---

## 🚀 Deployment Architecture

### Container Architecture

```
┌─────────────────────────────────────────────────┐
│              Docker Container                    │
│  ┌───────────────────────────────────────────┐  │
│  │         FastAPI Application               │  │
│  │  ┌─────────────┐  ┌──────────────┐       │  │
│  │  │  API Server │  │  Static Files│       │  │
│  │  │  (Port 8000)│  │  (Excel UI)  │       │  │
│  │  └─────────────┘  └──────────────┘       │  │
│  └───────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────┐  │
│  │         Chronos-2 Model                   │  │
│  │  (amazon/chronos-2)                       │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                      │
            ┌─────────▼─────────┐
            │  HuggingFace      │
            │  Spaces           │
            │  (Public URL)     │
            └───────────────────┘
```

### Environment Configuration

**Production**:
- HuggingFace Spaces
- CPU inference (free tier)
- Public HTTPS endpoint

**Development**:
- Local Docker
- Hot reload
- Debug mode

**Testing**:
- CI/CD pipeline
- Automated tests
- Coverage reports

---

## 📈 Performance Considerations

### Model Loading

```python
# Singleton pattern for model (loaded once)
_model_instance = None

def get_forecast_model():
    global _model_instance
    if _model_instance is None:
        _model_instance = ModelFactory.create("chronos2")
    return _model_instance
```

### Caching Strategy (Future)

```python
# Redis cache for repeated forecasts
@cache(ttl=3600)
def forecast_univariate(values, prediction_length):
    ...
```

### Async Processing (Future)

```python
# Background tasks for long forecasts
@router.post("/forecast/async")
async def forecast_async(background_tasks: BackgroundTasks):
    background_tasks.add_task(long_forecast)
    return {"task_id": "..."}
```

---

## 🔐 Security Considerations

### Input Validation

- ✅ Pydantic validation at API layer
- ✅ Domain validation in services
- ✅ Type hints throughout

### Error Handling

- ✅ Structured error responses
- ✅ No sensitive data in errors
- ✅ Logging for debugging

### CORS Configuration

```python
# Configurable CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_origins,
    allow_methods=["GET", "POST"],
    allow_headers=["*"]
)
```

---

## 📚 References

### Architecture Patterns

- **Clean Architecture**: Robert C. Martin
- **Domain-Driven Design**: Eric Evans
- **SOLID Principles**: Robert C. Martin

### Frameworks & Libraries

- **FastAPI**: https://fastapi.tiangolo.com/
- **Chronos**: https://github.com/amazon-science/chronos-forecasting
- **Pydantic**: https://docs.pydantic.dev/

---

## 🎓 Learning Resources

### For New Developers

1. Read `DEVELOPMENT.md` for setup instructions
2. Review `API.md` for endpoint documentation
3. Study test examples in `tests/`
4. Start with simple features (add endpoint)

### Architecture Books

- "Clean Architecture" by Robert C. Martin
- "Domain-Driven Design" by Eric Evans
- "Patterns of Enterprise Application Architecture" by Martin Fowler

---

**Last Updated**: 2025-11-09  
**Version**: 3.0.0  
**Maintainer**: Claude AI