# Architecture

This diagram provides a high-level overview of the Scorable system components and their relationships.

```mermaid
---
title: Scorable System Architecture
---
graph TB
    %% User-facing
    Users([Users])

    %% Frontend Layer
    Frontend["🐳 Frontend<br/>Next.js Application<br/>(Container)"]
    PublicAPI[Public API / SDK<br/>External Integration]

    %% API Layer
    API["🐳 API Server<br/>Main Backend<br/>(Container)"]

    %% Background Processing
    BackgroundProcessing["🐳 Background Processing<br/>Background Tasks<br/>(Container)"]

    %% AI/ML Services
    LLMProxy["🐳 LLM Proxy<br/>LiteLLM<br/>(Container)"]
    Evals["🐳 Evals Service<br/>(Container)"]

    %% Data Layer
    PostgreSQL[(PostgreSQL<br/>Database)]
    Redis[(Redis<br/>Cache & Queue)]

    %% Storage
    Storage[Object Storage]

    %% External Services
    LLMProviders[LLM Providers<br/>OpenAI, Anthropic, Google, Self-hosted]
    SAMLIdP[SAML Identity Provider<br/>Organization IdP]
    OrgMonitoring[Organization Systems<br/>Monitoring, Logging, SIEM]

    %% User Flow
    Users --> Frontend
    Users --> PublicAPI
    Frontend --> API
    PublicAPI --> API

    %% API Connections
    API --> PostgreSQL
    API --> Redis
    API --> Evals
    API --> Storage

    %% Background Processing
    BackgroundProcessing --> Redis
    BackgroundProcessing --> PostgreSQL

    %% AI Services
    Evals --> PostgreSQL
    Evals --> LLMProxy

    %% LLM Proxy to External
    LLMProxy --> LLMProviders

    %% Authentication Flow
    Users -.->|SAML Auth| SAMLIdP
    SAMLIdP -.-> API

    %% Observability
    API -.->|Logs/Metrics| OrgMonitoring
    BackgroundProcessing -.->|Logs/Metrics| OrgMonitoring
    Evals -.->|Logs/Metrics| OrgMonitoring
    LLMProxy -.->|Logs/Metrics| OrgMonitoring

    %% Styling
    classDef user fill:#9e9e9e,stroke:#616161,stroke-width:2px,color:#fff
    classDef frontend fill:#42a5f5,stroke:#1565c0,stroke-width:2px,color:#fff
    classDef backend fill:#ff9800,stroke:#e65100,stroke-width:2px,color:#fff
    classDef data fill:#7e57c2,stroke:#4527a0,stroke-width:2px,color:#fff
    classDef ai fill:#66bb6a,stroke:#2e7d32,stroke-width:2px,color:#fff
    classDef external fill:#ec407a,stroke:#ad1457,stroke-width:2px,color:#fff

    class Users user
    class Frontend,PublicAPI frontend
    class API,BackgroundProcessing backend
    class PostgreSQL,Redis data
    class LLMProxy,Evals ai
    class Storage,LLMProviders,SAMLIdP,OrgMonitoring external
```

## Component Overview

### Application Services (Docker Containers)

* **Frontend**: Next.js application - user-facing web interface \[Container]
* **Public API / SDK**: External integration interface - programmatic access for developers
* **API Server**: Main backend service (Python) - core business logic and REST API \[Container]
* **Background Processing**: Handles asynchronous job processing (Python) \[Container]

### AI/ML Services (Docker Containers)

* **LLM Proxy**: Unified interface to multiple LLM providers (Python) \[Container]
* **Evals**: Evaluation and assessment service (Python) \[Container]

### Data Layer

* **PostgreSQL**: Primary relational database
* **Redis**: Cache and message broker for task queues

### External Dependencies

* **Storage**: Object storage for files and artifacts
* **LLM Providers**: External and self-hosted AI services
* **SAML Identity Provider**: Organization's identity provider for authentication (e.g., Entra, Okta)
* **Organization Systems**: Integration with organization's monitoring, logging, and SIEM systems

## Data Flow

