# supertokens/supertokens-core architecture

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

- Interactive diagram: https://gitdiagram.com/supertokens/supertokens-core
- Repository: https://github.com/supertokens/supertokens-core

## Overview

##### Main Components
- Core Authentication Engine: Represented by the main “src” directory (including packages such as authRecipe, emailpassword, emailverification, session, jwt, webserver, etc.). This component implements the core HTTP API endpoints for sign-in, sign-up, token management, and various authentication flows.
- Enterprise Modules: The “ee” directory contains the enterprise-specific features (e.g., extended licensing, feature flag checks, cronjobs for license validity, etc.). This can be drawn as an extension to the core authentication engine.
- CLI Module: The “cli” directory wraps a command-line interface for administrative tasks (installation, starting/stopping processes, printing help, and version management). It communicates with the core engine (possibly to trigger build processes or administrative commands).
- Downloader Module: The “downloader” directory contains code to help fetch or update necessary parts (likely interacting with remote repositories or updating jars). This module can be considered as a support or integration component.
- Build & CI/CD: Directories like “.circleci” and “.github” (with workflows and Dockerfiles) highlight the CI/CD and automated testing/integration pipelines. Although not part of runtime architecture, they are essential for deployments.

##### Relationships and Interactions
- External SDKs (Frontend & Backend) call the SuperTokens Core’s API endpoints (hosted on an embedded webserver).
- The Core communicates with its Storage Layer (both in-memory and/or on-disk databases) to manage user data, sessions, and tokens.
- Within the core, distinct “recipes” (emailpassword, passwordless, multi-tenancy, etc.) encapsulate specific authentication/logging logic. They interact with a central configuration system and share utilities (logging, rate limiter, JWT handling, etc.).
- The CLI module acts as a user-facing tool that internally calls the core services or sets up configuration.
- The Downloader module might be used during installation and upgrade processes, fetching jars/build artifacts.
- CI/CD pipelines (denoted by .circleci and .github directories) are used to build, test, and package the application for deployment (e.g. via Docker or as a jar).

##### Architectural Patterns & Technical Choices
- Modular/Layered Architecture: The project breaks down into distinct modules (core, cli, downloader, ee) with specialized responsibilities.
- Plugin/Extensibility Pattern: The use of “authRecipe” modules and other feature-specific packages suggests a plugin-like mechanism where new authentication recipes can be added.

##### Relevant Technologies & Frameworks
- Java: The entire project is implemented in Java.
- Embedded HTTP Server: Likely using embedded Tomcat or similar lightweight server (as inferred from “webserver” package).
- Docker: The presence of Dockerfiles in CI directories and for distribution.
- Gradle: For building and dependency management.
- CI/CD scripts: GitHub and CircleCI workflows for continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        A1["Frontend SDK"]:::external
        A2["Backend SDK"]:::external
    end

    B["HTTP API & Webserver"]:::api
    A1 --> B
    A2 --> B

    C["SuperTokens Core (Authentication Engine)"]:::core
    B --> C

    D(("Storage Layer")):::storage
    C --> D

    E["CLI Module"]:::support
    F["Downloader Module"]:::support
    E --> C
    F --> C

    G["Enterprise Extensions (EE)"]:::enterprise
    G --> C

    subgraph "CI/CD Pipelines"
        H["CircleCI Pipeline"]:::cicd
        I["GitHub Actions"]:::cicd
    end
    H --> C
    I --> C

    click C "https://github.com/supertokens/supertokens-core/tree/master/src"
    click G "https://github.com/supertokens/supertokens-core/tree/master/ee"
    click E "https://github.com/supertokens/supertokens-core/tree/master/cli"
    click F "https://github.com/supertokens/supertokens-core/tree/master/downloader"
    click H "https://github.com/supertokens/supertokens-core/blob/master/.circleci"
    click I "https://github.com/supertokens/supertokens-core/blob/master/.github"

classDef external fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px
classDef api fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px
classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
classDef storage fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
classDef support fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
classDef enterprise fill:#FFE0B2,stroke:#E65100,stroke-width:2px
classDef cicd fill:#CFD8DC,stroke:#263238,stroke-width:2px
```
