Structum Lab - Framework Documentation¶

Framework Version: 0.1.0 (Alpha) Documentation Status: Alpha License: Apache 2.0 Copyright: © 2025 PythonWoods

[!NOTE] Nota sul Versionamento: Attualmente il progetto è in fase Alpha. Tutti i pacchetti (Core e Plugin) seguono il versionamento sincronizzato (“Lockstep”) del framework principale (structum-lab). In futuro, i plugin adotteranno un versionamento semantico indipendente.

Overview¶

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

Structum Lab 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: 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¶

🚀 Getting Started¶

• Installation

• Quick Start (5 Minutes)

• Project Structure

📦 Core Modules¶

• Configuration - Multi-layer config with dot-notation

• Authentication - JWT, RBAC, password hashing

• Database - Connection pooling, transactions, health checks

🔌 Plugins¶

• Dynaconf Plugin - Advanced configuration engine (Type-safe, Multi-source)

• Observability Plugin - Structured logging & Prometheus metrics

• Auth Plugin - Production-ready authentication

• Database Plugin - SQLAlchemy integration

• Bootstrap Plugin - Startup validation & health checks

• DI Plugin - Dependency injection for FastAPI

📖 Guides¶

• Configuration Getting Started

• Enterprise Architecture

• Observability Stack

Installation¶

Core Framework¶

# Install core framework (minimal dependencies)
pip install -e packages/core

With Plugins¶

# Configuration engine
pip install -e packages/dynaconf

# Observability stack  
pip install -e packages/observability

# Authentication
pip install -e packages/auth

# Database support
pip install -e packages/database

# Dependency injection
pip install -e packages/di

# Bootstrap validation
pip install -e packages/bootstrap

Development Environment¶

# Clone repository
git clone https://github.com/pythinwoods/structum-lab.git
cd structum-lab

# Install all packages in development mode
pip install -e packages/core
pip install -e packages/dynaconf
pip install -e packages/observability
pip install -e packages/auth
pip install -e packages/database
pip install -e packages/di
pip install -e packages/bootstrap

# Install development tools
pip install -e "packages/core[dev]"

Quick Start¶

1. Minimal Example (Core Only)¶

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

from structum_lab.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}")

Output:

Server starting on 0.0.0.0:8080

2. Production Example (With Plugins)¶

Full-featured application with type-safe configuration and observability:

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

def setup_application():
    """
    Initialize Structum with production features.
    Called once at application startup.
    """
    # 1. Validation: Ensure environment is ready
    boot = SystemBootstrapper()
    boot.add_validator(EnvValidator(required=["APP_ENV", "DB_URL"]))
    boot.run_or_exit()  # Fails fast if environment invalid
    
    # 2. Configuration: Load multi-layer config with validation
    provider = DynaconfConfigProvider(
        root_path=".",
        env_prefix="MYAPP",
        current_env=os.getenv("APP_ENV", "development")
    )
    provider.auto_discover()  # Scans config/app/*.toml
    set_config_provider(provider)
    
    # 3. Observability: Setup structured logging
    setup_logging()
    
    logger = get_logger(__name__)
    logger.info("Application initialized", env=provider.current_env)

def main():
    setup_application()
    
    # Your application code
    config = get_config()
    db_url = config.get("database.url")
    
    logger = get_logger(__name__)
    logger.info("Connecting to database", url=db_url)
    
    # ... rest of your application

if __name__ == "__main__":
    main()

Project Structure¶

Structum Lab uses a monorepo architecture with independent packages:

structum-lab/
├── packages/                          # Monorepo packages
│   ├── core/src/structum_lab/        # Core framework (protocols & base)
│   ├── dynaconf/src/structum_lab/    # Configuration engine
│   ├── observability/src/structum_lab/ # Logging & metrics
│   ├── auth/src/structum_lab/        # Authentication
│   ├── database/src/structum_lab/    # Database interfaces
│   ├── di/src/structum_lab/          # Dependency injection
│   └── bootstrap/src/structum_lab/   # Startup validation
│
├── demo/                              # Example applications
│   ├── 01-logging-basics/
│   ├── 02-observability-full/
│   ├── 03-zero-config/
│   ├── 04-web-integration/
│   └── 10-di-fastapi/
│
├── docs/                              # Documentation (you are here)
│   ├── modules/                       # Core module documentation
│   ├── plugins/                       # Plugin documentation
│   └── guides/                        # Tutorial guides
│
└── pyproject.toml                     # Root monorepo configuration

Architecture Overview¶

Protocol-Based Design¶

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

┌─────────────────────────────────────────┐
│   Application Code                      │
│   Uses: get_config(), get_logger()      │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│   Core Protocols (packages/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¶

1. Configuration Management¶

Multi-layer resolution with precedence:

1. Runtime → config.set() modifications

2. Environment → MYAPP_DATABASE__HOST variables

3. Secrets → config/.secrets.toml (git-ignored)

4. Application → config/app/*.toml (versioned)

5. Defaults → Hard-coded fallbacks

Example:

# Layer 4: Application default
# config/app/database.toml
[default]
host = "localhost"

# Layer 2: Environment override
export MYAPP_DATABASE__HOST=prod.db.com

# Result:
config.get("database.host")  # "prod.db.com" (ENV wins)

Read more →

2. Observability¶

Structured logging with automatic context propagation:

from structum_lab.plugins.observability import get_logger

logger = get_logger(__name__)
logger.info("User login", user_id=123, ip="10.0.0.1")

# Output (JSON):
# {"timestamp": "2025-01-12T10:00:00Z", "level": "INFO", 
#  "message": "User login", "user_id": 123, "ip": "10.0.0.1"}

Prometheus metrics with automatic collection:

from structum_lab.plugins.observability import get_metrics

metrics = get_metrics("myapp.api")
metrics.increment("requests.total", tags={"endpoint": "/users"})
metrics.timing("request.duration", 0.250)

Read more →

3. Authentication¶

Production-ready JWT authentication with Argon2 password hashing:

from structum_lab.plugins.auth import JWTAuthProvider

auth = JWTAuthProvider.from_config()
tokens = auth.authenticate("username", "password", user_repo)

if tokens:
    access_token = tokens.access_token    # Short-lived (15min)
    refresh_token = tokens.refresh_token  # Long-lived (7 days)

Read more →

Why Structum?¶

vs. Django/Flask¶

Django/Flask are opinionated web frameworks. Structum is a foundation layer:

Use Structum + FastAPI for a modern, type-safe web stack.

vs. Pydantic Settings¶

Pydantic Settings handles config loading. Structum provides the complete foundation:

• ✅ Configuration (Pydantic + multi-layer)

• ✅ Logging (structured + context)

• ✅ Metrics (Prometheus)

• ✅ Authentication (JWT + Argon2)

• ✅ Database (interfaces + pooling)

• ✅ Bootstrap validation

• ✅ Plugin system

Next Steps¶

New Users¶

1. ✅ Read Configuration Guide

2. ✅ Explore Demo Applications

3. ✅ Review Module Documentation

Existing Projects¶

1. ✅ Read Enterprise Architecture Guide

2. ✅ Plan migration strategy (incremental adoption)

3. ✅ Start with configuration subsystem

Contributors¶

1. ✅ Read Contributing Guidelines

2. ✅ Review AI Development Guide

3. ✅ Check ROADMAP.md for planned features

Support & Community¶

• Documentation: https://structum-lab.readthedocs.io

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Changelog: CHANGELOG.md

License¶

Distributed under the Apache 2.0 License.
Copyright © 2025 PythonWoods.

See LICENSE for details.