How it works
The one rule
Data flows in one direction, layer by layer, and no layer is skipped:
- Middlewarerequest id, logging, auth, tenancy, permissions
internal/app/routes.go - Handlerbind + validate → call service → respond
modules/<m>/handler.go - Servicebusiness rules, tenancy, transactions, activity
modules/<m>/service.go - RepositorySQL via sqlc, maps rows ↔ domain
modules/<m>/repository.go - PostgreSQLgenerated queries (internal/dbgen)
migrations/ + sql/queries/
- Handlers don’t touch SQL. They decode the request, call one service method and write the response.
- Services don’t know about HTTP. They hold the business rules, so the same method serves an HTTP request, a CLI command, a queue job or a scheduled task.
- Repositories don’t know about HTTP or the current user. They take explicit parameters
(
tenantID,tenancy.Filter) and run generated SQL.
That is the whole architecture. Everything else is a consequence of it.
A request, end to end
Here is POST /api/v1/branch from the wire to the database and back.
1. The route declares the permission (internal/modules/branches/routes.go) — Laravel’s
->middleware('can:branch.create'):
r.With(h.can(authz.PermBranchCreate)).Post("/branch", h.store)Before the handler runs, middleware has already assigned a request id, authenticated the bearer token and resolved the tenant for this request.
2. The handler binds and delegates (handler.go):
func (h *Handler) store(w http.ResponseWriter, r *http.Request) { var req InsertUpdateRequest if !h.Bind(w, r, &req) { // decode + validate; the 400/415/422 is already written return } branch, err := h.service.Create(r.Context(), tenancy.From(r), authn.UserID(r), req.toInput()) if err != nil { h.Error(w, r, err) // any error becomes an RFC 9457 problem response return } h.Data(w, r, http.StatusCreated, NewResponse(*branch)) // {"data": {...}}}3. The service applies the rules (service.go): it reads the tenant from the scope it was
given, checks the plan’s branches.max quota, writes inside a transaction and records an
activity entry.
4. The repository runs generated SQL (repository.go), calling internal/dbgen — code that
sqlc generates from the SQL in sql/queries/branches.sql. The tenant id is a
parameter of every tenant-scoped query.
5. The response goes back up the same path: domain struct → response DTO → JSON envelope.
Laravel → this codebase
| Laravel | Here |
|---|---|
| Controller method | handler method on a type embedding httpx.Kit |
Form request ($request->validated()) |
h.Bind(w, r, &req) with validate:"…" struct tags |
->middleware('can:x') |
r.With(h.can("x")) on the route |
auth()->id() |
authn.UserID(r) |
| Eloquent model + global scope | repository + explicit tenancy.Filter in SQL |
DB::transaction() |
s.tx.WithTx(ctx, func(q *dbgen.Queries) error { … }) |
config/*.php |
internal/config/*.go, one file per section |
| Artisan command | Cobra command in internal/cli (ims <command>) |
| Queued job | queue.Definition registered in a queue.Registry |
Kernel::schedule() |
the task list in internal/app/schedule.go |
Cache::remember() |
cache.Remember(ctx, store, key, ttl, fn) |
| Feature test | testkit.New(t) + app.As(user).Post(...) |
| spatie/laravel-activitylog | activity.Recorder.Record(ctx, activity.Entry{…}) |
| Telescope / Horizon | the developer dashboard at /dev |
Two places things get wired
The composition root (internal/app) builds every dependency explicitly — there is no container
or reflection:
platform.gobuilds what every mode shares (HTTP, CLI, workers, scheduler): database pools, cache, queue, storage, mail and the shared services. They hang off thePlatformstruct.wiring.gobuilds the HTTP-only pieces — handlers — on theDependenciesstruct, androutes.gomounts them into route groups.
Route groups
Every route lives in one of these groups (internal/app/routes.go):
| Group | Middleware | Examples |
|---|---|---|
| Public | none | /up, /api/health, login, password reset, public packages, gateway callbacks |
| Authenticated | bearer token | logout |
| Tenant-resolved | token → resolve tenant & branch | users, branches, roles, settings, flags, files of a tenant, billing status |
| Tenant-exempt | token → exempt (+ internal-only) | tenants, permissions, internal users/roles, packages, internal billing |
| Dashboard | dashboard enabled → token → exempt → dev.view |
/dev, /dev/api/* (mutations add dev.manage) |
Next: find your way around the folders in the Project tour.