cleverclaude-core/docs/index.md

Boilerplate

Modern Python 3.13 micro-service starter with bleeding-edge tooling and 60-second cold clone to green CI.

This is a completely modernized Python starter project that replaces legacy setuptools-based workflows with cutting-edge tools and practices. Built for Python 3.11-3.13 with strict type safety, behavior-driven development, and cloud-native deployment.

Features

🚀 Performance & Speed

• 60-second cold clone to green CI - Lightning-fast feedback loop
• Rust-powered tools - uv (10-100x faster than pip) + ruff (10-100x faster than flake8/black)
• Optimized containers - Multi-stage Docker builds with 20MB runtime images
• Parallel testing - nox runs tests across Python versions concurrently

🔒 Type Safety & Quality

• Strict type checking - Pyright in strict mode catches bugs at development time
• Single-tool quality - Ruff replaces 5+ legacy tools (black, isort, flake8, pylint, bandit)
• Pre-commit hooks - Automatic code formatting and linting on commit
• Import organization - Consistent import sorting across the codebase

🧪 Modern Testing

• BDD testing - Natural language specs with Behave (.feature files)
• Property-based fuzzing - Hypothesis automatically discovers edge cases
• Cross-version testing - Automated testing on Python 3.11, 3.12, and 3.13
• Fast feedback - Tests run in seconds, not minutes

🐳 Development Experience

• Development containers - Instant setup with VS Code & GitHub Codespaces
• Shell integration - Pre-configured aliases and shortcuts
• Hot reloading - Live documentation server and development tools
• Consistent environments - Same tools locally, in CI, and production

☁️ Cloud Native

• Kubernetes ready - Production Helm charts with HPA and monitoring
• Container security - Non-root execution, read-only filesystem, minimal attack surface
• Observability - Health checks, metrics endpoints, structured logging
• GitOps friendly - Declarative configuration and automated deployments

📚 Documentation

• Modern docs - Material for MkDocs with dark mode and search
• Versioned docs - Mike handles documentation versioning automatically
• Living specs - BDD scenarios serve as both tests and documentation
• API docs - Auto-generated from type hints and docstrings

Quick Start

Option 1: Development Container (Recommended)

Get started in 2-3 minutes with zero configuration:

# Clone and open in VS Code
git clone https://git.cleverthis.com/cleverthis/base/base-python
cd base-python && code .

# Click "Reopen in Container" when prompted
# Wait 2-3 minutes for automatic setup
# Everything is ready! Start coding 🎉

# Verify setup
python --version  # Python 3.13.x
behave -q         # Run BDD tests
nox              # Run full test suite

What you get:

• Python 3.13 with all dependencies pre-installed
• VS Code with 15+ relevant extensions
• Pre-commit hooks configured
• Shell aliases and shortcuts
• Docker-in-Docker for building containers
• kubectl and Helm for Kubernetes development

Option 2: GitHub Codespaces

Develop in your browser with zero local setup:

1. Go to repository → Code → Codespaces → Create codespace
2. Wait 2-3 minutes for automatic environment setup
3. Start coding immediately with full IDE experience!

Benefits:

• No local dependencies required
• 4-core, 8GB RAM development environment
• 32GB persistent storage
• 60 hours/month free for personal accounts

Option 3: Local Setup

For developers who prefer local development:

# Install uv (Rust-powered package manager)
pip install uv

# Clone and setup
git clone https://git.cleverthis.com/cleverthis/base/base-python
cd base-python

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Verify installation
python --version  # Should show Python 3.11+
ruff --version    # Linting and formatting
pyright --version # Type checking
behave --version  # BDD testing

# Run tests to verify everything works
behave -q
nox

Development Workflow

Core Commands

# Code quality (lightning fast!)
nox -s format     # Format code with ruff
nox -s lint       # Lint code with ruff  
nox -s typecheck  # Type check with pyright

# Testing
nox -s behave     # Run BDD tests on all Python versions
behave -q         # Quick BDD test run
behave -t @wip    # Run only work-in-progress scenarios

# Documentation
nox -s docs       # Build documentation
nox -s serve_docs # Serve docs locally at http://localhost:3000

# Everything
nox               # Run all quality checks and tests

Advanced Commands

# Package building
nox -s build      # Build wheel package
python -m build   # Alternative build command

# Pre-commit hooks
pre-commit run --all-files  # Run hooks on all files
pre-commit autoupdate       # Update hook versions

# Development shortcuts (available in devcontainer)
dev-test          # Alias for nox -s behave
dev-lint          # Alias for nox -s lint
dev-format        # Alias for nox -s format
dev-all           # Alias for nox

Modern Technology Stack

Core Tools

