Design Principles

Plumego is not defined by its feature set.

It is defined by what it refuses to become.

This document lists the non-negotiable design principles
that constrain Plumego’s evolution and guide every future decision.

If a change violates these principles,
it does not belong in Plumego — regardless of demand or popularity.

Principle 1: Explicitness Over Convenience

If behavior is not visible in code, it is not acceptable.

Plumego rejects:

Implicit configuration
Magic defaults
Convention-based behavior
Runtime inference
Hidden lifecycle hooks

Every meaningful behavior must be:

Constructed explicitly
Wired explicitly
Invoked explicitly

Convenience that hides behavior is considered technical debt.

Principle 2: Control Flow Must Be Obvious

Plumego treats control flow as sacred.

This means:

Middleware execution order is explicit
Handler termination is explicit
Errors do not “bubble magically”
Nothing retries or recovers unless you wire it

If you cannot explain exactly what happens next,
the design is wrong.

Principle 3: No Global State, No Ambient Context

Plumego avoids:

Global registries
Hidden singletons
Ambient configuration
Implicit dependency injection

All dependencies must be passed explicitly.

This enables:

Testability
Replaceability
Reasoning under pressure
Safe refactoring

Global convenience is short-term gain, long-term cost.

Principle 4: Small Core, Strong Boundaries

Plumego’s core is intentionally minimal.

The framework:

Defines boundaries
Enforces contracts
Refuses to grow horizontally

New capabilities should live:

In user code
In optional middleware
In external packages

If something can be done outside the core, it should be.

Principle 5: Application Owns the Lifecycle

Plumego never assumes ownership of:

Process startup
HTTP server lifecycle
Shutdown orchestration
Background workers
Scheduling

The application decides when things start and stop.

This makes Plumego embeddable, composable, and long-lived.

Principle 6: Framework Neutrality

Plumego is deliberately opinionated about structure,
but neutral about infrastructure.

It does not mandate:

Logging libraries
Auth providers
Databases
Message queues
Serialization formats
Deployment models

Plumego integrates with ecosystems —
it does not replace them.

Principle 7: Boring Is a Feature

Plumego values:

Predictability over novelty
Stability over speed of change
Familiarity over cleverness

If something feels “exciting” because it is clever,
it probably does not belong in the core.

Boring code survives longer.

Principle 8: Replaceability Is a First-Class Goal

Every major abstraction must be replaceable:

Routers
Middleware
Persistence
External integrations

Replaceability is achieved by:

Explicit interfaces
Clear boundaries
No hidden coupling

If something cannot be replaced safely,
it will eventually force a rewrite.

Principle 9: Errors Are Part of the Contract

Errors are not incidental.

Plumego enforces that:

Errors are explicit
Error handling is visible
Error translation happens at boundaries
Nothing is silently swallowed

This applies equally to:

HTTP errors
Domain errors
Infrastructure failures

Silence is never acceptable.

Principle 10: Documentation Is a Contract

Documentation is not optional.

If behavior exists:

It must be documented
It must be intentional
It must be defensible

Undocumented behavior is considered unstable by default.

The Reference section defines reality.

Principle 11: Evolution Must Be Slow and Deliberate

Plumego optimizes for longevity.

This means:

Breaking changes are rare
Major versions are infrequent
Compatibility is valued
Migration paths are explicit

Framework churn is treated as a design failure.

Principle 12: The User Is a Responsible Engineer

Plumego assumes its users:

Understand Go
Understand HTTP
Understand concurrency
Understand trade-offs

The framework does not protect users from complexity
by hiding it.

Instead, it exposes complexity honestly.

Principle 13: No Features Without a Clear Removal Story

Every new capability must answer:

“How do we remove this if it turns out to be wrong?”

If removal would break the ecosystem,
the feature should not be added.

Principle 14: Pressure Is the Real Test

Design decisions must hold under:

Scale
Failures
Team growth
Operational stress
Time

If a design only works in small demos,
it does not belong in Plumego.

How These Principles Are Applied

Every proposed change is evaluated against this checklist:

Does it introduce hidden behavior?
Does it weaken boundaries?
Does it grow the core unnecessarily?
Does it reduce replaceability?
Does it complicate reasoning?

If yes, the change is rejected.

Summary

Plumego is constrained by design.

These principles exist to ensure that:

The framework remains understandable
Systems remain evolvable
Users retain control
Time does not turn features into liabilities

The roadmap is shaped not by ambition,
but by restraint.

Roadmap Overview — long-term direction
Migration Policy — how change is handled
Changelog — what actually changed

If Plumego ever violates these principles,
it has lost its reason to exist.