Structum Mental Model

The Big Picture: How the pieces fit together.

This map visualizes the distinction between Contracts (Foundation), Implementations (Plugins), and Usage (Application).

graph TD %% Styling classDef app fill:#e1f5fe,stroke:#01579b,stroke-width:2px; classDef foundation fill:#fff3e0,stroke:#ff6f00,stroke-width:2px; classDef plugins fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px; classDef governance fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,stroke-dasharray: 5 5; subgraph "Layer 4: Governance (The Constitution)" CONST[Constitution]:::governance -.-> |"C-1 Opt-In"| PLUGINS CONST -.-> |"C-6 Fail-Fast"| BOOT end subgraph "Layer 3: Application (User Land)" APP[My Service]:::app MAIN[main.py]:::app end subgraph "Layer 2: Machinery (Plugins)" PLUGINS[Plugins Implementation]:::plugins AUTH_P[Structum Auth]:::plugins DB_P[Structum Database]:::plugins BOOT[Structum Bootstrap]:::plugins end subgraph "Layer 1: Foundation (Zero Dependencies)" CORE[Structum Core]:::foundation PROTO_A[Auth Protocol]:::foundation PROTO_D[App Config Protocol]:::foundation end %% Flows APP --> |"Imports Type Hints"| CORE APP --> |"Injected with"| PLUGINS MAIN --> |"Configures"| PLUGINS PLUGINS -.-> |"Implements"| CORE AUTH_P --> PROTO_A DB_P --> PROTO_D

Key Takeaways

  1. Foundation is cheap: Importing structum.core costs nothing (no deps).

  2. Plugins are heavy: They bring dependencies (SQLAlchemy, Pydantic).

  3. Governance is pervasive: The Constitution constrains how Plugins implement the Foundation.