# exercism/python architecture

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

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

## Overview

##### Project type and purpose
- This repo is not a web app or microservice but an **open-source content and tooling platform** (“Python Track”) for Exercism.
- It contains all the Markdown, JSON, Python code, templates, and scripts needed to define, generate, test, and maintain Python “concept” and “practice” exercises.

##### High-level file-structure analysis
- Top‐level directories:
- **concepts/** – source for “concept” exercises (small focused learning modules)
- **exercises/** – source for “practice” exercises, with subdirs for each problem, including metadata (`.meta`), docs, code & tests
- **bin/** – Python scripts to generate tests, fetch or validate config, run exercise‐generation pipelines
- **config/** – Jinja2 templates for generating README, instructions, test harnesses
- **.github/workflows/** – CI workflows for exercise‐checks, linting, configlet, dependence updates
- **docs/** – track‐level documentation and instructions for contributors
- **docker-compose.yml** – local development environment to spin up containers (test-runner, representer, analyzer)
- **config.json** – manifests which exercises are concept vs practice; ordering; dependencies

##### README insights
- Purpose: host all instructions, tests, code, and support files for Python exercises on Exercism
- Tooling: test-runner, representer, analyzer (track tooling), all run under Python 3.11.5
- CI: uses GitHub Actions to run “Exercises check” workflow, configlet, issue commenter, stale issues, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Workstation
    subgraph "Developer Workstation"
        Dev["Developer"]
        subgraph "Local Files"
            conceptsDir["concepts/"]:::content
            practiceDir["exercises/practice/"]:::content
            sharedDir["exercises/shared/"]:::content
            binDir["bin/"]:::tooling
            genTests["generate_tests.py"]:::tooling
            testScript["test_exercises.py"]:::tooling
            configDir["config/"]:::tooling
            configJson["config.json"]:::tooling
            docsDir["docs/"]:::tooling
            dockerCompose["docker-compose.yml"]:::tooling
        end
        Dev -->|"edits & tests locally"| conceptsDir
        Dev --> practiceDir
        Dev --> sharedDir
        Dev --> binDir
        Dev --> configDir
        Dev --> docsDir
        Dev --> configJson
        Dev --> dockerCompose
    end

    %% GitHub Repository
    subgraph "GitHub Repository"
        repoConcepts["concepts/"]:::content
        repoPractice["exercises/practice/"]:::content
        repoShared["exercises/shared/"]:::content
        repoBin["bin/"]:::tooling
        repoGenTests["bin/generate_tests.py"]:::tooling
        repoTestScript["bin/test_exercises.py"]:::tooling
        repoConfig["config/"]:::tooling
        repoConfigJson["config.json"]:::tooling
        repoDocs["docs/"]:::tooling
        repoDockerCompose["docker-compose.yml"]:::tooling
        repoWorkflows[".github/workflows/"]:::ci
        ciTest["test-runner.yml"]:::ci
        ciConfiglet["configlet.yml"]:::ci
        ciIssue["issue-commenter.yml"]:::ci
        ciStale["stale.yml"]:::ci
        ciDependabot["../dependabot.yml"]:::ci
    end

    Dev -->|"push to"| repoConcepts
    Dev --> repoPractice
    Dev --> repoShared
    Dev --> repoBin
    Dev --> repoConfig
    Dev --> repoDocs
    Dev --> repoConfigJson
    Dev --> repoDockerCompose
    Dev --> repoWorkflows

    repoWorkflows --> ciTest
    repoWorkflows --> ciConfiglet
    repoWorkflows --> ciIssue
    repoWorkflows --> ciStale
    repoWorkflows --> ciDependabot

    %% GitHub Actions CI
    subgraph "GitHub Actions CI"
        GHActions["Actions Runner"]:::ci
    end

    repoWorkflows -->|"triggers"| GHActions

    %% CI Containers
    subgraph "CI Containers (Docker)"
        testRunner["Test-Runner Container"]:::tooling
        representer["Representer Container"]:::tooling
        analyzer["Analyzer Container"]:::tooling
    end

    GHActions -->|"runs in"| testRunner
    GHActions -->|"runs in"| representer
    GHActions -->|"runs in"| analyzer

    %% External Services
    subgraph "External Services"
        exercism["Exercism Platform"]:::external
        discourse["Discourse Forum"]:::external
        dependabotSvc["Dependabot"]:::external
    end

    GHActions -->|"comments/issues"| discourse
    GHActions -->|"dependency updates"| dependabotSvc
    representer -->|"publishes content to"| exercism

    %% Click Events
    click conceptsDir "https://github.com/exercism/python/tree/main/concepts/"
    click practiceDir "https://github.com/exercism/python/tree/main/exercises/practice/"
    click sharedDir "https://github.com/exercism/python/tree/main/exercises/shared/"
    click genTests "https://github.com/exercism/python/blob/main/bin/generate_tests.py"
    click testScript "https://github.com/exercism/python/blob/main/bin/test_exercises.py"
    click configDir "https://github.com/exercism/python/tree/main/config/"
    click configJson "https://github.com/exercism/python/blob/main/config.json"
    click docsDir "https://github.com/exercism/python/tree/main/docs/"
    click dockerCompose "https://github.com/exercism/python/blob/main/docker-compose.yml"
    click repoWorkflows "https://github.com/exercism/python/tree/main/.github/workflows/"
    click ciTest "https://github.com/exercism/python/blob/main/.github/workflows/test-runner.yml"
    click ciConfiglet "https://github.com/exercism/python/blob/main/.github/workflows/configlet.yml"
    click ciIssue "https://github.com/exercism/python/blob/main/.github/workflows/issue-commenter.yml"
    click ciStale "https://github.com/exercism/python/blob/main/.github/workflows/stale.yml"
    click ciDependabot "https://github.com/exercism/python/blob/main/.github/dependabot.yml"

    %% Styles
    classDef content fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef tooling fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
