# alleninstitute/scrattch architecture

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

- Interactive diagram: https://gitdiagram.com/alleninstitute/scrattch
- Repository: https://github.com/alleninstitute/scrattch

## Overview

##### Project type and purpose
- This is an R “umbrella” package (modeled after the tidyverse) that bundles installation, update, and helper functions for a suite of downstream `scrattch.*` packages.

##### File structure
- Top-level metadata: DESCRIPTION, NAMESPACE, README.md, LICENSE, CONTRIBUTION.
- R/: contains core function definitions:
- dependencies.R (declare child-package dependencies)
- install.R (functions: install_scrattch(), install_bioc_deps(), install_github_deps(), install_scrattch_deps())
- inst/: supporting scripts & data shipped in the package:
- generate_function_table.R (script to build function lookup)
- scrattch_function_list.csv (generated table of exported functions)
- man/: autogenerated documentation for each exported function.
- Build metadata: .Rbuildignore, .gitignore, scrattch.Rproj.
- No “runtime” services or web server; it’s a library/package.

##### README for additional insights
- Emphasis on using Docker/Singularity to install the full suite.
- References to external repositories (child packages) and Docker Hub.
- Historical branches (scrattch_2023, archive).

##### Main components & interactions
a. Components:
1. User environment (R session or HPC via Singularity)
2. Umbrella package “scrattch”:
- Core R functions (install, dependency management, palettes)
- Inst scripts and function lookup table
- Man pages
3. External package registries:
- CRAN/Bioconductor (for Bioconductor dependencies)
- GitHub (for child `scrattch.*` repos)
4. Docker Hub / Singularity (optional runtime environment)
5. Child packages (not part of this repo but orchestrated):
- scrattch.taxonomy, scrattch.mapping, scrattch.hicat, etc.
b. Relationships & data flow:
- User invokes scrattch::install_scrattch()
→ install_scrattch calls install_bioc_deps() to fetch Bioconductor packages
→ install_github_deps() to fetch child repos from GitHub
→ (optionally) instructs Docker client or Singularity to pull/run container
→ Returns: child packages installed & ready in user’s R library.
c. Architectural patterns / design principles:
- “Facade” pattern: provides a single interface (scrattch) to a complex subsystem of child packages.
- Modular layering: Core functions separated (R/) from shipped scripts/data (inst/) and docs (man/).
- Convention over configuration: standard R package structure.
d. Key technologies / frameworks:
- R (base, devtools)
- Bioconductor
- GitHub API (via usethis/devtools)
- Docker / Singularity
- Roxygen2 (doc generation)

##### Elements
- “User R Session”
- “Bioconductor registry”
- “GitHub repos”
- “Docker Hub / Singularity runtime”
- User → scrattch::install_scrattch()
- scrattch → Bioconductor
- scrattch → GitHub
- scrattch → Docker/Singularity (optional)

##### Final recommendations
- Be exhaustive: represent each folder’s role (R/, inst/, man/).
- Orchestration logic flow — this is the heart of the umbrella pattern.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Environment
    User["User R Session"]:::external

    %% Umbrella package
    subgraph "scrattch umbrella package"
        direction TB
        subgraph "Metadata"
            direction TB
            DESCRIPTION["DESCRIPTION"]:::code
            NAMESPACE["NAMESPACE"]:::code
            README["README.md"]:::code
            LICENSE["LICENSE"]:::code
            CONTRIBUTION["CONTRIBUTION"]:::code
        end

        subgraph "R/ (Core Modules)"
            direction TB
            Color["color.R"]:::code
            Deps["dependencies.R"]:::code
            Install["install.R"]:::code
        end

        subgraph "inst/ (Scripts & Data)"
            direction TB
            GenFunc["generate_function_table.R"]:::code
            FuncList["scrattch_function_list.csv"]:::code
        end

        subgraph "man/ (Documentation)"
            direction TB
            ManDocs["*.Rd"]:::code
        end

        subgraph "Build Config"
            direction TB
            Rbuild[".Rbuildignore"]:::code
            Gitignore[".gitignore"]:::code
            Rproj["scrattch.Rproj"]:::code
        end
    end

    %% External services
    BiocRegistry["Bioconductor Registry"]:::external
    GitHub["GitHub scrattch.* modules"]:::external
    Container["Docker Hub / Singularity"]:::optional

    %% Orchestration flow
    User -->|"calls install_scrattch()"| Install
    Install -->|"fetch Bioconductor deps"| BiocRegistry
    Install -->|"fetch GitHub packages"| GitHub
    Install -->|"pull/run container"| Container

    %% Internal interactions
    Deps -->|"reads"| FuncList
    Color -->|"uses"| FuncList

    %% Click Events
    click DESCRIPTION "https://github.com/alleninstitute/scrattch/tree/master/DESCRIPTION"
    click NAMESPACE "https://github.com/alleninstitute/scrattch/tree/master/NAMESPACE"
    click README "https://github.com/alleninstitute/scrattch/blob/master/README.md"
    click LICENSE "https://github.com/alleninstitute/scrattch/tree/master/LICENSE"
    click CONTRIBUTION "https://github.com/alleninstitute/scrattch/tree/master/CONTRIBUTION"
    click Color "https://github.com/alleninstitute/scrattch/blob/master/R/color.R"
    click Deps "https://github.com/alleninstitute/scrattch/blob/master/R/dependencies.R"
    click Install "https://github.com/alleninstitute/scrattch/blob/master/R/install.R"
    click GenFunc "https://github.com/alleninstitute/scrattch/blob/master/inst/generate_function_table.R"
    click FuncList "https://github.com/alleninstitute/scrattch/blob/master/inst/scrattch_function_list.csv"
    click ManDocs "https://github.com/alleninstitute/scrattch/tree/master/man/"
    click Rbuild "https://github.com/alleninstitute/scrattch/blob/master/.Rbuildignore"
    click Gitignore "https://github.com/alleninstitute/scrattch/blob/master/.gitignore"
    click Rproj "https://github.com/alleninstitute/scrattch/blob/master/scrattch.Rproj"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#D0FFD0,stroke:#228B22,color:#228B22
    classDef optional fill:#FFF0D0,stroke-dasharray: 5 5,stroke:#DAA520,color:#DAA520
```
