Architecture

This section describes how to structure real systems built with Plumego.

It is not about framework internals,
and it is not a collection of patterns to blindly copy.

Instead, it focuses on architectural decisions that determine whether a system can evolve safely over time.

If you skip this section, Plumego will still work —
but the risk of long-term architectural drift increases significantly.

What This Section Is About

The Architecture section answers questions such as:

• How should a Plumego application be layered?
• Where should framework code stop?
• How do we prevent HTTP and infrastructure concerns from leaking inward?
• How should domain logic and use cases be structured?
• How do we control dependency direction in Go?
• How can a system grow from a monolith into multiple services without collapse?

These questions are independent of Plumego’s APIs.
They are engineering questions, not framework questions.

What This Section Is Not

This section deliberately does not cover:

• How to register routes
• How middleware works
• How to write handlers
• How to configure the server

Those topics are covered in Concepts and Guides.

Architecture is about shape and constraints, not mechanics.

Design Assumptions

The guidance in this section assumes that:

• The system is expected to live for more than a short experiment
• Multiple engineers may work on it over time
• Requirements will change
• Parts of the system may need to be replaced or split

If none of these apply, the guidance here may be unnecessary overhead.

How to Read This Section

The documents in this section are meant to be read in order.

Each builds on the previous one and introduces constraints gradually.

Recommended order

1. Layering
   Defines the basic structure and responsibility boundaries.

2. Boundary Definition
   Explains where translation must occur and how to protect the core.

3. Domain and Usecase
   Clarifies the separation between business rules and application behavior.

4. Dependency Direction
   Shows how to keep the architecture intact as the codebase grows.

5. Monolith to Services
   Describes how to evolve the system without premature distribution.

Skipping steps often leads to misunderstandings later.

Plumego’s Architectural Stance

Plumego does not enforce architecture mechanically.

Instead, it:

• Keeps the framework surface small
• Avoids implicit coupling mechanisms
• Makes boundaries visible
• Relies on engineering discipline

This section exists to help teams use that freedom responsibly.

When This Section Matters Most

You should pay close attention to this section if:

• You are starting a new long-lived service
• You are refactoring an existing Plumego codebase
• You are onboarding new engineers
• You are considering splitting services
• You want to avoid framework lock-in

Architecture decisions made early tend to compound.

Summary

The Architecture section is about making change safe.

It provides:

• Clear layering guidance
• Explicit boundary definitions
• Correct dependency direction
• A path for controlled system evolution

Plumego gives you the tools.
This section explains how to use them without breaking your system.

Next

If you are new to Plumego, you may want to review:

→ Concepts — to understand how the framework works

If you are ready to apply Plumego in production:

→ Guides — practical solutions for real-world problems

Both build on the architectural foundations defined here.