Structum - Framework Documentation¶

[!NOTE] Versioning Note: The project is currently in Alpha Phase. All packages (Core and Plugins) follow synchronized versioning (“Lockstep”) with the main framework (structum).

Overview¶

Structum (lat. struttura): A solid, invisible, and modular foundation for modern Python applications.

Structum is not another web framework, CLI tool, or ORM. It’s a foundational framework designed to manage application lifecycle, configuration, observability, and plugin ecosystems—leaving you free to choose your preferred technologies for the final implementation.

Philosophy¶

• Protocol-First Architecture: Built on typing.Protocol interfaces, not rigid inheritance

• Zero Core Dependencies: structum-core uses only Python Standard Library

• Enterprise-Ready: Production features (health checks, metrics, graceful shutdown) from day one

• Modular by Design: Install only what you need via independent packages

Quick Navigation¶

🎓 Learning Path¶

📦 Core Modules¶

• Configuration - Multi-layer config with dot-notation

• Authentication - JWT, RBAC, password hashing

• Database - Connection pooling, transactions, health checks

• Logging - Structured logging facade (Core)

🔌 Plugins¶

• Dynaconf - Enterprise configuration engine

• Bootstrap - Application lifecycle management

• Dependency Injection - DI for FastAPI

• Auth - Authentication implementations

• Database - SQLAlchemy/PostgreSQL providers

• Observability - Structlog/Prometheus backend

📚 Guides¶

• All Guides & Learning Paths - Start here!

• Observability Stack - Logging & Prometheus metrics

• Enterprise Architecture - Production patterns

• Enterprise Architecture - Building production systems

• Configuration Getting Started - Deep dive into configuration

• Structum CLI - Command Line Interface Reference

🏛️ Governance & Architecture¶

• Architectural Constitution - The “Supreme Law” of Structum

• Why Structum? - Philosophy and technical rationale

• Review Checklist - Compliance for PRs

• Anti-Patterns - What NOT to do

• Mental Model - Visual Architecture Map

• Exit Strategy - Decommissioning Protocol

• AI Governance - Transparency & Ethics

Installation¶

[!IMPORTANT] Alpha Status: Structum is currently in alpha phase (v0.1.0). Packages are not yet published to PyPI. Installation is only available from source.

From Source (Required)¶

# Clone repository
git clone https://github.com/PythonWoods/structum.git
cd structum

# Install all packages + dev tools (mypy, pytest, ruff, etc.)
uv sync --extra dev

Note: This installs all workspace packages (packages/*) in editable mode with development dependencies.

Future: PyPI Installation (Coming Soon)¶

Once packages are published to PyPI, you will be able to install via:

# [Meta-package & CLI](cli/index.md) (all features)
pip install structum

# Individual packages
pip install structum-core structum-dynaconf

Quick Start¶

1. Minimal Example (Core Only)¶

The configuration system works out-of-the-box without any setup using structum-core:

from structum.config import get_config

# Get the singleton instance
config = get_config()

# Write configuration (automatically persisted)
config.set("server.host", "0.0.0.0")
config.set("server.port", 8080)

# Read configuration (with safe defaults)
host = config.get("server.host", default="localhost")
port = config.get("server.port", default=8000)

print(f"Server starting on {host}:{port}")

2. Production Example (With Plugins)¶

Full-featured application using structum (Meta):

from structum.config import set_config_provider, get_config
from structum.plugins.dynaconf import DynaconfConfigProvider
from structum.plugins.observability import setup_logging, get_logger
from structum.plugins.bootstrap import SystemBootstrapper, EnvValidator

def setup_application():
    """
    Initialize Structum with production features.
    """
    # 1. Validation: Ensure environment is ready
    boot = SystemBootstrapper()
    boot.add_validator(EnvValidator(required=["APP_ENV", "DB_URL"]))
    boot.run_or_exit()
    
    # 2. Configuration: Load multi-layer config
    provider = DynaconfConfigProvider(root_path=".", env_prefix="MYAPP")
    set_config_provider(provider)
    
    # 3. Observability: Setup structured logging
    setup_logging()
    
    get_logger(__name__).info("Application initialized")

if __name__ == "__main__":
    setup_application()

Project Structure¶

Structum uses a monorepo architecture with distributed packages:

structum/
├── packages/                          # Distribution Packages
│   ├── core/                          # [structum-core] Protocols & Base
│   ├── meta/                          # [structum] Meta-package bundle
│   ├── dynaconf/                      # [structum-dynaconf] Plugin
│   ├── observability/                 # [structum-observability] Plugin
│   ├── auth/                          # [structum-auth] Plugin
│   ├── database/                      # [structum-database] Plugin
│   ├── di/                            # [structum-di] Plugin
│   └── bootstrap/                     # [structum-bootstrap] Plugin
│
├── demo/                              # Example applications
│   ├── 01-logging-basics/
│   ├── 02-observability-full/
│   └── ...
│
└── pyproject.toml                     # Workspace Orchestrator

Architecture Overview¶

Protocol-Based Design¶

Structum separates interfaces (protocols) from implementations (plugins):

┌─────────────────────────────────────────┐
│   Application Code                      │
│   Uses: get_config(), get_logger()      │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│   Structum Core (structum-core)         │
│   • ConfigProviderInterface             │
│   • LoggerInterface                     │
│   • AuthInterface                       │
│   • DatabaseInterface                   │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│   Plugin Implementations                │
│   ┌──────────┬──────────┬──────────┐   │
│   │ Dynaconf │Observable│ Auth     │   │
│   │ Provider │ Logger   │ Provider │   │
│   └──────────┴──────────┴──────────┘   │
└─────────────────────────────────────────┘

Benefits:

• Testability: Mock providers without changing application code

• Flexibility: Switch implementations (JSON → Dynaconf → Vault) without refactoring

• Type Safety: Full static type checking with mypy strict mode

Core Features¶

Why Structum?¶

vs Django/FastAPI¶

Structum is not a replacement. It’s an underpinning. Use Django ORM, FastAPI routing, or Flask views—Structum manages the lifecycle beneath them.

vs Direct Library Usage¶

Instead of manually wiring pydantic, structlog, prometheus_client, Structum provides a unified API with consistent patterns.

vs No Framework¶

As projects grow, you’ll reinvent configuration management, logging setup, health checks. Structum provides these patterns from day one.

Next Steps¶

1. Configuration Guide - Deep dive into configuration management

2. Enterprise Architecture - Building production systems

3. API Reference - Complete API documentation

Support¶

• GitHub Issues: github.com/PythonWoods/structum/issues

• Discussions: github.com/PythonWoods/structum/discussions

License¶

Apache 2.0 - See LICENSE