# sourcery-ai/python-best-practices-cookiecutter architecture

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

- Interactive diagram: https://gitdiagram.com/sourcery-ai/python-best-practices-cookiecutter
- Repository: https://github.com/sourcery-ai/python-best-practices-cookiecutter

## Overview

##### Project type and purpose
- This is not a runtime application but a “cookiecutter” template project. Its purpose is to generate new Python projects that follow a set of best practices (testing, linting, formatting, CI/CD, Dockerization, etc.).

##### File structure
- Top‐level:
- cookiecutter.json – defines user‐prompted variables
- hooks/ – pre_generation and post_generation Python scripts
- LICENSE, README.md, cookiecutter.json
- Template folder “{{cookiecutter.repo_name}}/” contains:
- Configuration files (.coveragerc, .pre‐commit-config.yaml, setup.cfg, Pipfile, Dockerfile, .editorconfig, .dockerignore, .gitignore)
- CI workflows (.github/workflows/test.yml, publish-docker.yml)
- Code scaffold:
– {{repo_name}}/__main__.py and module file {{repo_name}}.py
– test/ directory with pytest starter
- Hooks scripts execute before and after project generation to customize or validate context.

##### README for additional insights
- Lists the best‐practices enforced: pytest, black, isort, mypy, flake8, pre-commit, Docker, GitHub Actions.
- Quickstart shows the user flow: pipx → cookiecutter → pipenv → pre-commit hooks → start coding.

##### Detailed capture of essential architectural elements
- In the generated side, show subcomponents: source package, tests, CI workflows, Dockerfile, pre-commit hooks.
- Decision points if any (e.g., conditional steps in hooks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    User["User"]:::user
    Developer["Developer"]:::user

    %% Template Engine Layer
    subgraph "Template Engine Layer"
        CookiecutterCLI["Cookiecutter CLI"]:::core
        CookiecutterJSON["cookiecutter.json"]:::artifact
        HooksPre["pre_gen_project.py"]:::core
        HooksPost["post_gen_project.py"]:::core
        TemplateFiles["Template Root {{cookiecutter.repo_name}}/"]:::artifact
    end

    %% Generated Project Layer
    subgraph "Generated Project Layer"
        subgraph "Source Package"
            MainModule["__main__.py"]:::artifact
            ModuleFile["{{cookiecutter.repo_name}}.py"]:::artifact
        end
        subgraph "Testing Starter"
            TestInit["test/__init__.py"]:::artifact
            TestFile["test/test_{{cookiecutter.repo_name}}.py"]:::artifact
        end
        subgraph "Configuration Files"
            ConfigCover[".coveragerc"]:::artifact
            ConfigSetup["setup.cfg"]:::artifact
            ConfigPreCommit[".pre-commit-config.yaml"]:::artifact
            ConfigEditor[".editorconfig"]:::artifact
            ConfigGitignore[".gitignore"]:::artifact
            ConfigDockerignore[".dockerignore"]:::artifact
            ConfigPipfile["Pipfile"]:::artifact
        end
        subgraph "CI-as-Code Workflows"
            WorkflowTest["test.yml"]:::artifact
            WorkflowDocker["publish-docker.yml"]:::artifact
        end
        Dockerfile["Dockerfile"]:::artifact
        DocsReadme["README.md"]:::artifact
        DocsLicense["LICENSE"]:::artifact
    end

    %% External Integrations
    subgraph "External Integrations"
        GitHub["GitHub"]:::external
        PreCommit["pre-commit (local)"]:::external
        DockerRegistry["Docker Registry"]:::external
        PyPI["PyPI"]:::external
    end

    %% Flows
    User -->|"invoke via pipx"| CookiecutterCLI
    CookiecutterCLI -->|"loads template definition"| CookiecutterJSON
    CookiecutterCLI -->|"loads template files"| TemplateFiles
    CookiecutterCLI -->|"runs pre-gen hook"| HooksPre
    HooksPre -->|"process template"| TemplateFiles
    TemplateFiles -->|"render files"| HooksPost
    HooksPost -->|"generate project skeleton"| MainModule
    HooksPost --> MainModule
    MainModule --> ModuleFile
    HooksPost --> TestInit
    HooksPost --> TestFile
    HooksPost --> ConfigCover
    HooksPost --> ConfigSetup
    HooksPost --> ConfigPreCommit
    HooksPost --> ConfigEditor
    HooksPost --> ConfigGitignore
    HooksPost --> ConfigDockerignore
    HooksPost --> ConfigPipfile
    HooksPost --> WorkflowTest
    HooksPost --> WorkflowDocker
    HooksPost --> Dockerfile
    HooksPost --> DocsReadme
    HooksPost --> DocsLicense
    WorkflowTest -->|"on push/tag"| GitHub
    Developer -->|"commit & push"| GitHub
    Developer -->|"run hooks"| PreCommit
    GitHub -->|"trigger test workflow"| WorkflowTest
    WorkflowDocker -->|"on release tag"| DockerRegistry
    WorkflowDocker -->|"publish package"| PyPI

    %% Click Events
    click CookiecutterJSON "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/cookiecutter.json"
    click HooksPre "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/hooks/pre_gen_project.py"
    click HooksPost "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/hooks/post_gen_project.py"
    click TemplateFiles "https://github.com/sourcery-ai/python-best-practices-cookiecutter/tree/main/{{cookiecutter.repo_name}}/"
    click ConfigCover "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.coveragerc"
    click ConfigSetup "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/setup.cfg"
    click ConfigPreCommit "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.pre-commit-config.yaml"
    click ConfigEditor "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.editorconfig"
    click ConfigGitignore "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.gitignore"
    click ConfigDockerignore "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.dockerignore"
    click ConfigPipfile "https://github.com/sourcery-ai/python-best-practices-cookiecutter/tree/main/{{cookiecutter.repo_name}}/Pipfile"
    click WorkflowTest "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.github/workflows/test.yml"
    click WorkflowDocker "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/.github/workflows/publish-docker.yml"
    click Dockerfile "https://github.com/sourcery-ai/python-best-practices-cookiecutter/tree/main/{{cookiecutter.repo_name}}/Dockerfile"
    click MainModule "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/__main__.py"
    click ModuleFile "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py"
    click TestInit "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/test/__init__.py"
    click TestFile "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/test/test_{{cookiecutter.repo_name}}.py"
    click DocsReadme "https://github.com/sourcery-ai/python-best-practices-cookiecutter/blob/main/{{cookiecutter.repo_name}}/README.md"
    click DocsLicense "https://github.com/sourcery-ai/python-best-practices-cookiecutter/tree/main/{{cookiecutter.repo_name}}/LICENSE"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef artifact fill:#C7F9B1,stroke:#333,stroke-width:1px
    classDef external fill:#FDBE87,stroke:#333,stroke-width:1px
    classDef user fill:#D3D3D3,stroke:#333,stroke-width:1px
```
