Folder Structure

internal/ Is a Compiler Rule, Not a Naming Convention

Go treats any package whose import path contains a directory literally named internal specially: it may only be imported by code rooted at the parent of that internal directory. For services/organization/internal/model, that parent is services/organization — so only code inside services/organization can import it. A future services/resident-service module physically cannot import services/organization/internal/model, even accidentally; the compiler refuses. This is the one architectural boundary from ADR 0001 that does not rely on code review to hold.

The Package Map Every Phase 2 Lesson Fills In

The Repository Map Is a Contract for Every Later Phase

Why cmd/api Deliberately Stays Nearly Empty

cmd/api/main.go is the only file allowed to import every internal package at once — it is the composition root, formalized properly in the Dependency Injection lesson. Keeping it thin (load config, construct dependencies, start the server) means it never accumulates business logic that would otherwise be untestable, since nothing outside _test.go files can import the main package.

Replacing the One-File Placeholder With a Real Composition Root

internal/server now owns constructing the HTTP listener. It is deliberately built on net/http alone — Gin does not arrive until the Service Bootstrap lesson in Phase 2 — so this lesson can prove the folder boundary works without pulling in a dependency that belongs to a later topic.

// Package server constructs the organization service's HTTP listener.
// Gin replaces the bare net/http mux in Phase 2's Service Bootstrap lesson;
// this placeholder exists only to prove the folder boundary compiles.
package server

import "net/http"

func New(addr string) *http.Server {
	mux := http.NewServeMux()
	return &http.Server{
		Addr:    addr,
		Handler: mux,
	}
}

package main

import (
	"log"

	"github.com/hoa-platform/backend/services/organization/internal/server"
)

func main() {
	srv := server.New(":8080")
	log.Printf("organization service listening on %s", srv.Addr)
	if err := srv.ListenAndServe(); err != nil {
		log.Fatalf("server stopped: %v", err)
	}
}

What the Compiler Actually Catches

To see the internal/ rule enforce itself, imagine a second module trying to reach into this one before it is even created. If a hypothetical services/resident-service/cmd/api/main.go contained import "github.com/hoa-platform/backend/services/organization/internal/model", compilation would stop with a specific, unambiguous message — not a lint warning, a hard build error.

use of internal package github.com/hoa-platform/backend/services/organization/internal/model not allowed

One boundary the compiler does not catch: a handler in internal/handler calling internal/repository directly, skipping internal/service. That would compile without complaint. Preventing it is a code-review discipline for now — the golangci-lint lesson later in this phase adds an automated depguard rule so this stops depending on review alone.

Running the Placeholder End to End