# ADR 001: UI and server code layout

## Status

Accepted

## Context

The codebase serves multiple portals (master dashboard, customer tenant portal) from a single Next.js app. Without a clear layout convention, shared UI and route-specific UI can drift into ambiguous locations.

## Decision

- **Portal routes and page-specific UI** live under `app/` (e.g. `app/customer/[tenant]/…`, `app/dashboard/…`).
- **Shared cross-portal UI** (forms, tables, settings shells, design-system wrappers) lives under `components/`.
- **Server-only helpers** (auth, upstream API clients, normalization, caching) live under `lib/server` and route-local `_lib/` folders next to the handlers that use them.

Route `_lib/` folders hold code that is specific to one portal module (customer dashboard widgets, report BFFs). Promote to `lib/server` or `components/` only when a second consumer appears.

## Consequences

- New customer report pages: UI in `app/customer/…`, shared report primitives in `app/customer/[tenant]/reports/_shared/` or `components/` when reused outside reports.
- New master admin screens: page + `_components` under `app/dashboard/…`; extract to `components/` when a customer or master screen needs the same building block.
- Fixtures and mock seed data: colocate as `*.fixtures.ts`, `*.mock.ts`, or under `__fixtures__/` near the feature; avoid mixing production data paths with demo seeds.