The architecture: a modular monolith, layer by layer

You have the project. This chapter is the map: how the code is arranged, which layer is allowed to call which, and why those rules exist. Get this and everything in part five is predictable.

The short answer

A modular monolith with a layered API and an in-process event bus. One binary, one database, about fifty internal packages.

That is the headline and it is slightly misleading, because no real system is one style. A Grit project runs six at once, each where it earns its keep:

• Modular monolith
• The whole API: one deployment, one transaction boundary
• Layered (n-tier)
• routes, handlers, services, models
• Event-driven
• internal/events: a write emits once, subscribers react
• Transactional outbox
• internal/outbox: durable delivery of those events
• Orchestration
• internal/saga: multi-step work that can half fail
• Microkernel
• The framework itself: grit plugin add

The request path

Follow one request all the way down. This is the shape every generated resource has.

HTTP request
  -> routes       which URL maps to which handler, and what guards it
  -> middleware   auth, CORS, rate limit, recover, request id
  -> handler      read the request, call one service method,
                  write the answer
  -> service      the rules, and every database call
  -> model        the struct, its GORM tags, its hooks
  -> database

Each layer talks only to the one below it. A handler never touches the database; a model never calls a service.

The rule the layering exists for

Handlers are thin on purpose, and the reason is not tidiness.

// A generated handler, in essence.
func (h *ContactHandler) List(c *gin.Context) {
    opts := paginate.FromQuery(c, contactListConfig)
    result, err := h.service().List(h.ctx(c), opts)
    if err != nil {
        respond.Error(c, err)
        return
    }
    respond.Paginated(c, result)
}

Read the request, call one method, write the answer. Every rule lives one layer down, in the service.

The payoff: a rule enforced in the service is enforced everywhere. The background job uses it. The CSV import uses it. The CLI command uses it. The test uses it. A rule written in a handler holds until the first time something other than a browser does the same thing, and then it silently does not.

// Every service method takes a context, not a *gin.Context.
func (s *ContactService) List(ctx context.Context,
    opts paginate.Options) (*paginate.Result[models.Contact], error)

That signature is the whole architecture in one line. context.Context rather than *gin.Context means the service has no idea it is being called over HTTP, so a job can call it with context.Background().

Where the rules live, concretely

Open any generated service and you find three things above the methods:

// What a client may search, sort and filter by. Whitelisted, because each
// name ends up in SQL.
var contactListConfig = paginate.Config{
    Searchable: []string{"name", "phone"},
    Sortable:   map[string]bool{"id": true, "created_at": true,
        "name": true, "phone": true},
    Filterable: map[string]bool{"id": true, "name": true,
        "phone": true, "group_id": true},
}

// Every column Patch and Bulk may write. id, the timestamps and
// the version are the framework's, and are dropped.
var writableContact = map[string]bool{
    "name": true, "phone": true, "group_id": true,
}

These are the answer to chapter twenty two's warning that a column name cannot be a placeholder. The client sends ?sort=name, and name is checked against a map the generator wrote, rather than being interpolated into SQL.

The event bus

A write emits once, and the systems that care subscribe.

events.Emit(c, events.Event{
    Name: "invoices.paid", Resource: "invoices", ID: inv.ID, After: inv,
})

The audit log, outbound webhooks and realtime clients are subscribers, not calls the handler has to remember. Adding a fourth consumer does not mean editing every handler.

Three delivery modes, and choosing correctly matters:

• Sync
• Runs inline, before the response. For the audit record, which must be written before the caller is told the write succeeded. A slow Sync subscriber is a slow endpoint
• Async
• Runs on a worker pool after the handler returns. For anything with a network call: a webhook that takes four seconds must not make the API take four seconds
• Durable
• Through the transactional outbox: at least once, retried, surviving a restart. For work another module depends on

Durable is the one worth understanding, because it is the difference between an event system and a reliable one. The event is written *in the same database transaction as the data*, so a crash between the commit and the HTTP call loses nothing. A relay then delivers it, claiming messages with a lease so another replica takes over if one dies.

What it deliberately is not

Four, each with a reason rather than a dismissal:

Not microservices. One binary by design. A split is worth paying for when teams need to release independently, and until then it buys network failures and a deployment pipeline in exchange for nothing.

Not CQRS or event sourcing. Both earn their complexity in a hot spot, not across a codebase. The read path is already separate enough to point at another store when one query needs it.

Not hexagonal. The generated service talks to GORM directly rather than through a port. Less indirection to read, at the cost of swapping the ORM being real work. That is a trade, stated as one.

Not serverless. Jobs, a scheduler, realtime connections and a warm pool all assume a process that stays up.

Organised by layer, not by feature

A fair question, since package-by-feature is what many Go teams land on: why is it models/, services/, handlers/ rather than invoice/,customer/?

What feature folders buy is real: a feature is a folder, you can delete one by deleting a directory, and the root stops growing. At forty resources Grit'sservices/ is forty files and the directory stops telling you which three form a subsystem.

What the layered layout buys back is the entity graph. A business application has thirty entities pointing at each other: invoice to customer to organisation and back. Go forbids import cycles, so with feature folders the momentcustomer refers to invoice you need an event or an interface dance to express what is really a foreign key.

Grit's thirty-odd models are one flat package models. Any model can reference any other with no ceremony, which is what lets client:belongs_to be a single word in a generate command rather than a design conversation.

Can you refactor to something else?

Yes, and the useful part of the answer is this: *what decides whether a refactor is a weekend or a quarter is almost never the code. It is the data.*

Moving a package is easy. Moving a table out from under three foreign keys, two joins and an admin screen that lists both sides of a relationship is the real work, and no amount of clean code makes it cheaper.

• CQRS on one endpoint
• hours
• The read path is already a separate whitelist. Point one query at a read replica
• Extract one module
• weeks
• The service is the seam. The cost is the foreign keys you must cut
• Fully hexagonal
• ongoing
• Mechanical, and the generator keeps writing the un-ported version
• Microservices
• months
• Only with an organisational reason. "It will scale" is not one
• Event sourcing
• a rewrite
• State stops being a row. Not a refactor
• Collapse services in
• weeks
• Easier than the reverse, and often the right direction

cd bookshop
grit start

Assignment

Commit your work with the message Architecture - Assignment One, exactly as written, so the leaderboard can score it.