Structum: Project Portal

Warning

Alpha Status: Structum is currently in Alpha (v0.1.0). APIs may change. Not yet ready for production use. See ROADMAP.md for development status.

Structum is a modular Python framework emphasizing architectural correctness and systems stability. It includes enterprise-grade Dependency Injection, layered configuration management, and "fail-fast" validation protocols.

---

🏛️ Architecture & Philosophy

Structum is built on the principle of Invisible Infrastructure: foundations that are solid, type-safe, and modular, but get out of your way.

graph TD
    %% Define Styles
    classDef app fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef core fill:#e0f2f1,stroke:#00695c,stroke-width:2px,color:#004d40
    classDef foundation fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c

    %% Layer 1: Application
    subgraph L1 [Layer 1: User Application]
        APP("🖥️ Your App"):::app
    end

    %% Layer 2: Core Framework
    subgraph L3 [Layer 2: Structum Core]
        FRAMEWORK{"🦅 Structum Framework"}:::core
        PROTOCOLS["📜 Protocol Interfaces"]:::core
    end

    %% Layer 3: Foundation
    subgraph L4 [Layer 3: Foundation]
        ZERO("⚛️ Zero External Dependencies (StdLib)"):::foundation
    end

    %% Relationships
    APP -->|Installs| FRAMEWORK
    APP -.->|Depends On| PROTOCOLS

    FRAMEWORK -->|Defines| PROTOCOLS
    FRAMEWORK -->|Built On| ZERO

Loading

Key Enterprise Features

• 🛡️ Verification-Based: Validates environment, config, and dependencies before the app starts. No runtime surprises.
• 🧩 Modular Design: Use the full suite or pick individual components. Zero coupling between plugins.
• 🔒 Secure by Default: Security is not an afterthought. Built-in secret management, RBAC, and secure logging.
• ⚡ Protocol-First: Interfaces defined in structum allow for easy mocking and replacement of implementation details.

---

📚 Official Documentation

Comprehensive guides, API references, and architectural deep-dives are available at:

👉 docs.structum.dev 👈

---

🚀 Installation

Important

Pre-Alpha Status: Structum is currently in pre-alpha phase (v0.1.0). Packages are not yet published to PyPI. You must install from source.

Install from Source

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

# Install with uv (recommended)
uv sync --all-extras

# Or with pip (editable mode)
pip install -e "packages/structum[all]"

Install Specific Plugins

# Core + specific plugins
pip install -e "packages/structum" \
             -e "packages/auth" \
             -e "packages/database"

# Web application bundle
pip install -e "packages/structum[web]"

Future: PyPI Installation (Post-Alpha)

Once published, installation will be simplified:

# Core framework only
pip install structum

# With plugins
pip install structum[auth,database,observability]

# Everything (batteries-included)
pip install structum[all]

---

🧩 Module Ecosystem

Structum follows a protocol-first architecture where the core defines interfaces and plugins provide implementations.

graph LR
    %% Styles
    classDef core fill:#e0f2f1,stroke:#00695c,stroke-width:2px,color:#004d40
    classDef plugin fill:#fff3e0,stroke:#ef6c00,stroke-width:1px,color:#e65100,stroke-dasharray: 5 5

    subgraph Core [Structum Core]
        P_AUTH["Auth Protocol"]:::core
        P_DB["Database Protocol"]:::core
        P_CONF["Config Protocol"]:::core
        P_LOG["Logging Protocol"]:::core
        P_MON["Monitoring Protocol"]:::core
    end

    subgraph Official [Official Plugins]
        I_AUTH["structum-auth<br/>(JWT, RBAC)"]:::plugin
        I_DB["structum-database<br/>(SQLAlchemy)"]:::plugin
        I_CONF["structum-dynaconf<br/>(Multi-env)"]:::plugin
        I_OBS["structum-observability<br/>(Structlog)"]:::plugin
        I_FAST["structum-fastapi<br/>(Web)"]:::plugin
        I_DI["structum-di<br/>(Container)"]:::plugin
        I_BOOT["structum-bootstrap<br/>(Validation)"]:::plugin
        I_CLI["structum-cli-tools<br/>(DevTools)"]:::plugin
    end

    subgraph Archive [Archive Plugins]
        A_MD["structum-archive-markdown"]:::plugin
        A_HTML["structum-archive-html"]:::plugin
        A_JSON["structum-archive-json"]:::plugin
        A_ZIP["structum-archive-zip"]:::plugin
    end

    %% Implementation Relationships
    I_AUTH ..|> P_AUTH
    I_DB ..|> P_DB
    I_CONF ..|> P_CONF
    I_OBS ..|> P_LOG
    I_OBS ..|> P_MON
    
    %% Archive plugins use core
    A_MD -.-> Core
    A_HTML -.-> Core
    A_JSON -.-> Core
    A_ZIP -.-> Core

