Architecture

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

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