Component	Legacy Tool	Modern Tool	Benefits
Package Manager	pip	uv	10-100x faster installs, better dependency resolution
Code Formatting	black	ruff format	10-100x faster, same output as black
Import Sorting	isort	ruff check --select I	10-100x faster, integrated with linting
Linting	flake8, pylint	ruff check	Single tool replaces 5+ legacy tools
Type Checking	mypy	pyright	5-10x faster, better Python 3.13 support
Testing	pytest	behave + hypothesis	Natural language specs + automatic fuzzing
Build System	setuptools	hatchling	PEP 621 compliant, modern metadata
Automation	tox	nox	Python-based, more flexible configuration
Documentation	Sphinx	MkDocs Material	Modern UI, dark mode, better mobile support

Development Environment

Feature	Legacy	Modern	Benefits
Setup	Manual installation	Dev Container	Zero-config, consistent across team
IDE Integration	Basic Python extension	15+ extensions	Complete development experience
Environment Management	virtualenv + pip	uv venv	Faster creation and package management
Code Quality	Multiple tools	Single ruff command	Unified workflow, much faster

Project Architecture

Directory Structure

boilerplate/
├── src/boilerplate/           # 📦 Source code with type hints
│   ├── __init__.py           # Package initialization  
│   ├── __main__.py           # Entry point for python -m
│   └── cli.py                # Command-line interface
├── features/                  # 🧪 BDD test specifications
│   ├── environment.py        # Test environment setup
│   ├── steps/               # Step definitions
│   │   └── cli_steps.py     # CLI test steps with Hypothesis
│   └── cli.feature          # Gherkin feature specifications
├── k8s/                      # ☸️ Kubernetes deployment
│   ├── Chart.yaml           # Helm chart metadata
│   ├── values.yaml          # Default configuration values
│   └── templates/           # Kubernetes resource templates
│       ├── deployment.yaml  # Pod deployment configuration
│       ├── service.yaml     # Service definition
│       ├── hpa.yaml         # Horizontal Pod Autoscaler
│       └── configmap.yaml   # Configuration management
├── .devcontainer/            # 🐳 Development container setup
│   ├── devcontainer.json    # VS Code dev container configuration
│   ├── Dockerfile           # Development environment image
│   ├── post-create.sh       # Automatic setup script
│   └── bashrc-append.sh     # Shell customizations and aliases
├── .forgejo/workflows/       # 🚀 CI/CD pipeline automation
│   └── ci.yml               # Automated testing and building
├── docs/                     # 📚 Documentation source
│   ├── index.md             # Documentation homepage
│   ├── devcontainer.md      # Development container guide
│   ├── behaviour.md         # BDD specifications documentation
│   ├── api.md               # API reference documentation
│   └── deployment.md        # Kubernetes deployment guide
├── scripts/                  # 🔧 Utility scripts
│   └── deploy_docs.sh       # Documentation deployment automation
├── pyproject.toml           # 📋 Modern project configuration (PEP 621)
├── noxfile.py               # 🔄 Test automation sessions
├── behave.ini               # 🧪 BDD test runner configuration
├── pyrightconfig.json       # 🔍 Type checker strict configuration
├── mkdocs.yml               # 📖 Documentation site configuration
├── Dockerfile               # 🐳 Production container image
├── .dockerignore            # Docker build context exclusions
├── .gitignore               # Git version control exclusions
├── .pre-commit-config.yaml  # Git pre-commit hooks configuration
├── README.md                # Project overview and quick start
├── CHANGELOG.md             # Version history and changes
└── LICENSE                  # Apache 2.0 open source license

Configuration Files Explained

pyproject.toml - Modern Python Project Configuration

Replaces setup.py, setup.cfg, requirements.txt, and more:

[build-system]
requires = ["hatchling>=1.21.0"]
build-backend = "hatchling.build"

[project]
name = "boilerplate"
version = "0.1.0"
dependencies = ["click>=8.1.7"]

[project.optional-dependencies]
dev = ["uv>=0.8.0", "ruff>=0.4.0", "pyright>=1.1.400", ...]

[tool.ruff]
line-length = 120
target-version = "py311"

noxfile.py - Test Automation Sessions

Replaces tox.ini with Python-based configuration:

@nox.session(python=["3.11", "3.12", "3.13"])
def behave(session):
    """Run BDD tests across Python versions."""
    session.install(".", "-e", ".[dev]")
    session.run("behave", "-q", *session.posargs)

pyrightconfig.json - Strict Type Checking

Ensures maximum type safety:

{
  "typeCheckingMode": "strict",
  "reportMissingImports": true,
  "pythonVersion": "3.11"
}

Testing Strategy

Behavior-Driven Development (BDD)

Tests are written as natural language specifications that serve as both documentation and executable tests:

