# ADR 019: New Module Golden Path and Ownership Rules

**Status**: Accepted
**Date**: 2026-04-19
**Deciders**: Architecture Lead, Engineering Lead

---

## Context

The hardest moment to maintain architectural discipline is at module creation. If creating a "correct" module is harder than dumping code into `lib/utils/`, developers will dump. The golden path must be the easiest path.

## Decision

Provide an automated scaffolding command:

```
npm run new:module -- <module-name>
```

It creates a clean module under `lib/<module>/` with:

```
lib/<module>/
  index.ts            ← public entrypoint (named exports only)
  README.md           ← purpose, owner, public API, dependencies
  internal/
    .gitkeep          ← for files not part of the public contract
  <module>.test.ts    ← Vitest placeholder
```

Optional flags: `--with-route` adds an `app/api/<module>/route.ts` placeholder; `--with-ui` adds `components/<module>/` placeholder.

### Ownership rules

1. Every module has a single named owner in its `README.md` (team or individual).
2. The public surface is whatever `index.ts` re-exports. Anything not re-exported is internal and may change without notice.
3. Tests for the module live next to it (`<module>/<module>.test.ts` or `__tests__/<module>/*`).
4. Cross-module access goes through `index.ts` only — no deep imports.

## Rules this decision creates

1. New top-level files in `lib/` are discouraged once the module pattern exists; new functionality goes into a module.
2. `npm run new:module` is the documented way to create a module; manual scaffolding is allowed but must produce the same shape.
3. PRs introducing a new module include the module README in the diff.
4. Renaming a module updates the public `index.ts` and the layer map in ADR 015.

## Consequences

### Forbidden

- Creating a new top-level `lib/<file>.ts` for non-trivial functionality without considering a module first.
- Modules without an owner or README.

### Accepted

- A small ceremony for each new module.

## Related

- ADR 011 — Modular monolith first
- ADR 015 — Architecture boundary enforcement