Loading

Official Plugins

Maintained by the Structum team for production-ready applications.

Plugin Package	Status	Domain	Description
structum-fastapi	✅ Alpha	Web	Seamless FastAPI integration with DI injection and middleware
structum-dynaconf	✅ Alpha	Config	Enterprise-grade configuration (files, env vars, Vault/Redis)
structum-observability	✅ Alpha	Ops	Structured logging (Structlog) and metrics (Prometheus)
structum-auth	✅ Alpha	Security	JWT tokens, Argon2 hashing, RBAC authorization
structum-database	✅ Alpha	Data	SQLAlchemy integration with connection pooling and migrations
structum-di	✅ Alpha	Architecture	Dependency Injection container (dependency-injector)
structum-bootstrap	✅ Alpha	Lifecycle	Startup validation, signal handling, graceful shutdown
structum-cli-tools	✅ Alpha	DevTools	Security scanning, testing, profiling, release automation

Archive Plugins (Self-Documentation)

Export and document your codebase structure:

Plugin Package	Status	Format	Description
structum-archive-markdown	✅ Alpha	Docs	Generate Markdown archives for documentation
structum-archive-html	✅ Alpha	Docs	Self-contained HTML reports with navigation
structum-archive-json	✅ Alpha	Data	JSON serialization for CI/CD analysis
structum-archive-zip	✅ Alpha	Utils	Binary ZIP export of filtered codebase

Installation Extras

# Core plugins
pip install -e "packages/structum[auth]"          # Authentication
pip install -e "packages/structum[database]"      # Database
pip install -e "packages/structum[observability]" # Logging & Metrics
pip install -e "packages/structum[di]"            # Dependency Injection
pip install -e "packages/structum[dynaconf]"      # Configuration
pip install -e "packages/structum[bootstrap]"     # Validation
pip install -e "packages/structum[fastapi]"       # Web framework
pip install -e "packages/structum[cli-tools]"     # Dev tools

# Archive plugins
pip install -e "packages/structum[archive-markdown]"
pip install -e "packages/structum[archive-html]"
pip install -e "packages/structum[archive-json]"
pip install -e "packages/structum[archive-zip]"

# Bundles
pip install -e "packages/structum[web]"           # FastAPI + Auth + DB + Observability
pip install -e "packages/structum[archive]"       # All archive plugins
pip install -e "packages/structum[all]"           # Everything

# Development
pip install -e "packages/structum[dev]"           # Dev dependencies (mypy, pytest, ruff)

---

📦 Module Reference

Complete module listing with source links:

Module	PyPI Package	Description	Source
Structum Core	structum	Core framework + CLI	packages/structum
Auth	structum-auth	JWT, Argon2, RBAC	packages/auth
Bootstrap	structum-bootstrap	Environment validation	packages/bootstrap
Database	structum-database	SQLAlchemy/PostgreSQL	packages/database
DI	structum-di	Dependency Injection	packages/di
Dynaconf	structum-dynaconf	Configuration	packages/dynaconf
FastAPI	structum-fastapi	Web framework	packages/fastapi
Observability	structum-observability	Logging, Metrics	packages/observability
CLI Tools	structum-cli-tools	Dev commands	packages/cli-tools
Archive: Markdown	structum-archive-markdown	Markdown export	packages/archive-markdown
Archive: HTML	structum-archive-html	HTML reports	packages/archive-html
Archive: JSON	structum-archive-json	JSON serialization	packages/archive-json
Archive: ZIP	structum-archive-zip	ZIP archives	packages/archive-zip

