Plumego Documentation

Welcome to Plumego

Plumego is a minimal, standard-library-first service framework for Go.

It is designed for engineers who care less about short-term convenience,
and more about long-term maintainability, architectural clarity, and predictable behavior.

Plumego does not attempt to be a “batteries-included” solution.
Instead, it provides a stable engineering skeleton on top of Go’s standard library,
allowing you to build services that remain understandable and evolvable over many years.

Before You Continue: Is Plumego the Right Choice?

This documentation is intentionally opinionated.

Before reading further, you should understand what Plumego is and is not.

Plumego might be a good fit if you:

Build long-lived services rather than short-term prototypes
Prefer explicit structure over implicit framework magic
Value predictability and debuggability over minimal lines of code
Are comfortable working close to Go’s standard library
Want a framework that can be copied, adapted, and evolved, not locked in

Plumego is likely not a good fit if you:

Need to ship an MVP as fast as possible
Rely heavily on large framework ecosystems or plugins
Expect the framework to make architectural decisions for you
Optimize primarily for development speed rather than system longevity
Prefer highly opinionated, feature-rich frameworks

If you are unsure, start with these documents:

What is Plumego
Design Philosophy
Tradeoffs
When Not to Use Plumego

They are intentionally placed first for a reason.

How This Documentation Is Structured

This documentation is organized by decision layers, not by API listings.

Each section exists to answer a specific type of question at a specific stage of adoption.

1. Intro — Understanding the Framework

“Should I use Plumego at all?”

This section explains Plumego’s goals, philosophy, tradeoffs, and boundaries.
No code, no tutorials — only architectural reasoning.

2. Getting Started — Running Your First Service

“I’ve decided to try Plumego. How do I get it running?”

Minimal steps to create a working Plumego service without introducing unnecessary complexity.

3. Concepts — Building a Mental Model

“How does Plumego actually work?”

Core concepts such as request lifecycle, context, middleware, handlers, and error handling.
This is the most important section for correct long-term usage.

4. Architecture — Structuring Real Systems

“How do I organize a serious project around Plumego?”

Guidance on layering, boundaries, dependency direction, and evolving from monoliths to services.

5. Core — Framework Capabilities Explained

“What exactly does Plumego provide?”

Precise explanations of Plumego’s core components, their responsibilities, and their limits.

6. Guides — Practical Integration

“How do I solve real problems with Plumego?”

Logging, tracing, authentication, graceful shutdown, WebSocket, Webhooks, and more —
always with explicit tradeoffs and no hidden magic.

7. Patterns — Recommended Ways of Working

“What has proven to work well?”

Non-mandatory patterns and practices derived from real-world usage.

8. Advanced — Customization and Extension

“How do I push Plumego further without breaking it?”

Performance tuning, component replacement, embedding, and multi-service setups.

9. Reference — Lookup-Oriented Documentation

“I know what I’m doing. I just need exact details.”

API references, configuration options, and formal definitions.

10. FAQ — Common Questions and Misconceptions

“Is Plumego like framework X?”

Clear, direct answers to recurring comparison and usage questions.

11. Roadmap — Evolution and Non-Goals

“Where is Plumego going — and where is it explicitly not going?”

Planned features, versioning strategy, and clearly stated non-goals.

12. Contributing — Governance and Collaboration

“How do decisions get made?”

Contribution philosophy, decision process, and long-term governance model.

A Note on Tone and Expectations

This documentation intentionally avoids:

Marketing language
Over-promising capabilities
Hiding complexity behind abstractions

Plumego assumes its users are engineers who want to understand their systems,
not just assemble them.

If that resonates with you, continue reading.

If it doesn’t, that is a valid and responsible conclusion as well.

Next Steps

If you are new here, start with:

→ Intro / What is Plumego

If you are ready to build:

→ Getting Started / Minimal Server

If you are deciding not to use Plumego:

→ Intro / When Not to Use Plumego

All three are equally valid outcomes.