# Go Architecture Evolution Choose a stage from actual domain complexity, change patterns, and deployment boundaries. Do not skip stages merely to adopt a fashionable structure. ## Stage 1: small service Use a flat `internal/handler`, `service`, `repository`, and `model` layout for a small API or experiment. Keep startup under `cmd//`, private code under `internal/`, and only genuinely portable packages under `pkg/`. ## Stage 2: vertical modular monolith Group code by business capability under `internal//` when layer-wide packages create cross-domain coupling or recurring merge conflicts. Each module may own its handler, service, repository, and model. Cross-module access should use an injected module API, not direct access to another module's tables. Keep shared technical drivers under `internal/infra/`. Keep the composition root in `cmd//main.go` or a dedicated wiring package. ## Stage 3: ports and adapters within a monolith Introduce explicit `domain`, `usecase`, `port`, and `infra` boundaries when multiple transports, workers, persistence implementations, or independent testing needs justify the conversion cost. ```text port and infra -> usecase -> domain ``` `domain` owns business entities and consumer-facing repository interfaces. `port` contains HTTP, gRPC, consumer, and scheduler entrypoints. `infra` contains drivers and implementations. Do not add an interface for every concrete type; add one where the consuming layer needs substitution or isolation. ## Stage 4: services Split a vertical module into an independently deployed service only when business ownership, scaling, reliability, release cadence, or isolation justifies network and operational cost. Replace in-memory module calls with explicit network contracts and account for partial failure, compatibility, observability, and distributed data ownership. Do not treat extracting a directory and adding `main.go` as the complete migration. Service extraction changes transactions, latency, retries, deployment, and failure semantics.