Structum Architectural Constitution

Status: Ratified (2026-01-14)
Authority: Supreme (Supersedes implementation details)
Scope: All Core Modules, Plugins, and Official Guides

Preamble

Structum is not just a collection of utilities; it is an opinionated architectural framework designed to balance robustness with freedom.

To prevent architectural drift as the ecosystem grows, this Constitution establishes the non-negotiable principles that govern the development of Structum. These principles are normative: code that violates them is considered buggy, regardless of functional correctness.

Article I: The Core Philosophy

C-1. Principle of Optionality (The “Opt-In” Law)

“Nothing is mandatory unless essential for the Core.”

  • Definition: No feature, plugin, or pattern shall be imposed on the user unless the application cannot technically function without it (e.g., importing a module).

  • Audit Question: Can I use Structum without this component?

  • Violation Example: A logging module that crashes if the DI container is missing.

C-2. Principle of Explicitness (The “No Magic” Law)

“Explicit state beats implicit discovery.”

  • Definition: Structum avoids “magic” behavior. Configuration, wiring, and side-effects must be observable and explicitly triggered.

  • Audit Question: Is it obvious where this value comes from?

  • Violation Example: A database connection that automatically initializes itself on import by scanning environment variables without a user call.

C-3. Principle of Managed Boundaries

“Infrastructure does not leak into Domain.”

  • Definition: Implementation details (frameworks, drivers, containers) must stop at the boundary of the business logic.

  • Audit Question: Does my domain logic import sqlalchemy or dependency_injector directly?

  • Violation Example: Passing a Session object deep into a pure business entity.

Article II: Operational Integrity

C-4. Principle of Zero Lock-In

“Structum is a guest, not a host.”

  • Definition: Structum adapters must expose standard interfaces. Switching away from Structum should be a refactor, not a rewrite.

  • Audit Question: How hard is it to replace this plugin?

  • Violation Example: A plugin that monkey-patches standard library functions globally.

C-5. Principle of Operational Continuity

“Fallback is a valid state.”

  • Definition: Systems must degrade gracefully. The absence of an advanced feature (like a metrics backend) must result in correct, albeit reduced, behavior (No-Op), not a crash.

  • Audit Question: What happens if I uninstall the plugin?

  • Violation Example: An application raising ImportError at runtime because a metrics library is missing.

C-6. Principle of Fail-Fast

“Validate early, crash loudly.”

  • Definition: Invalid states must be caught at bootstrap time, not at usage time.

  • Audit Question: Does the app start if configuration is invalid?

  • Violation Example: Allow an app to start with a missing DATABASE_URL, only to crash 5 hours later when a query is executed.

Article III: Data Integrity

C-7. Principle of Temporal Accounting

“Metrics are facts, not decorations.”

  • Definition: Observability data must follow strict semantic rules. Counters count, gauges measure state, histograms measure distribution.

  • Audit Question: Does this metric physically represent what it claims?

  • Violation Example: Using a Gauge to track the total number of requests (losing rate information).

Article IV: Meta-Governance

C-8. Principle of Anti-Magic (AI Transparency)

“AI is an auditor, not an author.”

  • Definition: The use of Agentic AI must be explicit, strictly governed, and used primarily for auditing, stress-testing, and compliance checking.

  • Audit Question: Is this code understood by the human maintainer?

  • Violation Example: Committing AI-generated code that violates Constitutional principles without human verification.

  • Reference: AI-Assisted Development & Governance

Enforcement

  1. Code Reviews: Every PR must be checked against these articles.

  2. Documentation: Every plugin README must define its “Constitution Compliance”.

  3. Breaking Changes: Any change that violates an existing principle requires a Major Version bump and a Constitutional Amendment.