Repository Layout¶

Full annotated structure of this repository with details on what each component does and what breaks if removed.

For a quick overview, see the Repository Layout section in the main README.

Directory Tree¶

simple-python-boilerplate/
├── .github/                    # GitHub-specific configuration
│   ├── CODEOWNERS              # Code ownership rules
│   ├── copilot-instructions.md # GitHub Copilot project context
│   ├── dependabot.yml          # Automated dependency updates
│   ├── FUNDING.yml             # Sponsorship links
│   ├── ISSUE_TEMPLATE/         # Issue templates (bug, feature, etc.)
│   ├── labeler.yml             # Auto-label rules for PRs
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── workflows/              # GitHub Actions CI/CD (36 files)
│   │   ├── ci-gate.yml         # Single required check for branch protection
│   │   ├── lint-format.yml     # Ruff linting and formatting
│   │   ├── release.yml         # Build artifacts on tag push
│   │   ├── release-please.yml  # Automated Release PR creation
│   │   ├── test.yml            # Pytest across Python versions
│   │   └── ...                 # Security, docs, maintenance workflows
│   └── workflows-optional/     # Opt-in workflows (copy to workflows/)
│
├── db/                         # Database assets (optional)
│   ├── migrations/             # Schema migration scripts
│   ├── queries/                # Reusable SQL queries
│   ├── seeds/                  # Sample/test data
│   └── schema.sql              # Database schema definition
│
├── docs/                       # Project documentation
│   ├── adr/                    # Architecture Decision Records
│   ├── blueprints/             # Proposed design shapes
│   ├── design/                 # Architecture and database design
│   ├── development/            # Developer guides
│   ├── explorations/           # Early-stage idea evaluation
│   ├── guide/                  # Getting-started, troubleshooting
│   ├── implementation-plans/   # Step-by-step execution details
│   ├── notes/                  # Personal learning notes
│   ├── reference/              # API reference (mkdocstrings)
│   ├── templates/              # Reusable file templates
│   │   # Design lifecycle (optional):
│   │   #   idea/problem → explorations/
│   │   #   proposed design → blueprints/
│   │   #   decision locked in → adr/
│   │   #   build steps → implementation-plans/
│   ├── index.md                # MkDocs homepage
│   ├── labels.md               # GitHub label catalog
│   ├── release-policy.md       # Versioning and release policy
│   ├── releasing.md            # How to create releases
│   ├── repo-layout.md          # This file
│   ├── sbom.md                 # Software Bill of Materials guide
│   ├── tooling.md              # Tooling overview
│   └── workflows.md            # GitHub Actions reference
│
├── experiments/                # Scratch space for exploration
│
├── labels/                     # GitHub label definitions
│   ├── baseline.json           # Core labels (18)
│   └── extended.json           # Full label set (62)
│
├── mkdocs-hooks/               # MkDocs build hooks
│   ├── repo_links.py           # Rewrite repo-relative links
│   ├── generate_commands.py    # Auto-regenerate command reference
│   └── include_templates.py    # Include file templates in docs
│
├── repo_doctor.d/              # Diagnostic check definitions
│   └── *.toml                  # Check configs (ci, docs, python, etc.)
│
├── scripts/                    # Developer/maintenance scripts
│   ├── apply_labels.py         # Sync labels to GitHub
│   ├── bootstrap.py            # One-command setup for fresh clones
│   ├── customize.py            # Interactive project customization
│   ├── clean.py                # Remove build artifacts/caches
│   ├── doctor.py               # Diagnostics bundle for bug reports
│   ├── env_doctor.py           # Environment health check
│   ├── git_doctor.py           # Git health dashboard and config manager
│   ├── repo_doctor.py          # Repository structure health checks
│   ├── precommit/              # Pre-commit helper scripts
│   └── sql/                    # SQL utility scripts
│
├── src/                        # Source code (package root)
│   └── simple_python_boilerplate/
│       ├── __init__.py         # Package initialization, version
│       ├── _version.py         # Generated by hatch-vcs (git tag version)
│       ├── py.typed            # PEP 561 type stub marker
│       ├── api.py              # Programmatic interface
│       ├── cli.py              # Command-line interface
│       ├── engine.py           # Core business logic
│       ├── main.py             # Entry points
│       ├── dev_tools/          # Development utilities
│       └── sql/                # SQL query assets
│
├── tests/                      # Test suite
│   ├── conftest.py             # Shared fixtures
│   ├── integration/            # Integration tests
│   └── unit/                   # Unit tests
│
├── var/                        # Runtime/generated files
│   └── app.example.sqlite3     # Example database file
│
├── .editorconfig               # Cross-editor formatting rules (indent, EOL, whitespace)
├── .gitattributes              # Git file handling (line endings, diff drivers, binary detection)
├── .gitignore                  # Files excluded from git
├── .gitmessage.txt             # Commit message template (Conventional Commits)
├── .markdownlint-cli2.jsonc    # markdownlint rule overrides
├── .pre-commit-config.yaml     # Pre-commit hook configuration
├── .release-please-manifest.json # Version tracker for release-please
├── _typos.toml                 # Typos spellchecker exceptions
├── CHANGELOG.md                # Version history
├── CODE_OF_CONDUCT.md          # Community guidelines
├── Containerfile               # Multi-stage container build
├── CONTRIBUTING.md             # Contribution guidelines
├── codecov.yml                 # Code coverage config
├── docker-compose.yml          # Container orchestration
├── git-config-reference.md     # Generated git config reference (git_doctor.py --export-config)
├── LICENSE                     # Project license (Apache-2.0)
├── mkdocs.yml                  # Documentation site config
├── pyproject.toml              # Project metadata and tool config
├── README.md                   # Project overview
├── release-please-config.json  # Release automation config
├── requirements.txt            # Production dependencies
├── requirements-dev.txt        # Development dependencies
├── SECURITY.md                 # Security policy
├── simple-python-boilerplate.code-workspace  # VS Code workspace
└── Taskfile.yml                # Task runner shortcuts