Data flows into the system through the API Server (via Frontend or Public API/SDK) and remains within the system components and databases. The only external data transmission occurs when the LLM Proxy makes API calls to LLM Providers for AI inference.

## Authentication & Authorization

Users are created and managed within Scorable. Authentication and authorization can be delegated to external identity services through SAML integration, allowing organizations to use their existing identity providers such as Entra.

## Component Details

### Stateful vs Stateless Components

| Component             | State     | Scalability | Notes                                             |
| --------------------- | --------- | ----------- | ------------------------------------------------- |
| Frontend              | Stateless | Horizontal  | Can run multiple replicas                         |
| API Server            | Stateless | Horizontal  | Can run multiple replicas                         |
| Background Processing | Stateless | Horizontal  | Can run multiple replicas                         |
| Evals Service         | Stateless | Horizontal  | Can run multiple replicas                         |
| LLM Proxy             | Stateless | Horizontal  | Can run multiple replicas                         |
| PostgreSQL            | Stateful  | Vertical/HA | Requires persistent storage, supports replication |
| Redis                 | Stateful  | Vertical/HA | Requires persistence for task queues              |

### Minimum Resource Requirements

**Per Container Instance:**

| Component             | CPU Request | Memory  | Notes                 |
| --------------------- | ----------- | ------- | --------------------- |
| Frontend              | 250m        | \~512MB | User interface        |
| API Server            | 500m        | \~1GB   | Core backend logic    |
| Background Processing | 500m        | \~1GB   | Async task processing |
| Evals Service         | 500m        | \~1GB   | Evaluation workloads  |
| LLM Proxy             | 500m        | \~1GB   | LLM request routing   |

**Databases:**

| Component  | Minimum        | Recommended      | Notes                     |
| ---------- | -------------- | ---------------- | ------------------------- |
| PostgreSQL | 2 CPU, 4GB RAM | 4+ CPU, 8GB+ RAM | Size based on data volume |
| Redis      | 1 CPU, 2GB RAM | 2 CPU, 4GB RAM   | Size based on queue depth |

### High Availability Configuration

**Recommended Minimum Replicas:**

* Frontend: 2 replicas
* API Server: 4 replicas
* Background Processing: 2+ replicas
* Evals Service: 2 replicas
* LLM Proxy: 2 replicas

**Database HA:**

* PostgreSQL: Primary + 1 or more read replicas
* Redis: Sentinel or cluster mode for HA

## Network & Integration

### Entry Points

| Component      | External Access | Protocol | Purpose             |
| -------------- | --------------- | -------- | ------------------- |
| Frontend       | Yes             | HTTPS    | Web interface       |
| Public API/SDK | Yes             | HTTPS    | Programmatic access |
| API Server     | Internal only   | HTTP     | Backend services    |

### Internal Communication

All internal communication between containers occurs over Redis or HTTP within the deployment environment. Components use service discovery (DNS or service names) to locate each other. Components use Redis for task queues and for inter-container communication.

### Integration Protocols

**SAML Authentication:**

* Protocol: SAML 2.0
* Callback to API Server for authentication validation
* Metadata exchange with organization's IdP

**Monitoring & Logging:**

* Logs: stdout/stderr
* Metrics: Can be exposed for scraping (Prometheus)

**Object Storage:**

* Protocol: S3, Azure Blob Storage, GCP Storage, etc.
* Authentication: Access keys or IAM roles
* Used for: File uploads, artifacts, backups

## Data Persistence

### Storage Requirements

**PostgreSQL Database:**

* Type: Block storage with persistent volumes
* Size: Varies by usage (start with 50GB, plan for growth)
* Backup: Daily backups recommended, point-in-time recovery

**Redis:**

* Type: Block storage with persistent volumes
* Size: 10-50GB typical
* Persistence: RDB snapshots + AOF for durability
* Backup: Periodic snapshots

**Object Storage:**

* Type: S3, Azure Blob Storage, GCP Storage, etc.
* Size: Varies significantly by usage
* Growth: Plan for user-uploaded content and evaluation data