old.cms.fellies.org/docs/product-engineering/request-lifecycle-flows.md

Request Lifecycle Flows

1. Auth Sign-In (Admin)

1. Browser posts to /api/auth/sign-in/email.
2. Route resolves identifier (email or username) to canonical email.
3. Better Auth credential sign-in executes.
4. Session cookie is set and user is redirected.

Key files:

• apps/admin/src/app/login/login-form.tsx
• apps/admin/src/app/api/auth/[...all]/route.ts
• apps/admin/src/lib/auth/server.ts

2. Initial Owner Registration

1. If no owner exists, /welcome renders owner sign-up mode.
2. Sign-up request goes through auth route handler.
3. New user is promoted to owner in transactional guard.
4. Owner invariant is re-validated to enforce single owner.

Key files:

• apps/admin/src/app/welcome/page.tsx
• apps/admin/src/app/api/auth/[...all]/route.ts
• apps/admin/src/lib/auth/server.ts

3. Media Upload

1. Admin form posts multipart data to /api/media/upload.
2. Metadata is validated and file is stored through selected provider.
3. Media asset record is persisted with storage metadata.
4. UI redirects back to media list with flash status query.

Key files:

• apps/admin/src/components/media/media-upload-form.tsx
• apps/admin/src/app/api/media/upload/route.ts
• apps/admin/src/lib/media/storage.ts
• packages/db/src/media-foundation.ts

4. Page Publish

1. Admin submit on /pages calls server action.
2. Page schema validates payload and persists.
3. published status sets publication fields.
4. Public app resolves slug and renders page if published.

Key files:

• apps/admin/src/app/pages/page.tsx
• packages/db/src/pages-navigation.ts
• apps/web/src/app/[locale]/[slug]/page.tsx

5. Commission Status Transition

1. Admin updates status from commission card form.
2. Server action validates transition payload.
3. DB update persists new status.
4. Kanban view re-renders with updated column placement.

Key files:

• apps/admin/src/app/commissions/page.tsx
• packages/db/src/commissions.ts