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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```toml
[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:

```python
@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:

```json
{
  "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:

```gherkin
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:

```python
@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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Before: Technical test files
test_*.py  # Hard to understand business logic

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

**From tox to nox:**
```bash
# 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!