docs/ARCHITECTURE.md

# Architecture Documentation

## Overview

Writing Studio follows a layered architecture pattern with clear separation of concerns:

```
┌─────────────────────────────────────┐
│     Presentation Layer (Gradio)     │
├─────────────────────────────────────┤
│      Core Logic (Analyzer)          │
├─────────────────────────────────────┤
│       Service Layer                 │
│  ┌──────────┬──────────┬─────────┐ │
│  │  Model   │  Rubric  │  Diff   │ │
│  │ Service  │ Service  │ Service │ │
│  └──────────┴──────────┴─────────┘ │
├─────────────────────────────────────┤
│        Utilities Layer              │
│  ┌──────────┬──────────┬─────────┐ │
│  │ Logging  │Validation│ Metrics │ │
│  └──────────┴──────────┴─────────┘ │
└─────────────────────────────────────┘
```

## Components

### Core Layer

#### Analyzer (`core/analyzer.py`)
- Orchestrates all analysis operations
- Manages service coordination
- Handles metrics collection
- Implements error handling strategy

#### Configuration (`core/config.py`)
- Pydantic-based settings management
- Environment variable loading
- Validation of configuration values

#### Exceptions (`core/exceptions.py`)
- Custom exception hierarchy
- Structured error information

### Service Layer

#### Model Service (`services/model_service.py`)
- Model lifecycle management
- Text generation
- Result caching
- HuggingFace model integration

#### Rubric Service (`services/rubric_service.py`)
- Writing analysis algorithms
- Multi-criteria scoring
- Feedback generation

#### Diff Service (`services/diff_service.py`)
- Text comparison
- HTML diff generation
- Similarity computation

#### Prompt Service (`services/prompt_service.py`)
- Template management
- Prompt pack system
- Dynamic prompt generation

### Utilities Layer

#### Logging (`utils/logging.py`)
- Structured JSON logging
- Log rotation
- Multiple output handlers

#### Validation (`utils/validation.py`)
- Input sanitization
- Parameter validation
- Security checks

#### Metrics (`utils/metrics.py`)
- Prometheus metric definitions
- Counter, Gauge, Histogram metrics

#### Monitoring (`utils/monitoring.py`)
- Health checks
- Readiness probes
- Liveness probes

## Data Flow

```
User Input → Validation → Analyzer
                ↓
        Model Service (Generation)
                ↓
        Rubric Service (Analysis)
                ↓
        Diff Service (Comparison)
                ↓
        Results → Gradio UI
```

## Design Patterns

### Singleton Pattern
- Model Service: Single instance per application
- Configuration: Global settings object

### Service Layer Pattern
- Clear separation between business logic and services
- Each service has a single responsibility

### Dependency Injection
- Services injected into Analyzer
- Allows for easy testing and mocking

### Error Handling Strategy
- Try-except at boundaries
- Structured exception hierarchy
- Logging at each level

## Scalability Considerations

### Horizontal Scaling
- Stateless design allows multiple instances
- Model caching at instance level
- Metrics aggregation via Prometheus

### Vertical Scaling
- Model loading optimized with caching
- Memory-efficient text processing
- Lazy initialization of services

### Performance Optimizations
- LRU cache for service instances
- Generation result caching
- Efficient string operations

## Security Architecture

### Input Validation
- All user inputs sanitized
- Maximum length enforcement
- Path traversal prevention

### Rate Limiting
- Configurable per-minute limits
- Per-user tracking (when auth enabled)

### Authentication (Optional)
- Can be enabled via configuration
- Session management
- Secure token handling

## Monitoring Strategy

### Metrics Collection
- Request counts and durations
- Error rates and types
- Cache hit rates
- Model loading times

### Health Checks
- Liveness: Application running
- Readiness: Ready to serve requests
- Health: All components operational

### Logging Strategy
- Structured JSON logs
- Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
- Contextual information in each log

## Testing Strategy

### Unit Tests
- Individual service testing
- Validation logic testing
- Mock external dependencies

### Integration Tests
- Service interaction testing
- End-to-end analysis flow
- Error handling paths

### Performance Tests
- Load testing with locust
- Memory profiling
- Model loading benchmarks

## Deployment Architecture

### Docker Container
```
┌──────────────────────────────────┐
│  Application Container           │
│  ┌────────────────────────────┐  │
│  │  Gradio Server (7860)      │  │
│  ├────────────────────────────┤  │
│  │  Metrics Server (8000)     │  │
│  └────────────────────────────┘  │
└──────────────────────────────────┘
         │              │
         ↓              ↓
    User Traffic   Prometheus
```

### Production Stack
```
┌─────────┐     ┌──────────┐     ┌─────────┐
│ Nginx   │────→│ Writing  │────→│ Prom    │
│ Reverse │     │ Studio   │     │ etheus  │
│ Proxy   │     │ (N inst) │     └─────────┘
└─────────┘     └──────────┘           │
                                       ↓
                                  ┌─────────┐
                                  │ Grafana │
                                  └─────────┘
```

## Future Enhancements

### Planned Improvements
1. Database integration for persistent storage
2. User authentication and authorization
3. Multi-model support with dynamic switching
4. Asynchronous processing for large texts
5. WebSocket support for real-time updates
6. API endpoints alongside Gradio UI
7. Custom rubric creation interface
8. Export functionality (PDF, DOCX)