# testcontainers/testcontainers-java architecture

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

- Interactive diagram: https://gitdiagram.com/testcontainers/testcontainers-java
- Repository: https://github.com/testcontainers/testcontainers-java

## Overview

##### Main Components / Layers
- Core API: Represented mostly by the “core” directory. This is where the main abstractions reside (e.g., classes like DockerClientFactory, Testcontainers, container abstractions, wait strategies, utility classes, etc.), and where the common behavior to launch and manage Docker containers is implemented.
- Container Modules: The “modules” directory is split into many submodules such as “cassandra,” “mysql,” “postgresql,” “mssqlserver,” “neo4j,” “clickhouse,” “mongodb,” “oracle” variants, “redis,” “vault,” etc. Each module extends the core API to enable support for a particular Docker container type. Indicate a node for each module or group them by category (databases, messaging, specialized services) to avoid clutter.
- Build & CI Infrastructure: The project uses Gradle as its build system (see build.gradle files, gradlew, and gradle wrapper directories) as well as a comprehensive CI setup (directories like .github, .circleci, azure-pipelines.yml, etc.) for automated testing and release processes.
- Test Infrastructure: There are extensive test folders in nearly every module (like “core/src/test,” “test-support,” “smoke-test”) which validate functionality. There is also “junit-jupiter” and support directories that integrate with JUnit tests.
- Documentation & Examples: The “docs” and “examples” directories show usage patterns and provide supporting documentation for end users.
- Configuration & Service SPI: Configuration files and service provider files (for example, in META-INF/services) indicate a pluggable/extension approach following the Service Provider Interface pattern.

##### Relationships and Data Flow
- The Core API is at the heart of the system. It defines the interfaces, base classes, and common utilities to interact with Docker and manage container lifecycles.
- The testing layer uses the Core API (and optionally specific container modules) to spin up containers for integration tests – indicate a feedback loop where tests trigger container startup/cleanup.
- The build/CI infrastructure orchestrates code compilation, module testing, and assembling releases – it interacts with all components using build scripts and configuration files.

##### Architectural Patterns and Design Principles
- Dependency Inversion: The modules rely on abstractions provided by the core—this minimizes coupling and allows for external extension.
- Test-Driven and Integration-Test Driven Design: The file structure shows a heavy emphasis on tests (unit tests, integration tests, smoke tests), which support the self-validating principle of the library.

##### Technologies, Frameworks, and Libraries
- Java and Gradle are used as the primary language and build tool.
- JUnit (and alternatively TestNG, Spock, or JUnit Jupiter) are part of the integration test ecosystem.
- Docker (and its related APIs) provides runtime support for container orchestration.
- GitHub Actions, CircleCI, and Azure pipelines power the CI/CD process.
- The usage of service registration via META-INF/services underpins the SPI design.

##### Additional Elements
- Flow for a typical test execution. For example, “Test Framework” (JUnit) invokes the “Testcontainers API” (Core), which in turn initializes a specific container from one of the modules, interacts with the Docker Engine via a client (a sub-component inside the core), and returns results.
- Optionally, indicate the "Build and Release Pipeline" layer which picks up the code from various modules, runs tests, and packages the library.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core API Layer
    subgraph "Core API"
        core["Core Container API"]:::core
        spi["Configuration & Service SPI"]:::spi
    end

    %% Container Modules Layer
    subgraph "Container Modules"
        modules["Container Modules"]:::modules
    end

    %% Build & CI Infrastructure Layer
    subgraph "Build & CI Infrastructure"
        ci["Build & CI Infrastructure"]:::ci
    end

    %% Test Infrastructure Layer
    subgraph "Test Infrastructure"
        test["Test Infrastructure"]:::test
    end

    %% Documentation & Examples Layer
    subgraph "Documentation & Examples"
        docs["Documentation & Examples"]:::docs
    end

    %% Relationships
    modules -->|"extends"| core
    core -->|"SPI registration"| spi
    test -->|"invokes"| core
    ci -->|"orchestrates"| core
    ci -->|"orchestrates"| modules
    docs -->|"documents"| core

    %% Click Events
    click core "https://github.com/testcontainers/testcontainers-java/tree/main/core/src/main/java/org/testcontainers"
    click modules "https://github.com/testcontainers/testcontainers-java/tree/main/modules/"
    click ci "https://github.com/testcontainers/testcontainers-java/blob/main/.circleci/, .github/, build.gradle, gradlew, gradle/wrapper, azure-pipelines.yml"
    click test "https://github.com/testcontainers/testcontainers-java/tree/main/core/src/test, modules/*/src/test, smoke-test/, test-support/"
    click docs "https://github.com/testcontainers/testcontainers-java/tree/main/docs/ and examples/"
    click spi "https://github.com/testcontainers/testcontainers-java/tree/main/core/src/main/resources/META-INF/services"

    %% Styles
    classDef core fill:#aaddff,stroke:#339,stroke-width:2px;
    classDef modules fill:#ccffcc,stroke:#33a,stroke-width:2px;
    classDef ci fill:#ffcccc,stroke:#933,stroke-width:2px;
    classDef test fill:#ffffcc,stroke:#993,stroke-width:2px;
    classDef docs fill:#ffdead,stroke:#996,stroke-width:2px;
    classDef spi fill:#baffb2,stroke:#0a0,stroke-width:2px;
```
