🏛️ From Scripting to Enterprise Architecture¶

A Masterclass in Scaling Complexity with Structum

Structum is designed to accompany you from your first line of code to your millionth. But “Enterprise” isn’t just about code size—it’s about Risk Management.

This guide demonstrates how to transition from a “Hope-Based” architecture to a “Verification-Based” architecture using structum-bootstrap and structum-di.

🛑 The “Professional Paranoia” Mindset¶

In an Enterprise environment (e.g., Banking, Healthcare), system integrity is paramount. Optimization is secondary to Correctness and Auditability.

1. Fail Fast: If a critical configuration or secret is missing, the application must terminate immediately. Silent failures or partial startups lead to undefined states during runtime.

2. Explicit Dependencies: No global variables or implicit assumptions. Every service must strictly declare its requirements.

3. Isolation: Business logic must be verifiable in isolation, without side effects from the infrastructure layer.

Structum enables this transition through enforced validation and dependency injection.

🗺️ The Architecture Map¶

🎓 End-to-End Example: The Secure Payment Processor¶

Let’s build a mocked “Payment Processor” that demands high security.

1. The Perimeter (Bootstrap)¶

We define a strict set of requirements. Note the paranoia: we check everything.

# bootstrap.py
from structum_lab.plugins.bootstrap import SystemBootstrapper, EnvValidator, DirectoryValidator

def verify_environment():
    gatekeeper = SystemBootstrapper()
    
    # 1. Secrets: Must exist. (Values are masked in logs)
    gatekeeper.add_validator(EnvValidator(required=[
        "STRIPE_API_KEY", 
        "DB_PASSWORD",
        "ENCRYPTION_KEY"
    ]))
    
    # 2. Compliance: Audit log directory must be writable
    gatekeeper.add_validator(DirectoryValidator(paths=["/var/log/audit/payments"]))
    
    # RUN. If this fails, the app process exits with code 1.
    gatekeeper.run_or_exit()

2. The Logic (Pure Python)¶

Notice: No imports from Structum. This service is pure business logic. It receives what it needs.

# services/payment.py
class PaymentProcessor:
    def __init__(self, api_key: str, audit_logger):
        self.api_key = api_key
        self.logger = audit_logger
        
    def process_transaction(self, amount: float):
        self.logger.info("Processing transaction", amount=amount)
        # ... logic ...

3. The Wiring (DI Container)¶

This is where Structum connects the generic Core to your specific Logic.

# container.py
from structum_lab.plugins.di import StructumContainer
from dependency_injector import providers
from .services.payment import PaymentProcessor

class AppContainer(StructumContainer):
    # We use Structum's Config Resource to fetch the API Key safely
    payment_processor = providers.Factory(
        PaymentProcessor,
        api_key=StructumContainer.config.provided.payment.stripe_key,
        # We inject a specific Logger context for Audit
        audit_logger=StructumContainer.logger("audit.payments")
    )

4. The Entrypoint¶

# main.py
from .bootstrap import verify_environment
from .container import AppContainer

def main():
    # 1. FAIL FAST: Verify Environment
    verify_environment()
    
    # 2. ASSEMBLE: Create Container
    container = AppContainer()
    
    # 3. EXECUTE: Run Application
    processor = container.payment_processor()
    processor.process_transaction(100.00)

🔓 The Structum Guarantee: Zero Lock-In¶

Important: You are NEVER forced to use the Dependency Injection Container.

All Structum plugins (auth, bootstrap, database, etc.) are designed to be used directly (“Standalone Mode”). The Container is simply a convenience adapter for those who prefer Clean Architecture.

See the Standalone Demo for proof.