How supertokens/supertokens-core works
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.