Component Details¶

Core (Required)¶

These are essential for the package to function.

Path	Purpose	What Breaks If Removed
`src/simple_python_boilerplate/`	Package source code	Everything — no package to import
`src/simple_python_boilerplate/__init__.py`	Package marker, exports version	Package won't be recognized
`pyproject.toml`	Build config, metadata, tool settings	Can't install, build, or configure tools
`LICENSE`	Legal terms	License compliance issues

Testing¶

Path	Purpose	What Breaks If Removed
`tests/`	Test suite	No tests to run, CI fails
`tests/conftest.py`	Shared fixtures	Fixtures unavailable across tests
`tests/unit/`	Unit tests	Reduced test coverage
`tests/integration/`	Integration tests	Can't verify component interactions

CI/CD¶

Path	Purpose	What Breaks If Removed
`.github/workflows/test.yml`	Run tests on push/PR	No automated testing
`.github/workflows/lint-format.yml`	Code quality checks	Formatting issues slip through
`.github/workflows/release.yml`	Build on version tags	Manual build required
`.github/dependabot.yml`	Dependency updates	Manual dependency management

See workflows.md for full workflow documentation.

Documentation¶

Path	Purpose	What Breaks If Removed
`README.md`	Project overview	No landing page
`CONTRIBUTING.md`	Contribution guide	Contributors lack guidance
`docs/`	Detailed documentation	Missing context for developers
`docs/adr/`	Decision records	Lost architectural context
`docs/explorations/`	Early-stage idea evaluation	Lost exploration context
`docs/blueprints/`	Proposed design shapes	Lost design context
`docs/implementation-plans/`	Execution details	Lost implementation context
`CHANGELOG.md`	Version history	No release notes

Development Experience¶

Path	Purpose	What Breaks If Removed
`.pre-commit-config.yaml`	Pre-commit hooks	Local checks disabled
`requirements-dev.txt`	Dev dependencies list	Unclear what to install
`.gitignore`	Exclude generated files	Caches committed to git
`.gitattributes`	Line ending normalization, diff drivers, binary file detection, linguist stats	Cross-platform line ending mismatches
`.editorconfig`	Cross-editor indent, charset, EOL, trailing whitespace rules	Inconsistent formatting across editors
`.gitmessage.txt`	Commit message template (Conventional Commits)	No guided commit format
`git-config-reference.md`	Generated git config reference (via `git_doctor.py --export-config`)	Regenerated on demand; informational only

