# biomedical-signal-processing/sleepyland architecture

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

- Interactive diagram: https://gitdiagram.com/biomedical-signal-processing/sleepyland
- Repository: https://github.com/biomedical-signal-processing/sleepyland

## Overview

##### Project Type and Purpose
- This is a full-stack, Docker-orchestrated Python web application (“SLEEPYLAND”) for FAIR, local sleep staging analysis.
- It leverages a Flask-based GUI, a lightweight Python API (“manager-api”), data-download scripts, model-inference services, and Jupyter notebooks for tutorials and advanced analysis.

##### Key Directories & Services
- Top-level docker-compose.yml defines multiple containers:
- gui (Flask web UI)
- manager-api (internal REST API)
- nsrr-download (data ingestion service)
- usleepyland (model-inference CLI)
- notebook (Jupyter environment)
- wild-to-fancy (data harmonization CLI)
- Shared volumes:
- nsrr_file_path (input EDF/XML)
- output (predictions, metrics)
- gui/app/ contains Flask routes, service modules (download, prediction, metrics), utils (file handling, validation).
- manager-api/src/api.py exposes REST endpoints; utils.py holds shared logic.
- nsrr-download/ and usleepyland/ hold standalone scripts and environment configs.
- notebook/ hosts tutorial notebooks and resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestrator grouping
    subgraph "Docker Compose Orchestrator" 
        direction TB
        ORCH[("docker-compose.yml")]:::orchestrator
        subgraph "Services"
            direction TB
            Browser["User Browser"]:::frontend
            GUI["GUI Service (Flask)"]:::frontend
            API["Manager-API Service"]:::backend
            NSRR["NSRR-Download Service"]:::dataservice
            Model["Model Service (usleepyland)"]:::model
            Notebook["Notebook Service (Jupyter)"]:::notebook
            Fancy["wild-to-fancy Service"]:::dataservice
        end
        VolIn[/"nsrr_file_path Volume"/]:::volume
        VolOut[/"output Volume"/]:::volume
        ExtNSRR[(External NSRR Data Source)]:::external
    end

    %% Relationships
    Browser -->|"HTTP 8887"| GUI
    GUI -->|"REST 8000"| API
    API -->|"invoke"| NSRR
    NSRR -->|"- writes .edf/.xml"| VolIn
    GUI -->|"invoke prediction"| Model
    Model -->|"- writes predictions & metrics"| VolOut
    GUI -->|"- reads metrics/graphs"| VolOut
    Notebook -->|"- mounts volumes"| VolIn
    Notebook -->|"- mounts volumes"| VolOut
    GUI -->|"optional harmonization"| Fancy
    Fancy -->|"- reads/writes volumes"| VolIn
    Fancy -->|"- reads/writes volumes"| VolOut
    ExtNSRR -->|"HTTP"| NSRR

    %% GUI internal modules
    subgraph "GUI Service Components"
        direction TB
        GUI_DF[Dockerfile]:::orchestrator
        GUI_APP[app.py]:::frontend
        GUI_ROUTES[routes.py]:::frontend
        GUI_DS[download_service.py]:::frontend
        GUI_PS[prediction_service.py]:::frontend
        GUI_MS[metrics_service.py]:::frontend
        GUI_GS[graph_service.py]:::frontend
        GUI_CS[get_channel_service.py]:::frontend
        GUI_FH[file_handling.py]:::frontend
        GUI_FV[file_validation.py]:::frontend
        GUI_HTML[index.html]:::frontend
    end
    GUI --> GUI_DF
    GUI --> GUI_APP
    GUI --> GUI_ROUTES
    GUI --> GUI_DS
    GUI --> GUI_PS
    GUI --> GUI_MS
    GUI --> GUI_GS
    GUI --> GUI_CS
    GUI --> GUI_FH
    GUI --> GUI_FV
    GUI --> GUI_HTML

    %% Manager-API internals
    subgraph "Manager-API Components"
        direction TB
        API_DF[Dockerfile]:::orchestrator
        API_SRC[api.py]:::backend
        API_UTIL[utils.py]:::backend
    end
    API --> API_DF
    API --> API_SRC
    API --> API_UTIL

    %% NSRR-Download internals
    subgraph "NSRR-Download Components"
        direction TB
        NSRR_DF[Dockerfile]:::orchestrator
        NSRR_PY[nsrr-download.py]:::dataservice
        NSRR_SH[nsrr_download.sh]:::dataservice
        NSRR_ENV[environment.yaml]:::dataservice
    end
    NSRR --> NSRR_DF
    NSRR --> NSRR_PY
    NSRR --> NSRR_SH
    NSRR --> NSRR_ENV

    %% Model Service internals
    subgraph "Model Service Components"
        direction TB
        MODEL_DF[Dockerfile]:::orchestrator
        MODEL_PY[predict.py]:::model
        MODEL_ART[model artifacts]:::model
    end
    Model --> MODEL_DF
    Model --> MODEL_PY
    Model --> MODEL_ART

    %% Notebook internals
    subgraph "Notebook Components"
        direction TB
        NB_DF[Dockerfile]:::orchestrator
        NB_LUNA[lunapi-notebooks/]:::notebook
        NB_SL[sleepyland-notebooks/]:::notebook
        NB_IMG[imgs/]:::notebook
    end
    Notebook --> NB_DF
    Notebook --> NB_LUNA
    Notebook --> NB_SL
    Notebook --> NB_IMG

    %% wild-to-fancy internals
    subgraph "wild-to-fancy Components"
        direction TB
        WF_DF[Dockerfile]:::orchestrator
        WF_HM[harmonize.py]:::dataservice
        WF_AC[annotation_commands.json]:::dataservice
        WF_DC[dataset_commands.json]:::dataservice
    end
    Fancy --> WF_DF
    Fancy --> WF_HM
    Fancy --> WF_AC
    Fancy --> WF_DC

    %% Click Events
    click ORCH "https://github.com/biomedical-signal-processing/sleepyland/blob/main/docker-compose.yml"
    click GUI_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/gui/Dockerfile"
    click GUI_APP "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app.py"
    click GUI_ROUTES "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/routes.py"
    click GUI_DS "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/services/download_service.py"
    click GUI_PS "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/services/prediction_service.py"
    click GUI_MS "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/services/metrics_service.py"
    click GUI_GS "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/services/graph_service.py"
    click GUI_CS "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/services/get_channel_service.py"
    click GUI_FH "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/utils/file_handling.py"
    click GUI_FV "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/app/utils/file_validation.py"
    click GUI_HTML "https://github.com/biomedical-signal-processing/sleepyland/blob/main/gui/templates/index.html"
    click API_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/manager-api/Dockerfile"
    click API_SRC "https://github.com/biomedical-signal-processing/sleepyland/blob/main/manager-api/src/api.py"
    click API_UTIL "https://github.com/biomedical-signal-processing/sleepyland/blob/main/manager-api/src/utils.py"
    click NSRR_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/nsrr-download/Dockerfile"
    click NSRR_PY "https://github.com/biomedical-signal-processing/sleepyland/blob/main/nsrr-download/nsrr-download.py"
    click NSRR_SH "https://github.com/biomedical-signal-processing/sleepyland/blob/main/nsrr-download/nsrr_download.sh"
    click NSRR_ENV "https://github.com/biomedical-signal-processing/sleepyland/blob/main/nsrr-download/environment.yaml"
    click MODEL_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/usleepyland/Dockerfile"
    click MODEL_PY "https://github.com/biomedical-signal-processing/sleepyland/blob/main/usleepyland/src/predict.py"
    click MODEL_ART "https://github.com/biomedical-signal-processing/sleepyland/tree/main/usleepyland/model/"
    click NB_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/notebook/Dockerfile"
    click NB_LUNA "https://github.com/biomedical-signal-processing/sleepyland/tree/main/notebook/src/lunapi-notebooks/"
    click NB_SL "https://github.com/biomedical-signal-processing/sleepyland/tree/main/notebook/src/sleepyland-notebooks/"
    click NB_IMG "https://github.com/biomedical-signal-processing/sleepyland/tree/main/notebook/resources/imgs/"
    click WF_DF "https://github.com/biomedical-signal-processing/sleepyland/tree/main/wild-to-fancy/Dockerfile"
    click WF_HM "https://github.com/biomedical-signal-processing/sleepyland/blob/main/wild-to-fancy/src/harmonize.py"
    click WF_AC "https://github.com/biomedical-signal-processing/sleepyland/blob/main/wild-to-fancy/src/annotation_commands.json"
    click WF_DC "https://github.com/biomedical-signal-processing/sleepyland/blob/main/wild-to-fancy/src/dataset_commands.json"

    %% Styles
    classDef frontend fill:#AED8E6,stroke:#036;stroke-width:1px
    classDef backend fill:#C8E6C9,stroke:#036;stroke-width:1px
    classDef dataservice fill:#FFE0B2,stroke:#036;stroke-width:1px
    classDef model fill:#FFCDD2,stroke:#036;stroke-width:1px
    classDef notebook fill:#E1BEE7,stroke:#036;stroke-width:1px
    classDef volume fill:#E0E0E0,stroke:#036;stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#FFFFFF,stroke:#036;stroke-width:1px,stroke-dasharray: 2 2
    classDef orchestrator fill:#B0BEC5,stroke:#033;stroke-width:2px,stroke-dasharray: 4 2
```
