Project Architecture

The Decisions That Outlive Every Line of Code

The repository we are about to create is empty. That is the best possible moment to make architectural decisions, because every choice made now is cheap to change and every choice made after the fifth service exists is expensive. This course builds a real HOA (Homeowners' Association) management platform: organizations (the societies themselves), residents, payments, complaints, visitors, and more will each become their own deployable service over the life of the course. Phase 1 exists to decide, once, how those services will be organized, configured, logged, and run locally — so that Phase 2 can spend its full attention on one service, Organization, without re-litigating infrastructure decisions.

Two structural decisions matter more than any framework choice: how many Go modules this repository will contain, and how much ceremony each service's internal package layout should carry. We answer both before writing main.go.

This is a fixed implementation baseline, not the course structure. No phase exists merely to tour a library: each dependency appears only when a service has a concrete problem it solves, and later services reuse that decision instead of reinstalling or reteaching it.

Layered Architecture, Not Ports-and-Adapters

The Go community's default advanced answer to 'how do I structure a service' is often hexagonal architecture: domain, application, ports, adapters. It is a good answer for a service with several outbound integrations and complex domain invariants. Organization is neither of those things yet — it is a CRUD-shaped resource with a small state machine (active, suspended, archived) and one dependency, PostgreSQL. Four-person teams shipping CRUD-heavy admin platforms pay a real productivity tax for hexagonal ceremony they do not need in year one.

Instead, every service in this platform uses a flat, layered package structure: model, dto, repository, service, handler. The only concession this course makes toward testability is that the repository is always consumed through an interface, so PostgreSQL can be swapped for a fake in unit tests and for a real, ephemeral container in integration tests. That single seam buys almost all of hexagonal architecture's testing benefit without its indirection cost.

Why One Monorepo, Not One Repository per Service

Every HOA service will share three concerns: how it reads configuration, how it logs, and how it represents a business error. Splitting those into a polyrepo today would mean either duplicating three small packages across ten repositories, or standing up a private module proxy and a release process for internal libraries before a single feature ships. Neither is worth it at this team size. A monorepo with independent Go modules gets the sharing without the release ceremony: every module is still separately versioned and separately buildable, but they live at predictable relative paths and are composed locally with go.work — the subject of the next lesson.

Recording the Decision as an ADR, Not Just a Conversation

A decision that only exists in someone's memory gets re-argued the day that person is on leave. We record it as an Architecture Decision Record (ADR): a short, dated, append-only markdown file that states the context, the decision, and the consequences the team accepted. The first ADR in this repository documents exactly the two decisions above — layered services and a monorepo — so a contributor joining in Phase 3 can read one file instead of asking in chat.

# 0001. Monorepo with layered services

## Status
Accepted

## Context
The HOA platform will grow into several deployable services (Organization first,
then Resident, Payment, Complaint, and more). Each service needs configuration
loading, structured logging, and a shared error vocabulary. We must decide the
repository shape and the internal package shape before any code exists.

## Decision
- One git repository ("hoa-platform") holds every service and shared package.
- There is no root go.mod. Every module (each service, each pkg/* library) owns
  its own go.mod and is composed locally through a single go.work file.
- Every service uses a flat layered package structure — model, dto, repository,
  service, handler — instead of hexagonal ports-and-adapters. The repository is
  always consumed through an interface so it can be faked in unit tests and
  replaced by a real, ephemeral container in integration tests.
- Each service owns exactly one database and is the only writer of its own
  tables. Other services never read another service's database directly.

## Consequences
- Shared code (env parsing, logging, semantic errors) lives once under pkg/ and
  is imported by services/, never the reverse.
- Adding a service means adding a new services/<name> module and one line in
  go.work — not restructuring an existing module.
- The team accepts that some future service may eventually need genuine
  hexagonal boundaries (multiple outbound integrations, complex domain rules).
  When that happens, it is scoped to that one service, not retrofitted
  everywhere.