Optional Components¶

These can be removed without breaking core functionality.

Path	Purpose	Safe to Remove?
`db/`	Database assets	✅ If not using a database
`experiments/`	Scratch space	✅ Personal exploration
`mkdocs-hooks/`	MkDocs hooks	✅ If no repo-relative links in docs
`labels/`	GitHub labels	✅ Manual label management
`scripts/`	Utility scripts	✅ Convenience only
`repo_doctor.d/`	Diagnostics	✅ Custom health checks only
`var/`	Runtime files	✅ Example data
`docs/notes/`	Personal notes	✅ Learning reference
`docs/templates/`	File templates	✅ Copy as needed

Source Code Architecture¶

src/simple_python_boilerplate/
├── __init__.py     # Package exports, version
├── _version.py     # Generated by hatch-vcs (do not edit)
├── py.typed        # PEP 561 marker for type checkers
├── main.py         # Entry points (thin wrappers)
├── cli.py          # CLI argument parsing
├── engine.py       # Core business logic
├── api.py          # Programmatic interface
├── dev_tools/      # Development utilities
│   └── __init__.py
└── sql/            # SQL query assets
    ├── __init__.py
    ├── example_query.sql
    └── README.md

Data Flow¶

User → main.py → cli.py → engine.py → result
              ↘ api.py ↗

Key Principle¶

Logic lives in engine.py. Interfaces (cli.py, api.py) adapt it.

See docs/notes/learning.md for detailed architecture notes.

Configuration Files¶

pyproject.toml Sections¶

Section	Purpose
`[build-system]`	How to build the package
`[project]`	Name, version, dependencies
`[project.optional-dependencies]`	Dev/test/docs extras
`[project.scripts]`	CLI entry points
`[tool.hatch.*]`	Environments, version (hatch-vcs), build
`[tool.ruff]`	Linter and formatter configuration
`[tool.mypy]`	Type checker configuration
`[tool.pytest]`	Test runner configuration
`[tool.coverage.*]`	Coverage measurement and reporting
`[tool.bandit]`	Security scanner configuration
`[tool.deptry]`	Unused/missing dependency checker
`[tool.commitizen]`	Conventional commit validation

Other Config Files¶

File	Tool	Purpose
`.pre-commit-config.yaml`	pre-commit	Git hook definitions
`.github/dependabot.yml`	Dependabot	Dependency update rules
`_typos.toml`	typos	Spellcheck exceptions
`.markdownlint-cli2.jsonc`	markdownlint	Markdown lint overrides
`Taskfile.yml`	Task	Task runner shortcuts
`mkdocs.yml`	MkDocs	Documentation site
`codecov.yml`	Codecov	Coverage reporting
`release-please-config.json`	release-please	Release automation
`Containerfile`	Podman/Docker	Container build
`docker-compose.yml`	Docker Compose	Container orchestration
`requirements.txt`	pip	Production dependencies
`requirements-dev.txt`	pip	Development dependencies

Naming Conventions¶

Pattern	Meaning	Example
`test_*.py`	Test file	`test_example.py`
`conftest.py`	Shared pytest fixtures	`tests/conftest.py`
`_*.py`	Internal/private module	`_version.py`
`py.typed`	PEP 561 type marker	Enables type-checking for package
`.example.`	Example/template file	`app.example.sqlite3`
`__init__.py`	Package marker	Required in all packages
`__pycache__/`	Python bytecode cache	Never commit
`_version.py`	Generated version	Created by hatch-vcs (do not edit)
`README.md`	Directory documentation	One per directory (convention)

What to Remove When Adopting¶

If you're using this template, consider removing:

Path	When to Remove
`docs/notes/`	Optional — keep as reference or remove
`experiments/`	After exploration
`var/app.example.sqlite3`	Replace with your data
`docs/templates/`	After copying what you need
`db/`	If not using a database