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

6. Public Commission Request Submission

1. Visitor opens /{locale}/commissions and submits request form.
2. Server action validates input through shared schema.
3. Existing customer is reused by email (and marked recurring) or a new customer is created.
4. A new commission is created in new status and linked to the resolved customer.

Key files:

• apps/web/src/app/[locale]/commissions/page.tsx
• packages/content/src/commissions.ts
• packages/db/src/commissions.ts

7. Public Portfolio Rendering

1. Visitor opens /{locale}/portfolio with optional group filter query.
2. Public app loads published portfolio groups and filtered published artworks.
3. Artwork cards render preferred rendition preview (card > thumbnail > full).
4. Image bytes are streamed through web media endpoint using configured storage provider fallback.

Key files:

• apps/web/src/app/[locale]/portfolio/page.tsx
• apps/web/src/app/[locale]/portfolio/[slug]/page.tsx
• apps/web/src/app/api/media/file/[id]/route.ts
• apps/web/src/lib/media/storage-read.ts
• packages/db/src/media-foundation.ts