Feature: Command-line greeting interface
  As a user of the boilerplate CLI
  I want to be greeted properly
  So that I can verify the application works

  Scenario: Default greeting
    When I run "python -m boilerplate"
    Then the exit code should be 0
    And the output should contain "Hello, World!"

  Scenario: Custom name greeting
    When I run "python -m boilerplate --name Alice"
    Then the exit code should be 0
    And the output should contain "Hello, Alice!"

  @hypothesis
  Scenario: Fuzz test greeting names
    When I fuzz test the CLI with random names
    Then all invocations should succeed

Property-Based Testing with Hypothesis

Automatically discovers edge cases by generating thousands of test inputs:

@hypothesis_given(
    st.text(min_size=0, max_size=100),
    st.integers(min_value=1, max_value=10)
)
def test_random_inputs(name, count):
    result = runner.invoke(main, ["--name", name, "--count", str(count)])
    assert result.exit_code == 0
    assert name in result.output
    assert result.output.count(name) == count

Benefits:

• Tests serve as living documentation
• Natural language specifications stakeholders can understand
• Automatic edge-case discovery with thousands of generated test cases
• Better bug discovery than traditional unit tests

Deployment Options

Development Environment

Option 1: Development Container (Recommended)

• Zero configuration setup
• Consistent environment across team
• VS Code integration with 15+ extensions
• Docker-in-Docker for container development

Option 2: GitHub Codespaces

• Browser-based development
• No local setup required
• 4-core, 8GB development environment
• 60 hours/month free tier

Option 3: Local Setup

• Traditional local development
• Full control over environment
• Requires manual tool installation

Production Deployment

Docker Container:

• Multi-stage builds for minimal size (20MB runtime)
• Non-root user execution for security
• Read-only filesystem for enhanced security
• Health checks and signal handling

Kubernetes with Helm:

• Production-ready Helm charts
• Horizontal Pod Autoscaling (HPA)
• Resource limits and requests
• Security contexts and pod security standards
• ConfigMap and Secret support

Performance Benchmarks

Tool Speed Comparison

Operation	Legacy Tool	Modern Tool	Performance Gain
Package Installation	pip install	uv pip install	10-100x faster
Code Formatting	black	ruff format	10-100x faster
Import Sorting	isort	ruff check --select I	10-100x faster
Linting	flake8 + pylint	ruff check	10-100x faster
Type Checking	mypy	pyright	5-10x faster

CI/CD Performance

• Cold clone to green CI: ≤ 60 seconds (vs 5-10 minutes with legacy tools)
• Warm cache builds: ≤ 30 seconds
• Parallel test execution: Tests run on Python 3.11, 3.12, 3.13 simultaneously
• Container builds: ≤ 2 minutes with BuildKit caching

Modern vs Legacy Comparison

Tool Replacements

From setup.py to pyproject.toml:

# Before: Multiple config files
setup.py + setup.cfg + requirements.txt + MANIFEST.in

# After: Single modern configuration
pyproject.toml  # PEP 621 compliant

From multiple tools to ruff:

# Before: Install and configure 5+ tools
pip install black isort flake8 pylint bandit

# After: Single Rust-powered tool
pip install ruff  # Replaces all, 10-100x faster

From pytest to BDD:

# Before: Technical test files
test_*.py  # Hard to understand business logic

# After: Natural language specifications  
*.feature  # Readable by stakeholders

From tox to nox:

# Before: Complex INI configuration
tox.ini  # Limited flexibility

# After: Python-based automation
noxfile.py  # Full Python flexibility

Key Modernization Benefits

1. Instant development - Terminal-based devcontainer setup in minutes
2. 10-100x faster tools - Rust-powered uv and ruff replace legacy tooling
3. Strict type safety - Pyright catches bugs at development time
4. Natural language tests - BDD scenarios anyone can understand
5. Cloud-native deployment - Production-ready Kubernetes with Helm
6. 60-second CI - Lightning-fast feedback loops

Best Practices

Development Workflow

1. Always use the devcontainer for consistent environments across team
2. Run nox before every commit to catch issues early
3. Write BDD scenarios first following test-driven development
4. Use type hints everywhere for better code quality and IDE support
5. Keep dependencies minimal for faster installation and fewer conflicts

Code Quality

1. Enable pre-commit hooks for automatic formatting and linting
2. Use strict type checking to catch bugs at development time
3. Write descriptive BDD scenarios that explain business value
4. Tag scenarios appropriately (@smoke, @wip) for selective testing
5. Follow conventional commits for clear change history

Deployment

1. Use Helm charts for consistent Kubernetes deployments
2. Set appropriate resource limits to prevent resource exhaustion
3. Enable HPA for automatic scaling based on CPU/memory usage
4. Implement health checks for reliable rolling deployments
5. Monitor application metrics in production environments

---

Ready to modernize your Python development? Choose your preferred setup method above and experience the power of modern Python tooling!