# loculus-project/loculus architecture

> Architecture diagram of the GitHub repository loculus-project/loculus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loculus-project/loculus
- Repository: https://github.com/loculus-project/loculus

## Overview

##### Main Components Identification

a) Frontend Layer:
- Website (React/Astro-based web interface)
- Keycloakify (custom authentication UI)

b) Backend Services:
- Main Backend (Kotlin-based)
- LAPIS (for querying data)
- Preprocessing Pipeline
- ENA Submission Service

c) Authentication:
- Keycloak Server

d) Databases:
- Main Database (PostgreSQL)
- LAPIS Database

**┌─ Client Layer ─────────────────────┐**
- Web Browser / API Clients          │
- ┬───────────────────┘
- ↓
**┌─ Frontend Layer ───────────────────┐**
- Website (Astro/React)              │
- Keycloakify Theme                  │
- ┬───────────────────┘
- ↓
**┌─ API Gateway Layer ────────────────┐**
- Ingress Controller / Load Balancer │
- ┬──────────┬────────────┘
- ↓          ↓
**┌─ Service Layer ──────────────────────────────────┐**
- ┌─────────────┐ ┌──────────┐ ┌────────────────┐ │
- Main Backend │ │  LAPIS   │ │Preprocessing   │ │
- (Kotlin)     │ │          │ │Pipeline        │ │
- ┘ └──────────┘ └────────────────┘ │
- ┌─────────────┐ ┌──────────────────────────────┐│
- ENA          │ │Keycloak Authentication       ││
- Submission   │ │Server                        ││
- ┘ └──────────────────────────────┘│
- ┬──────────┬────────────┬────────────┘
- ↓          ↓            ↓
**┌─ Data Layer ───────────────────────────────────┐**
- ┌─────────────┐ ┌──────────┐ ┌──────────────┐ │
- Main Database│ │LAPIS DB  │ │Keycloak DB   │ │
- (PostgreSQL) │ │          │ │              │ │
- ┘ └──────────┘ └──────────────┘ │
- ┘

##### Key Interactions to Highlight

- User authentication flow through Keycloak
- Sequence submission and preprocessing pipeline
- Search queries through LAPIS
- Data synchronization between databases
- ENA submission workflow

##### Important Details

- Kubernetes deployment boundaries
- API endpoints and communication protocols
- Data flow directions
- Authentication boundaries
- External service integrations

##### Specific Implementation Notes

- How the preprocessing pipeline can be customized/extended
- Flexible metadata field configuration
- Multi-segmented genome support
- Group management and access control flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef client fill:#B3E5FC,stroke:#0288D1
    classDef frontend fill:#90CAF9,stroke:#1976D2
    classDef gateway fill:#9FA8DA,stroke:#3949AB
    classDef service fill:#A5D6A7,stroke:#388E3C
    classDef auth fill:#EF9A9A,stroke:#D32F2F
    classDef data fill:#FFE082,stroke:#FFA000
    classDef external fill:#CE93D8,stroke:#7B1FA2

    %% Client Layer
    Client["Web Browser / API Clients"]:::client

    %% Frontend Layer
    subgraph Frontend
        Website["Website (Astro/React)"]:::frontend
        KeycloakifyTheme["Keycloakify Theme"]:::frontend
    end

    %% API Gateway Layer
    Gateway["Ingress Controller / Load Balancer"]:::gateway

    %% Service Layer
    subgraph Services
        MainBackend["Main Backend (Kotlin)"]:::service
        LAPIS["LAPIS Query Service"]:::service
        Pipeline["Preprocessing Pipeline"]:::service
        ENASubmission["ENA Submission Service"]:::service
        KeycloakServer["Keycloak Server"]:::auth
    end

    %% Data Layer
    subgraph Data
        MainDB[(Main Database)]:::data
        LAPISDB[(LAPIS DB)]:::data
        KeycloakDB[(Keycloak DB)]:::data
    end

    %% External Services
    ENA["European Nucleotide Archive"]:::external

    %% Relationships
    Client --> Website
    Client --> KeycloakifyTheme
    Website --> Gateway
    KeycloakifyTheme --> Gateway
    Gateway --> MainBackend
    Gateway --> LAPIS
    Gateway --> KeycloakServer
    MainBackend --> Pipeline
    MainBackend --> ENASubmission
    MainBackend --> MainDB
    LAPIS --> LAPISDB
    KeycloakServer --> KeycloakDB
    ENASubmission --> ENA

    %% Click events
    click Website "https://github.com/loculus-project/loculus/tree/main/website"
    click KeycloakifyTheme "https://github.com/loculus-project/loculus/tree/main/keycloak/keycloakify"
    click MainBackend "https://github.com/loculus-project/loculus/tree/main/backend"
    click Pipeline "https://github.com/loculus-project/loculus/tree/main/preprocessing"
    click ENASubmission "https://github.com/loculus-project/loculus/tree/main/ena-submission"

    %% Legend
    subgraph Legend
        L1["Client Components"]:::client
        L2["Frontend Components"]:::frontend
        L3["Gateway Components"]:::gateway
        L4["Service Components"]:::service
        L5["Auth Components"]:::auth
        L6["Data Storage"]:::data
        L7["External Services"]:::external
    end
```
