# typelevel/cats architecture

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

- Interactive diagram: https://gitdiagram.com/typelevel/cats
- Repository: https://github.com/typelevel/cats

## Overview

##### Project type and purpose
- This is an open-source, multi-module Scala library (“Cats”) providing functional-programming abstractions (type classes, data types, laws, free structures, etc.) for Scala, Scala.js, and Scala Native.
- It is not a web or full-stack app—it’s a toolkit comprised of independent but inter-related modules.

##### File structure
- Top-level directories are modules:
- kernel / kernel-laws
- core / laws
- free
- algebra-core / algebra-laws
- alleycats-core / alleycats-laws
- cats-testkit
- bench, binCompatTest, scripts, scalafix, docs, tests
- Root has build.sbt, project/ (SBT meta-build), config files, CI workflows.
- Each module has src/main/scala and src/test/scala, often cross-built for Scala 2.12, 2.13+, 3, JS, JVM, Native.

##### README for additional insights
- Core modules: cats-kernel, cats-core, cats-free, cats-laws, cats-testkit, algebra, alleycats.
- Emphasis on modularity, binary compatibility, cross-platform support (Scala.js, Native).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Infrastructure
    subgraph "Build Infrastructure"
        direction TB
        BuildInfra_project("project/"):::infra
        BuildInfra_build("build.sbt"):::infra
        BuildInfra_mima("mima.sbt"):::infra
        BuildInfra_ci(".github/workflows/ci.yml"):::infra
        BuildInfra_clean(".github/workflows/clean.yml"):::infra
    end

    %% Foundation Layer
    subgraph "Foundation Layer"
        direction TB
        Kernel("Kernel Module"):::foundation
        KernelLaws("kernel-laws"):::laws
    end

    %% Core & Extensions
    subgraph "Core & Extensions"
        direction TB
        Core("Core Module"):::core
        Free("Free Module"):::core
        Algebra("Algebra Module"):::core
        Alleycats("Alleycats Module"):::core
    end

    %% Law Testing Layer
    subgraph "Law Testing Layer"
        direction TB
        CatsLaws("cats-laws"):::laws
        AlgebraLaws("algebra-laws"):::laws
        AlleycatsLaws("alleycats-laws"):::laws
        Testkit("cats-testkit"):::laws
    end

    %% Tooling
    subgraph "Tooling"
        direction TB
        Bench("bench"):::tooling
        BinCompat("binCompatTest"):::tooling
        Scalafix("scalafix"):::tooling
        Scripts("scripts"):::tooling
    end

    %% Cross-Build & CI
    subgraph "CI/CD & Cross-Build"
        direction TB
        SBT("SBT Build"):::infra
        CI("GitHub Actions CI"):::infra
    end

    %% Dependencies
    Kernel -->|"uses"| Core
    Kernel -->|"provides foundation for"| Algebra
    Core -->|"uses"| Free
    Core -->|"extends"| Algebra
    Algebra -->|"extended by"| Alleycats
    Free -->|"tested by"| Testkit

    KernelLaws -->|"tests"| Kernel
    CatsLaws -->|"tests"| Core
    CatsLaws -->|"tests"| Free
    AlgebraLaws -->|"tests"| Algebra
    AlleycatsLaws -->|"tests"| Alleycats

    Scalafix -->|"transforms"| Kernel
    Scalafix -->|"transforms"| Core
    Scalafix -->|"transforms"| Free
    Scalafix -->|"transforms"| Algebra
    Scalafix -->|"transforms"| Alleycats

    Bench -->|"benchmarks"| Core
    Bench -->|"benchmarks"| Free
    BinCompat -->|"checks compatibility for"| Core
    BinCompat -->|"checks compatibility for"| Kernel

    SBT -->|"orchestrates build"| Kernel
    SBT -->|"orchestrates build"| Core
    SBT -->|"orchestrates build"| Free
    SBT -->|"orchestrates build"| Algebra
    SBT -->|"orchestrates build"| Alleycats
    SBT -->|"runs"| CatsLaws
    SBT -->|"runs"| KernelLaws
    SBT -->|"runs"| AlgebraLaws
    SBT -->|"runs"| AlleycatsLaws
    SBT -->|"runs"| Bench
    SBT -->|"runs"| BinCompat
    SBT -->|"runs"| Scalafix
    SBT -->|"runs"| Scripts

    CI -->|"invokes"| SBT

    %% Click Events
    click BuildInfra_project "https://github.com/typelevel/cats/tree/main/project/"
    click BuildInfra_build "https://github.com/typelevel/cats/blob/main/build.sbt"
    click BuildInfra_mima "https://github.com/typelevel/cats/blob/main/mima.sbt"
    click BuildInfra_ci "https://github.com/typelevel/cats/blob/main/.github/workflows/ci.yml"
    click BuildInfra_clean "https://github.com/typelevel/cats/blob/main/.github/workflows/clean.yml"
    click Kernel "https://github.com/typelevel/cats/tree/main/kernel/src/main/scala/cats/kernel/"
    click KernelLaws "https://github.com/typelevel/cats/tree/main/kernel-laws/shared/src/main/scala/cats/kernel/laws/"
    click Core "https://github.com/typelevel/cats/tree/main/core/src/main/scala/cats/"
    click CatsLaws "https://github.com/typelevel/cats/tree/main/laws/src/main/scala/cats/laws/"
    click Free "https://github.com/typelevel/cats/tree/main/free/src/main/scala/cats/free/"
    click Algebra "https://github.com/typelevel/cats/tree/main/algebra-core/src/main/scala/algebra/"
    click AlgebraLaws "https://github.com/typelevel/cats/tree/main/algebra-laws/shared/src/main/scala/algebra/laws/"
    click Alleycats "https://github.com/typelevel/cats/tree/main/alleycats-core/src/main/scala/alleycats/"
    click AlleycatsLaws "https://github.com/typelevel/cats/tree/main/alleycats-laws/shared/src/main/scala/alleycats/laws/"
    click Testkit "https://github.com/typelevel/cats/blob/main/testkit/src/main/scala/cats/tests/Helpers.scala"
    click Bench "https://github.com/typelevel/cats/tree/main/bench/src/main/scala/cats/bench/"
    click BinCompat "https://github.com/typelevel/cats/blob/main/binCompatTest/src/main/scala-2/catsBC/MimaExceptions.scala"
    click Scalafix "https://github.com/typelevel/cats/blob/main/scalafix/rules/src/main/scala/fix/Cats_v1_0_0.scala"
    click Scripts "https://github.com/typelevel/cats/blob/main/scripts/releaseNotes.scala"

    %% Styles
    classDef foundation fill:#E0F7FA,stroke:#006064,color:#006064
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef laws fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef tooling fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef infra fill:#F3E5F5,stroke:#4A148C,color:#4A148C
    classDef default stroke:#333,stroke-width:1px,fill:#fff,rx:5,ry:5
```
