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)