# fractal-analytics-platform/fractal-server architecture

> Architecture diagram of the GitHub repository fractal-analytics-platform/fractal-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fractal-analytics-platform/fractal-server
- Repository: https://github.com/fractal-analytics-platform/fractal-server

## Overview

##### Main Components

a. Core Server Components:
- FastAPI Application Layer (evident from the app structure)
- Authentication System (auth routes and security modules)
- Database Layer (SQLAlchemy ORM, based on models structure)
- Task Runner System (with multiple executors)
- API Versioning (v1 and v2 endpoints)

b. External Interfaces:
- REST API Endpoints
- OAuth Integration
- SLURM Integration
- SSH Connectivity
- Database Connection

##### Component Relationships

**Top Level (Client Interface):**
- REST API (v1, v2) <-> Authentication Layer

**Middle Level (Business Logic):**
- Route Handlers <-> Task Management <-> Runner System

**Bottom Level (Infrastructure):**
- Database <-> Models
- File System <-> Task Executors
- External Services (SLURM, SSH)

##### Specific Implementation Details to Highlight

a. API Structure (fractal_server/app/routes/):
- Separate v1 and v2 API versions
- Admin, auth, and core API routes
- Task collection endpoints

b. Task Execution System (fractal_server/app/runner/):
- Local executor
- SLURM executor
- SSH integration
- Task lifecycle management

c. Data Models (fractal_server/app/models/):
- Project structure
- Workflow management
- Task definitions
- User management

##### Key Workflows to Illustrate

a. Task Execution Flow:
1. API Request
2. Authentication
3. Task Validation
4. Runner Selection
5. Execution
6. Status Updates
7. Result Storage

b. Data Processing Pipeline:
1. Input Reception
2. Task Distribution
3. Parallel Processing
4. Result Collection
5. Storage Management

##### Important Design Patterns

- Repository Pattern (for database access)
- Factory Pattern (for runner creation)
- Strategy Pattern (for different execution methods)
- Observer Pattern (for task status updates)

##### Technical Details

- PostgreSQL Database
- FastAPI Framework
- Alembic Migrations
- OAuth2 Authentication
- SLURM Integration
- SSH Connectivity
- Task Queue System

##### Infrastructure Layer (execution environment)

- Component types
- Connection types (sync/async)
- Data flow directions
- Security boundaries
- Version distinctions (v1/v2)

This architecture should emphasize the system's ability to handle:
- Parallel processing
- Multiple execution environments
- Versioned APIs
- Security requirements
- Scalability concerns

Remember to maintain a balance between detail and clarity, focusing on the key architectural decisions while avoiding overwhelming technical minutiae.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        REST[REST API Client]
    end

    subgraph "Interface Layer"
        API_V1["/api/v1 Endpoints"]:::api
        API_V2["/api/v2 Endpoints"]:::api
        ADMIN["Admin Routes"]:::api
        AUTH["Authentication"]:::security
    end

    subgraph "Business Logic Layer"
        TASK_MGMT["Task Management"]:::core
        RUNNER["Runner System"]:::core
        OAUTH["OAuth Handler"]:::security
        SECURITY["Security Controls"]:::security
    end

    subgraph "Data Access Layer"
        DB_MODELS["Database Models"]:::data
        SCHEMAS["Task Schemas"]:::data
        MIGRATIONS["DB Migrations"]:::data
    end

    subgraph "Infrastructure Layer"
        DB[(PostgreSQL)]:::infra
        LOCAL["Local Executor"]:::exec
        SLURM["SLURM Executor"]:::exec
        SSH["SSH Service"]:::exec
        FS["File System"]:::infra
    end

    %% Connections
    REST --> API_V1 & API_V2 & ADMIN
    API_V1 & API_V2 & ADMIN --> AUTH
    AUTH --> SECURITY
    SECURITY --> OAUTH
    API_V1 & API_V2 --> TASK_MGMT
    TASK_MGMT --> RUNNER
    RUNNER --> LOCAL & SLURM & SSH
    TASK_MGMT --> DB_MODELS
    DB_MODELS --> DB
    SCHEMAS --> TASK_MGMT
    MIGRATIONS --> DB
    LOCAL & SLURM & SSH --> FS

    %% Click Events
    click API_V1 "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/routes/api/v1/"
    click API_V2 "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/routes/api/v2/"
    click ADMIN "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/routes/admin/"
    click AUTH "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/routes/auth/"
    click OAUTH "https://github.com/fractal-analytics-platform/fractal-server/blob/main/fractal_server/app/routes/auth/oauth.py"
    click SECURITY "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/security/"
    click RUNNER "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/runner/"
    click DB_MODELS "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/models/"
    click SCHEMAS "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/schemas/"
    click MIGRATIONS "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/migrations/"
    click SLURM "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/app/runner/executors/slurm/"
    click SSH "https://github.com/fractal-analytics-platform/fractal-server/tree/main/fractal_server/ssh/"

    %% Styling
    classDef api fill:#2374ab
    classDef security fill:#57a773
    classDef core fill:#484d6d
    classDef data fill:#f7d794
    classDef exec fill:#ff8364
    classDef infra fill:#95a5a6

    %% Legend
    subgraph Legend
        L1["API Component"]:::api
        L2["Security Component"]:::security
        L3["Core Component"]:::core
        L4["Data Component"]:::data
        L5["Executor Component"]:::exec
        L6["Infrastructure"]:::infra
    end
```
