# Phase 9: Backend admin authentication and schema pipeline - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-09-23
**Phase:** 09-backend-admin-authentication-and-schema-pipeline
**Areas discussed:** Admin identity and login, Schema pipeline shape, Admin CRUD API contract, Relation manager and settings

---

## Admin identity and login

| Option | Description | Selected |
|--------|-------------|----------|
| Winter-shaped tables | backend_users + backend_user_roles, groups skipped, is_superuser and role codes kept | ✓ |
| Lean admin model | One summer_admins table with role string and permissions JSON | |
| Reuse frontend users table with a flag | is_backend + role on users | |

**User's choice:** Winter-shaped tables

| Option | Description | Selected |
|--------|-------------|----------|
| JWT via a `backend` bouncer guard | Second guard beside `jwt`, own secret and audience, reuses Phase 7 mint/verify/blacklist | ✓ |
| Cookie sessions with scs | HttpOnly cookie, Postgres session store, CSRF | |
| You decide | | |

**User's choice:** JWT via a `backend` bouncer guard

| Option | Description | Selected |
|--------|-------------|----------|
| Winter strings with wildcard | HasPermissions in registerPermissions shape, is_superuser, role JSON, `.*` prefix match, RequiredPermissions() enforced by framework | ✓ |
| Flat permission list, no wildcards | Exact match only | |
| You decide | | |

**User's choice:** Winter strings with wildcard

| Option | Description | Selected |
|--------|-------------|----------|
| Console command | `summer admin:create` + `admin:reset-password` | ✓ |
| Seeded from config | Boot-time superuser from YAML/env | |
| Both | Command canonical, env seed opt-in | |

**User's choice:** Console command

---

## Schema pipeline shape

| Option | Description | Selected |
|--------|-------------|----------|
| Winter layout | config_form/config_list point at models/<model>/fields.yaml and columns.yaml; scaffold updated | ✓ |
| Scaffold layout | Keep controllers/<name>/fields.yaml as Phase 4 emits | |
| You decide | | |

**User's choice:** Winter layout

| Option | Description | Selected |
|--------|-------------|----------|
| Typed schema, Winter key names | Go structs per field type, unknown keys fail, Winter spelling in JSON | ✓ |
| Pass-through map | Generic map served as-is | |
| Typed schema, normalized names | snake_case house style | |

**User's choice:** Typed schema, Winter key names

| Option | Description | Selected |
|--------|-------------|----------|
| Resolved server-side | phrasebook resolves labels in the admin's locale; SPA gets strings | ✓ |
| Raw keys plus a lang bundle endpoint | SPA resolves locally | |
| Both fields | label and labelKey side by side | |

**User's choice:** Resolved server-side

| Option | Description | Selected |
|--------|-------------|----------|
| Options provider interface on the model | DropdownOptions(field) []Option; static YAML maps also work | ✓ |
| Registry keyed by method name | Controller registers a map of func by name | |
| You decide | | |

**User's choice:** Options provider interface on the model

---

## Admin CRUD API contract

| Option | Description | Selected |
|--------|-------------|----------|
| /_admin/api/v1, plain JSON, no envelope | Plain resource bodies, `{message, errors}` errors | |
| Reuse the fonoteka house envelope | Same helpers as /_fonoteka/api/v1 | |
| You decide | | |

**User's choice:** Free text: "Do you really recommend 1? Our chance to introduce nice and consistent api layer." Claude proposed a framework-wide layer (plugin-namespaced paths, one envelope with a fixed error-code vocabulary, one list contract, one verb set, relation endpoints under the record, swag-annotated framework package). User: "Yes, let's proceed with that."
**Notes:** Recorded as D-09 to D-11.

| Option | Description | Selected |
|--------|-------------|----------|
| Winter list features only | search, sort, dir, page, recordsPerPage, relation columns | |
| Add per-column filters | filter[column]=value exact matches | |
| You decide | | |

**User's choice:** Free text: "Filters in Winter are done with config_filters.yaml we need filters like that here." Claude found the user and journal plugins' config_filter.yaml files (switch, daterange, model-backed scope) and asked about scope coverage and raw SQL `conditions:`. User: "Port 3 shapes now, note for future phases that this will be extended and all shapes will be introduced in time. Model scope methods instead of SQL strings are fully acceptable."
**Notes:** Recorded as D-12; remaining scope types deferred.

| Option | Description | Selected |
|--------|-------------|----------|
| Optional interfaces on the controller | Type-asserted hooks with admin principal in context; bulk delete per record | ✓ |
| Struct of func fields | Optional func fields on AdminController | |
| You decide | | |

**User's choice:** Optional interfaces on the controller

| Option | Description | Selected |
|--------|-------------|----------|
| Port the email mapping | Admin email must match exactly one frontend user; reuse its active collection; 422 otherwise | ✓ |
| Explicit collection picker | SPA header on every request | |
| Both | Mapping default, header override for superusers | |

**User's choice:** Port the email mapping

---

## Relation manager and settings

| Option | Description | Selected |
|--------|-------------|----------|
| config_relation.yaml as a first-class schema | Typed relation schema; `type: relation-manager` replaces `partial` | ✓ |
| Keep `partial` as an alias | Map partial to relation manager | |
| You decide | | |

**User's choice:** config_relation.yaml as a first-class schema

| Option | Description | Selected |
|--------|-------------|----------|
| Pivot fields stamped by the framework hook | RelationBeforeLink stamps role, granted_at, granted_by; unlink deletes pivot | ✓ |
| Bare pivot insert | Only the two foreign keys | |
| You decide | | |

**User's choice:** Pivot fields stamped by the framework hook

| Option | Description | Selected |
|--------|-------------|----------|
| HasSettings capability + singleton model | registerSettings shape, /settings/{code} GET/PUT via Fillable | ✓ |
| Settings as an ordinary admin controller | Form with no list, hand-written per page | |
| You decide | | |

**User's choice:** HasSettings capability + singleton model

| Option | Description | Selected |
|--------|-------------|----------|
| HasNavigation in Winter's shape, URL becomes a route key | url replaced by controller ID; /navigation filtered by permissions | ✓ |
| Winter shape with literal URLs | Keep url strings | |
| You decide | | |

**User's choice:** HasNavigation in Winter's shape, URL becomes a route key

---

## Claude's Discretion

- Package naming and layout for the admin API and schema packages.
- YAML parse timing (boot vs lazy), `rules:` in fields.yaml vs model Rules().
- Admin login throttling and password policy.
- Soft-deleted rows in admin lists; settings row creation timing; relation candidate pagination.

## Deferred Ideas

- Remaining Winter filter scope types.
- backend_user_groups, preferences, access logs.
- Policy-based row/field-level permissions.
- Boot-time admin seed from environment.