# testcontainers/testcontainers-go architecture

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

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

## Overview

##### Main Components
- Client API & Test Integration: At the top, show the APIs that developers use in their test code. This is the “Testcontainers for Go” interface that exposes simple methods to define container configurations and start/stop containers.
- Core Engine (Container Lifecycle Manager): Illustrate the core package components (like container.go, docker_client.go, network.go, and the internal/core package) that handle container creation, lifecycle management, image management, and network operations.
- Wait Strategies & Utilities: Show the “wait” package that encapsulates various wait strategies (HTTP, file, TLS, exit codes, logs) to determine container readiness before tests run.
- Modules (Service Specific Extensions): Represent the numerous “modules” (e.g., modules/compose, modules/azure, modules/mongodb, etc.) which provide service-specific configuration and functionality. These modules abstract the container specifics for different technologies.
- Module Generator: Include the “modulegen” component which is designed to facilitate the extension of the library by generating new modules/templates.
- Logging & Configuration: Indicate the logging package (e.g., log/logger.go) and configuration management (internal/config) that ensure runtime behavior is traceable and configurable.

##### Relationships and Interactions
- Lifecycle Flow: Map the request from container creation, configuration application (via wait strategies and service-specific modules), container execution, and eventual teardown.

##### Architectural Patterns and Technologies
- Modularity: Clearly represent the modular design that splits generic container management from service-specific implementations through the modules directory.
- Separation of Concerns: Distinguish between the public API surface and the underlying internal implementation details using layering.
- Test Driven: Note the heavy use of unit and integration tests (as seen by the extensive test files) reinforcing that the design is test-centric.
- Go Ecosystem: Indicate that the entire system is built on Go, with clearly separated packages following idiomatic Go practices.

##### Additional Elements

This detailed approach will provide a clear, comprehensive view of the system’s architecture that accurately reflects the project’s purpose and structure. Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Interaction"
        API["Client API & Test Integration\n(testcontainers.go)"]:::public
    end

    subgraph "Core Engine"
        CORE["Container Lifecycle Manager\n(container.go, docker_client.go, network.go,\ninternal/core)"]:::core
    end

    subgraph "Wait Strategies & Utilities"
        WAIT["Wait Strategies & Utilities\n(wait/*.go)"]:::utility
    end

    subgraph "Service Specific Modules"
        MODULES["Service Specific Modules\n(modules/*)"]:::modules
    end

    subgraph "Module Generator"
        MODULEGEN["Module Generator\n(modulegen/*)"]:::modulegen
    end

    subgraph "Logging & Configuration"
        LOG["Logging\n(log/logger.go)"]:::logging
        CONFIG["Configuration\n(internal/config/*.go)"]:::config
    end

    subgraph "External Dependencies"
        DOCKER["Docker Engine"]:::external
        REGISTRY["Container Registries"]:::external
        CI["CI/CD Pipelines"]:::external
    end

    API -->|"Calls"| CORE
    CORE -->|"ManagesContainers"| WAIT
    CORE -->|"IntegratesWith"| MODULES
    CORE -->|"Utilizes"| LOG
    CORE -->|"Utilizes"| CONFIG
    CORE -->|"SendsCommandsTo"| DOCKER

    MODULEGEN -->|"Extends"| MODULES
    MODULEGEN -->|"Assists"| CORE

    WAIT -->|"SignalsReadiness"| CORE

    LOG -->|"LogsTo"| CORE
    CONFIG -->|"Configures"| CORE

    DOCKER -->|"ExecutesOn"| CORE
    CORE -->|"FetchesImagesFrom"| REGISTRY
    CI -->|"TriggersTestsFor"| API

    click API "https://github.com/testcontainers/testcontainers-go/blob/main/testcontainers.go"
    click CORE "https://github.com/testcontainers/testcontainers-go/blob/main/container.go"
    click CORE "https://github.com/testcontainers/testcontainers-go/blob/main/docker_client.go"
    click CORE "https://github.com/testcontainers/testcontainers-go/tree/main/internal/core"
    click WAIT "https://github.com/testcontainers/testcontainers-go/tree/main/wait"
    click MODULES "https://github.com/testcontainers/testcontainers-go/tree/main/modules"
    click MODULEGEN "https://github.com/testcontainers/testcontainers-go/tree/main/modulegen"
    click LOG "https://github.com/testcontainers/testcontainers-go/blob/main/log/logger.go"
    click CONFIG "https://github.com/testcontainers/testcontainers-go/tree/main/internal/config"

    classDef public fill:#f9c2ff,stroke:#333,stroke-width:2px;
    classDef core fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef utility fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef modules fill:#fff9c4,stroke:#333,stroke-width:2px;
    classDef modulegen fill:#ffcdd2,stroke:#333,stroke-width:2px;
    classDef logging fill:#b3e5fc,stroke:#333,stroke-width:2px;
    classDef config fill:#b2dfdb,stroke:#333,stroke-width:2px;
    classDef external fill:#eeeeee,stroke:#333,stroke-width:2px;
```