---

⚡ Local Development Quickstart

To contribute or develop locally using the workspace:

1. Clone the repository:

   git clone https://github.com/PythonWoods/structum.git
   cd structum

2. Environment Setup (using uv):

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

   Note: This installs all packages in editable mode with development dependencies.

3. Run Quality Checks:

   # Lint
   uv run ruff check .
   
   # Format
   uv run ruff format .
   
   # Type check
   uv run mypy packages/*/src --strict
   
   # Security scan
   uv run bandit -c bandit.toml -r packages/
   
   # Tests
   uv run pytest --cov=packages
   
   # Build docs
   uv run sphinx-build -n -W -b html docs/ docs/_build/html

4. Pre-commit Hooks (Recommended):

   # Install hooks
   pre-commit install
   
   # Run on all files
   pre-commit run --all-files

---

🛠️ CLI Tools

Structum provides an extensible CLI for development workflows:

Core Commands

structum check                       # Code quality (lint + format + types + security)
structum build-docs                  # Sphinx documentation
structum docs verify-intersphinx     # Verify docs external links
structum license check               # REUSE compliance

Advanced Tools (CLI Tools Plugin)

Security Scanning:

structum security scan               # Bandit static analysis
structum security audit              # Full security audit (Bandit + Safety)

Testing:

structum test                        # Run pytest
structum test --cov                  # With coverage
structum test --cov-fail-under=90    # Enforce coverage threshold

Future Features (Sprint 2-3):

structum profile run app.py          # CPU flamegraphs
structum profile memory app.py       # Memory tracking
structum release prepare             # Semantic versioning
structum api diff v0.1.0..HEAD       # Breaking changes detection
structum plugin search <keyword>     # Search marketplace
structum plugin install <name>       # Install plugin

Architecture: Plugin-based with auto-discovery, respecting Zero-Dependency core.

See: CLI Documentation | CLI Tools Plugin

---

🔌 Plugin Ecosystem

Structum features a built-in plugin marketplace for discovering and installing community extensions.

Core Plugin Commands (Always Available)

# Search marketplace
structum plugin search <keyword>

# Install verified plugin
structum plugin install <plugin-name>

# List installed plugins
structum plugin list

# Verify plugin integrity
structum plugin verify <plugin-name>

Plugin Catalog

The following plugins are currently available in the monorepo:

Plugin	Package Name	Description	Status
Auth	structum-auth	JWT, Argon2, RBAC	✅ Alpha
Bootstrap	structum-bootstrap	Environment validation	✅ Alpha
Database	structum-database	SQLAlchemy, PostgreSQL	✅ Alpha
DI	structum-di	Dependency Injection	✅ Alpha
Dynaconf	structum-dynaconf	Configuration management	✅ Alpha
FastAPI	structum-fastapi	FastAPI web framework integration	✅ Alpha
Observability	structum-observability	Logging, Metrics, Tracing	✅ Alpha
CLI Tools	structum-cli-tools	Advanced dev tools	✅ Alpha
Archive: Markdown	structum-archive-markdown	Markdown export	✅ Alpha
Archive: HTML	structum-archive-html	HTML reports	✅ Alpha
Archive: JSON	structum-archive-json	JSON serialization	✅ Alpha
Archive: ZIP	structum-archive-zip	ZIP archives	✅ Alpha

See: Plugin Development Guide

Security: Official plugins follow strict security standards and code review processes.

---

🔒 Security

Security is a priority. Our CI pipeline includes:

• ✅ Static Analysis: Bandit security scanner on every commit
• ✅ Dependency Audit: Automated vulnerability checks
• ✅ Blocking CI: HIGH/CRITICAL issues block merges
• ✅ Security Reports: Available as artifacts for 90 days

For security concerns, please refer to our Security Policy or contact security@structum.dev.

---

🤝 Contributing

We welcome contributions! Please see:

• Contributing Guide
• Code of Conduct
• Style Guide

---

📧 Contact

• Technical: dev@structum.dev
• Support: support@structum.dev
• Security: security@structum.dev
• General: info@structum.dev

---

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