Docs Design Philosophy

Design Philosophy

Plumego is not the result of accidental simplicity.
It is the result of deliberate constraints.

Every design decision in Plumego is guided by a small set of principles that prioritize clarity, longevity, and engineering responsibility over short-term convenience.

This document describes those principles.

1. Standard Library First

The Go standard library is a foundation, not something to be hidden.

Plumego treats Go’s standard library as the most stable and trustworthy dependency in the system.

Rather than reimplementing or abstracting it away, Plumego:

  • Builds directly on net/http
  • Extends context.Context instead of replacing it
  • Avoids reflection-heavy or code-generated behavior

Why this matters

  • The standard library has a strong compatibility guarantee
  • Its behavior is well-documented and widely understood
  • Tooling, debugging, and profiling work as expected
  • Engineers can always fall back to “plain Go” when needed

Plumego assumes that understanding the standard library is an asset — not a burden.

2. Explicit Over Implicit

Hidden behavior trades short-term convenience for long-term confusion.

Many frameworks improve developer experience by introducing implicit behavior:

  • Automatic parameter binding
  • Implicit request context mutation
  • Global middleware with unclear ordering
  • Convention-driven magic

Plumego deliberately avoids these patterns.

Instead, it favors:

  • Explicit data flow
  • Clear execution order
  • Visible dependencies
  • Predictable side effects

The cost of explicitness

Plumego may require more code to achieve the same result.
That is a conscious tradeoff.

Every explicit line of code serves as documentation for future maintainers.

3. Predictability Over Cleverness

A predictable system is more valuable than a clever one.

Plumego avoids designs that:

  • Depend on reflection or runtime magic
  • Change behavior based on hidden configuration
  • Introduce multiple ways to do the same thing

Instead, it prioritizes:

  • Linear request flow
  • Single, obvious execution paths
  • Consistent mental models across projects

This makes Plumego particularly suitable for:

  • Debugging production issues
  • Onboarding new engineers
  • Reasoning about behavior under failure

4. Structure Over Convenience

Good structure scales better than convenience.

Plumego assumes that:

  • Most systems grow more complex over time
  • Architectural debt compounds silently
  • Early convenience often becomes future friction

As a result, Plumego emphasizes:

  • Clear boundaries between framework and business logic
  • Explicit layering and dependency direction
  • Separation of concerns, even when it feels verbose

This may slow down early development slightly,
but it significantly reduces long-term maintenance costs.

5. Framework as Boundary, Not Core

Framework code should never become the center of your system.

In Plumego:

  • The framework owns the request lifecycle
  • The application owns the business logic

Plumego is designed so that:

  • Domain and use-case code do not depend on Plumego
  • Framework-specific code stays at the edges
  • Core logic can be tested and reused independently

This principle makes Plumego especially suitable for systems that may:

  • Outlive the framework
  • Migrate to different transports
  • Be partially rewritten over time

6. Minimalism With Intent

Minimalism is only valuable when it is intentional.

Plumego is not minimal because it lacks ambition.
It is minimal because it refuses to guess your requirements.

Plumego intentionally does not include:

  • ORM layers
  • Configuration systems
  • Background job frameworks
  • Caching abstractions
  • Messaging systems

Not because these are unimportant,
but because they are highly context-dependent.

Plumego prefers to integrate with existing, proven solutions rather than reinvent them.

7. Long-Term Maintainability as a First-Class Goal

Code is read far more often than it is written.

Plumego is designed with the assumption that:

  • Teams change
  • Context is lost over time
  • Systems must evolve without full rewrites

Therefore, Plumego optimizes for:

  • Readability over terseness
  • Consistency over flexibility
  • Stability over novelty

The goal is not to be impressive today,
but to remain trustworthy years from now.

8. Engineering Judgment Over Framework Authority

Frameworks should not make irreversible decisions for engineers.

Plumego avoids:

  • Strong opinions about data modeling
  • Enforced architectural patterns
  • Global configuration that cannot be escaped

Instead, it provides:

  • Sensible defaults
  • Clear extension points
  • Well-defined boundaries

Plumego expects engineers to take responsibility for their systems.

This is not a weakness — it is the point.

A Coherent Set of Tradeoffs

These principles are tightly connected.

Together, they explain why Plumego:

  • Feels more explicit than many frameworks
  • Avoids aggressive abstraction
  • Prioritizes stability over features
  • Accepts verbosity as a cost of clarity

None of these principles are universally correct.

They are correct only if you share the same priorities.

Summary

Plumego is built on a small number of deeply held beliefs:

  • The standard library is enough, if used well
  • Explicit code is easier to maintain than clever code
  • Frameworks should define boundaries, not hide complexity
  • Long-term maintainability is worth short-term cost

If these beliefs resonate with you, Plumego is designed for you.

If they do not, Plumego encourages you to choose a different tool — without apology.

Next

To understand what Plumego gives up in order to uphold these principles, continue with:

→ Tradeoffs