docs(adr): rename ADR-012 — drop Lazar; update title + content + cross-refs
- Rename docs/decisions/adr-012-lazar-conformance.md → adr-012-feature-conventions.md - Strip "Lazar", "Plan 8/9/10/11", "refactor-logs" refs from all ADRs, architecture docs, HTML explainers, and feature/core AGENTS.md files - Update all incoming links in docs/, packages/*/AGENTS.md, HTML explainers Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -8,33 +8,33 @@ Users collection + authentication use cases (sign-in, sign-up, sign-out). Provid
|
||||
|
||||
## Layer responsibilities
|
||||
|
||||
| Layer | Key files |
|
||||
|---|---|
|
||||
| **entities/models** | `user.ts`, `session.ts`, `cookie.ts` — Zod schemas + inferred types |
|
||||
| **entities/errors** | `auth.ts` (AuthenticationError, UnauthenticatedError, UnauthorizedError), `common.ts` (InputParseError) |
|
||||
| **application/use-cases** | `sign-in.use-case.ts`, `sign-up.use-case.ts`, `sign-out.use-case.ts` — factory functions + exported schemas |
|
||||
| **application/repositories** | `users.repository.interface.ts` — `IUsersRepository` |
|
||||
| **application/services** | `authentication.service.interface.ts` — `IAuthenticationService` |
|
||||
| **infrastructure/repositories** | `users.repository.ts` (real Payload-backed), `users.repository.mock.ts` (in-memory) |
|
||||
| **infrastructure/services** | `authentication.service.ts` (real Payload-backed), `authentication.service.mock.ts` (in-memory) |
|
||||
| **interface-adapters/controllers** | `sign-in.controller.ts`, `sign-up.controller.ts`, `sign-out.controller.ts` — one file per use case |
|
||||
| **di** | `symbols.ts` (AUTH_SYMBOLS), `module.ts`, `container.ts`, `bind-production.ts` |
|
||||
| **integrations/api** | `procedures.ts` (authProcedure), `router.ts` (authRouter) |
|
||||
| **integrations/cms** | `collections/users.ts` — Payload Users CollectionConfig |
|
||||
| **ui** | `src/ui/index.ts` — placeholder (auth is mutations only; no query builders today) |
|
||||
| Layer | Key files |
|
||||
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| **entities/models** | `user.ts`, `session.ts`, `cookie.ts` — Zod schemas + inferred types |
|
||||
| **entities/errors** | `auth.ts` (AuthenticationError, UnauthenticatedError, UnauthorizedError), `common.ts` (InputParseError) |
|
||||
| **application/use-cases** | `sign-in.use-case.ts`, `sign-up.use-case.ts`, `sign-out.use-case.ts` — factory functions + exported schemas |
|
||||
| **application/repositories** | `users.repository.interface.ts` — `IUsersRepository` |
|
||||
| **application/services** | `authentication.service.interface.ts` — `IAuthenticationService` |
|
||||
| **infrastructure/repositories** | `users.repository.ts` (real Payload-backed), `users.repository.mock.ts` (in-memory) |
|
||||
| **infrastructure/services** | `authentication.service.ts` (real Payload-backed), `authentication.service.mock.ts` (in-memory) |
|
||||
| **interface-adapters/controllers** | `sign-in.controller.ts`, `sign-up.controller.ts`, `sign-out.controller.ts` — one file per use case |
|
||||
| **di** | `symbols.ts` (AUTH_SYMBOLS), `module.ts`, `container.ts`, `bind-production.ts` |
|
||||
| **integrations/api** | `procedures.ts` (authProcedure), `router.ts` (authRouter) |
|
||||
| **integrations/cms** | `collections/users.ts` — Payload Users CollectionConfig |
|
||||
| **ui** | `src/ui/index.ts` — placeholder (auth is mutations only; no query builders today) |
|
||||
|
||||
## Public exports
|
||||
|
||||
| Subpath | Contents |
|
||||
|---|---|
|
||||
| `.` | `User`, `Session`, `Cookie` types; `AuthenticationError`, `UnauthenticatedError`, `UnauthorizedError`, `InputParseError`; `SESSION_COOKIE`; all use-case schemas + input/output types + `IXUseCase` aliases; `IXController` type aliases; `AuthRouter` type |
|
||||
| `./ui` | Placeholder — extend here when auth gains React Query builders, never re-add to root |
|
||||
| `./api` | `authRouter` (tRPC router) |
|
||||
| `./cms` | Payload Users collection definition |
|
||||
| `./di/bind-production` | `bindProductionAuth(ctx: BindProductionContext)` — swaps mock impls for real Payload-backed ones at app boot |
|
||||
| `./di/bind-dev-seed` | `bindDevSeedAuth(ctx: BindContext)` — replaces the default empty mock with a populated one for dev / Storybook |
|
||||
| `./di/container` | `authContainer` — the per-feature inversify container (consumed by e2e tests + production Payload event-tasks) |
|
||||
| `./di/symbols` | `AUTH_SYMBOLS` — DI symbol registry (consumed by e2e tests + production Payload event-tasks) |
|
||||
| Subpath | Contents |
|
||||
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `.` | `User`, `Session`, `Cookie` types; `AuthenticationError`, `UnauthenticatedError`, `UnauthorizedError`, `InputParseError`; `SESSION_COOKIE`; all use-case schemas + input/output types + `IXUseCase` aliases; `IXController` type aliases; `AuthRouter` type |
|
||||
| `./ui` | Placeholder — extend here when auth gains React Query builders, never re-add to root |
|
||||
| `./api` | `authRouter` (tRPC router) |
|
||||
| `./cms` | Payload Users collection definition |
|
||||
| `./di/bind-production` | `bindProductionAuth(ctx: BindProductionContext)` — swaps mock impls for real Payload-backed ones at app boot |
|
||||
| `./di/bind-dev-seed` | `bindDevSeedAuth(ctx: BindContext)` — replaces the default empty mock with a populated one for dev / Storybook |
|
||||
| `./di/container` | `authContainer` — the per-feature inversify container (consumed by e2e tests + production Payload event-tasks) |
|
||||
| `./di/symbols` | `AUTH_SYMBOLS` — DI symbol registry (consumed by e2e tests + production Payload event-tasks) |
|
||||
|
||||
## Use-case + controller patterns
|
||||
|
||||
@@ -42,35 +42,35 @@ See `CLAUDE.md` Key Conventions and `docs/architecture/overview.md` for the cano
|
||||
|
||||
### Use cases
|
||||
|
||||
| Use case | Input schema | Output schema | Notes |
|
||||
|---|---|---|---|
|
||||
| `signInUseCase` | `signInInputSchema` — `{ username, password }` | `signInOutputSchema` — `{ session, cookie }` | Throws `AuthenticationError` on bad credentials |
|
||||
| `signUpUseCase` | `signUpInputSchema` — `{ username, password, confirmPassword }` with `.refine` | `signUpOutputSchema` — `{ session, cookie }` | Throws `AuthenticationError` on taken username |
|
||||
| `signOutUseCase` | `signOutInputSchema` — `{ sessionId }` | void (no `xOutputSchema`) | Calls `authenticationService.invalidateSession` |
|
||||
| Use case | Input schema | Output schema | Notes |
|
||||
| ---------------- | ------------------------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------- |
|
||||
| `signInUseCase` | `signInInputSchema` — `{ username, password }` | `signInOutputSchema` — `{ session, cookie }` | Throws `AuthenticationError` on bad credentials |
|
||||
| `signUpUseCase` | `signUpInputSchema` — `{ username, password, confirmPassword }` with `.refine` | `signUpOutputSchema` — `{ session, cookie }` | Throws `AuthenticationError` on taken username |
|
||||
| `signOutUseCase` | `signOutInputSchema` — `{ sessionId }` | void (no `xOutputSchema`) | Calls `authenticationService.invalidateSession` |
|
||||
|
||||
### Controllers
|
||||
|
||||
| Controller | Presenter | Return type |
|
||||
|---|---|---|
|
||||
| `signInController` | `presenter(value) { return value.cookie; }` | `ReturnType<typeof presenter>` (Cookie) |
|
||||
| `signUpController` | `presenter(value) { return value.cookie; }` | `ReturnType<typeof presenter>` (Cookie) |
|
||||
| `signOutController` | none (void) | `Promise<void>` |
|
||||
| Controller | Presenter | Return type |
|
||||
| ------------------- | ------------------------------------------- | --------------------------------------- |
|
||||
| `signInController` | `presenter(value) { return value.cookie; }` | `ReturnType<typeof presenter>` (Cookie) |
|
||||
| `signUpController` | `presenter(value) { return value.cookie; }` | `ReturnType<typeof presenter>` (Cookie) |
|
||||
| `signOutController` | none (void) | `Promise<void>` |
|
||||
|
||||
Controllers accept `unknown` input and `safeParse` with the use-case's `xInputSchema`, throwing `InputParseError` on failure.
|
||||
|
||||
## Real Payload implementations (Plan 8)
|
||||
## Real Payload implementations
|
||||
|
||||
- `UsersRepository` (`infrastructure/repositories/users.repository.ts`) — calls `getPayload({ config })` for `getUser`, `getUserByUsername`, and `createUser`. Receives `SanitizedConfig` at constructor time.
|
||||
- `AuthenticationService` (`infrastructure/services/authentication.service.ts`) — implements `hashPassword` and `verifyPassword` with Node.js `crypto` (pbkdf2). Three session-related methods (`createSession`, `validateSession`, `invalidateSession`) are **deferred** — they throw `NotImplementedError` with a reference to refactor log §7. The mock (`authentication.service.mock.ts`) handles all test paths.
|
||||
- `AuthenticationService` (`infrastructure/services/authentication.service.ts`) — implements `hashPassword` and `verifyPassword` with Node.js `crypto` (pbkdf2). Three session-related methods (`createSession`, `validateSession`, `invalidateSession`) are **deferred** — they throw `NotImplementedError`. The mock (`authentication.service.mock.ts`) handles all test paths.
|
||||
|
||||
## Errors → tRPC codes
|
||||
|
||||
| Error class | tRPC code | Thrown by |
|
||||
|---|---|---|
|
||||
| `InputParseError` | `BAD_REQUEST` | controllers (safeParse failure) |
|
||||
| `AuthenticationError` | `UNAUTHORIZED` | sign-in / sign-up use cases |
|
||||
| Error class | tRPC code | Thrown by |
|
||||
| ---------------------- | -------------- | ------------------------------- |
|
||||
| `InputParseError` | `BAD_REQUEST` | controllers (safeParse failure) |
|
||||
| `AuthenticationError` | `UNAUTHORIZED` | sign-in / sign-up use cases |
|
||||
| `UnauthenticatedError` | `UNAUTHORIZED` | future session-guard middleware |
|
||||
| `UnauthorizedError` | `FORBIDDEN` | future authorization checks |
|
||||
| `UnauthorizedError` | `FORBIDDEN` | future authorization checks |
|
||||
|
||||
Defined in `src/integrations/api/procedures.ts` via `authProcedure = t.procedure.use(defineErrorMiddleware([...]))`.
|
||||
|
||||
@@ -154,10 +154,9 @@ tests/
|
||||
- Any other feature package (`@repo/blog`, `@repo/media`, etc.)
|
||||
- Any app package
|
||||
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only `@repo/core-shared`
|
||||
> Note: `@repo/core-trpc` and `@repo/core-ui` are optional packages scaffolded via `pnpm turbo gen core-package trpc` / `ui`. If not present, these constraints still apply to any future installation.
|
||||
> Note: `@repo/core-trpc` and `@repo/core-ui` are optional packages scaffolded via `pnpm turbo gen core-package trpc` / `ui`. If not present, these constraints still apply to any future installation.
|
||||
|
||||
## Cross-links
|
||||
|
||||
- ADR-012 (`docs/decisions/adr-012-lazar-conformance.md`) — factory-style use cases, per-use-case controllers, file-naming conventions
|
||||
- ADR-012 (`docs/decisions/adr-012-feature-conventions.md`) — factory-style use cases, per-use-case controllers, file-naming conventions
|
||||
- ADR-013 (`docs/decisions/adr-013-input-output-unification.md`) — schemas-in-use-case, presenter, `./ui` subpath, error middleware
|
||||
- Refactor logs: `docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md` (Plan 8), `docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md` (Plan 9)
|
||||
|
||||
Reference in New Issue
Block a user