# exercism/go architecture

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

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

## Overview

##### Main Components
- Exercises Repository: This is the core of the track. It contains multiple top-level directories such as “concepts” (for foundational concepts) and “exercises” (sublabeled into “concept” and “practice” sets). Each exercise is self-contained, with its own files for the exercise’s stub code, tests, and a “.meta” subdirectory for metadata, hints, and generator scripts.
- Generator & Synchronization Tools: There are dedicated directories and scripts – for example, the “gen” folder and the “gomod-sync” directory – that assist in generating test cases from the canonical problem specifications and synchronizing go.mod files across exercises.
- Build and CI Infrastructure: The “.github” directory holds CI workflow definitions (for Configlet, test runners, etc.) that ensure automated testing and validation. Additionally, the “bin” directory houses helper scripts (like fetch-golangci-lint, run-tests, run-generators) that are used during development.
- Documentation and Reference Resources: Inside “docs” and “reference” directories you find learning guides, installation instructions, and concept explanations for language features.

##### Relationships and Interactions
- Each individual exercise (found throughout “exercises/concept” and “exercises/practice”) is connected to its respective metadata in the “.meta” folder; these are in turn used by the generator tools (in the “gen” directory and .meta/gen.go files) to produce test case files.
- The “gomod-sync” tool interacts with all the go.mod files across exercises. It reads configuration (from gomod-sync/config.json) and updates individual module files, ensuring consistency.
- The CI services (configured in “.github/workflows”) automatically run tests (triggered by scripts in “bin”) and perform tasks like synchronizing exercise metadata or running linters, linking back to the code in exercises.
- The repository uses external tools – like configlet for syncing exercise metadata (from problem-specifications on GitHub) – and these can be depicted as external connectors.
- The “reference” folder holds static documentation that connects to the overall exercise functionality by supporting both contributors and learners.

##### Architectural Patterns and Design Principles
- Modularity: Each exercise is self-contained. This modularity is explicitly visible in the directory layout, where each exercise has its own tests, metadata, example solution, and sometimes even its own generator.
- Code Generation: A key design principle is the dynamic generation of test cases via “.meta/gen.go” scripts and centralized generator tools. This ensures consistency with the canonical problem specifications.
- CI/CD and Automated Validation: By embedding multiple CI workflows in the “.github” directory and providing scripts in “bin,” the system reinforces continuous integration, testing, and synchronization.
- Separation of Concerns: The repository cleanly segregates concerns such as exercise definitions, tooling for generation/synchronization, metadata management, and continuous integration.
- Externalized Configuration: Files like config.json (both at the project root and under “gomod-sync”) and metadata files in .meta directories ensure that configurations are separate from business logic.

##### Technologies, Frameworks, or Libraries
- The project is entirely written in Go and relies only on the standard library.
- External tooling includes “configlet” (a tool for Exercism exercise synchronization) and “golangci-lint” for linting.
- The use of GitHub Actions for CI is central as indicated by all configuration files under “.github/workflows.”
- The repository also relies on standard file tree structures to manage exercises, documentation, and generators.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: External and Documentation Resources
    ExternalPS["problem-specifications (external)"]:::external

    subgraph "Documentation & Reference Resources"
        Docs["Docs"]:::documentation
        Ref["Reference"]:::documentation
    end

    %% Middle Layer: Exercises Repository
    subgraph "Exercises Repository"
        Concepts["Concepts (concepts/)"]:::repository
        Exercises["Exercises (exercises/)"]:::repository
    end

    %% Bottom Layer: Tooling & CI Infrastructure
    subgraph "Tooling & CI Infrastructure"
        Gen["Generator & Sync Tools (gen/)"]:::tools
        Gomod["gomod-sync (gomod-sync/)"]:::tools
        Github["CI Workflows (.github/)"]:::ci
        Bin["CI Scripts (bin/)"]:::ci
    end

    %% Connections between layers
    ExternalPS -->|"feeds"| Gen
    Gen -->|"updates"| Concepts
    Gen -->|"updates"| Exercises
    Gomod -->|"syncs"| Concepts
    Gomod -->|"syncs"| Exercises
    Gen -->|"triggers"| Github
    Github -->|"runs"| Bin
    Github -->|"tests"| Concepts
    Github -->|"tests"| Exercises
    Docs -->|"guides"| Concepts
    Ref -->|"guides"| Exercises

    %% Click Events
    click Concepts "https://github.com/exercism/go/tree/main/concepts/"
    click Exercises "https://github.com/exercism/go/tree/main/exercises/"
    click Gen "https://github.com/exercism/go/tree/main/gen/"
    click Gomod "https://github.com/exercism/go/tree/main/gomod-sync/"
    click Github "https://github.com/exercism/go/tree/main/.github/"
    click Bin "https://github.com/exercism/go/tree/main/bin/"
    click Docs "https://github.com/exercism/go/tree/main/docs/"
    click Ref "https://github.com/exercism/go/tree/main/reference/"

    %% Styles
    classDef external fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef repository fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef tools fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef ci fill:#577590,stroke:#fff,stroke-width:2px;
    classDef documentation fill:#8ecae6,stroke:#000,stroke-width:2px;
```
