# Phase 9 — Super Administrator, Media Manager, Business Branding, Loyalty Redesign, Home Screen Redesign and Google Reviews: Summary

A large post-Phase-8 pass adding a platform-level administration account, a single reusable Media Manager that becomes the standard image picker everywhere, full post-install editability of every branding asset, a restyled and properly-configured loyalty card, a real Google Reviews pipeline, and a sticky-tabbed Home Screen redesign (Services/Portfolio/Reviews/Details) built on top of a new owner-managed gallery. Executed in nine dependency-ordered sub-phases (9.0–9.9, tracked as such in-session), each fully typechecked, linted, and integration-tested against a real MySQL database before moving to the next — no phase was left partially wired.

---

## 1. Super Administrator

A platform-level account with every Owner permission, provisioned from environment variables (`SUPER_ADMIN_EMAIL`/`PASSWORD`/`FIRST_NAME`/`LAST_NAME`) rather than the installation wizard — deliberately **not** a hidden staff member. It has no `StaffProfile` row at all, which is the whole design: every exclusion the brief asked for (not in the Team list, not selectable as a barber, never receives an appointment, not counted in staff totals, not in customer-facing staff lists) falls out **structurally** from that absence — `StaffProfile`-scoped queries simply never see it — rather than needing a filter added at each of the ~6 call sites that would otherwise need one.

`hasPermission()` (`src/lib/auth/permissions.ts`) short-circuits `true` for any permission when `User.isSuperAdmin` is set — safe because `OWNER_PERMISSIONS` already **is** the full `Permission` enum, so "all Owner permissions" and "unconditionally true" are the same thing. `scripts/ensure-super-admin.ts` is idempotent and re-hashes the password every run (wired into `docker/entrypoint.sh`, after migrations), so rotating `SUPER_ADMIN_PASSWORD` and restarting the container is how you change it; it refuses to silently take over an existing non-super-admin account with the same email.

**Real architectural cost, paid honestly rather than papered over**: every owner page that resolved its business via `getActingStaff()` (a `StaffProfile` lookup) would otherwise 403 a Super Administrator with no such profile. Rather than special-case each one, a new `getActingBusinessContext()` helper (`src/lib/business/get-acting-business-context.ts`) resolves `{userId, businessId, businessName, businessTimezone}` for **either** a real staff member **or** a Super Administrator (falling back to the app's one business, since v1 is single-business) — and all 16 owner pages/actions that only ever needed `businessId`/`timezone` from `getActingStaff()`, not real staff identity, were retrofitted onto it (verified per-file that none of them used `staff.id` for anything beyond the redirect gate). Pages doing genuine staff-ledger work (loyalty stamp authorship, appointment reassignment) still require real `StaffProfile` identity and are out of scope for this account by design — "purely for administration," per the brief.

---

## 2. Media Manager

No upload mechanism existed anywhere before this phase — every image field was a plain-text URL `Input`. Now there is exactly one: `MediaManagerModal` (Upload / Library / External URL tabs) plus the field-level `MediaPicker` wrapper (preview + Change + Remove), both in `src/features/media/components/`. It backs every image field migrated this phase: business logo, cover image, welcome backgrounds, favicon, PWA icon, loyalty card background, staff photo, service photo, and the new gallery/portfolio system.

- **Storage**: local disk under `public/media/<category>/...`, served for free by Next's own static file handling — no custom GET route needed, only the upload path (`src/lib/media/media-storage.ts`). A deliberate v1 choice for this app's single-container Docker model, not a cloud integration; `docker-compose.local.yaml` gained a `next-chair-media` named volume so uploads survive a rebuild, and the Dockerfile pre-creates `public/media` owned by the non-root user before that volume first attaches.
- **Schema**: new `MediaAsset` model (url, dimensions, size, mime type, category, uploader).
- **Upload path**: a Server Action (`src/features/media/actions/media.ts`), not a REST route — Next.js Server Actions accept `FormData`/`File` natively, so this stays consistent with every other mutation in the app rather than introducing a one-off API endpoint. SVG is rejected (stored-XSS risk via inline `<script>`); size capped at `MEDIA_MAX_UPLOAD_BYTES` (default 5MB); dimensions probed with the tiny, dependency-free `image-size` package rather than pulling `sharp`/libvips into the Alpine build.
- **Permissions, deliberately split**: uploading/browsing only requires being signed-in staff (or the Super Administrator) — a barber needs to add their own profile photo without an owner-only permission blocking them. **Deleting** an asset from the shared library requires the new `MANAGE_MEDIA_LIBRARY` permission (Owner/Super Admin), since a delete can affect images other fields/other staff reference.
- **Icon and colour pickers**, built alongside since the loyalty card designer needed both: `ColorPicker` (native swatch + hex text + presets) and `IconPicker` (searchable Font Awesome grid — a **curated** ~40-icon set via individual named imports, not the full ~2000-icon `fas` pack, both for a more relevant picker and to keep Font Awesome's path data out of bundles that don't need it).

---

## 3. Welcome Background Images

`Business.welcomeBackgroundDesktopUrl`/`welcomeBackgroundMobileUrl` — independent images (not one image cropped two ways), editable via two `MediaPicker` fields in Business Branding settings. The Welcome page (`src/app/page.tsx`) swaps between them with a plain Tailwind `hidden md:block` / `block md:hidden` pair of absolutely-positioned layers plus a bottom gradient scrim for text legibility, falling back to the existing plain `bg-ink` background when neither is set.

---

## 4. Business Branding Settings

Every asset configured during installation is now editable afterwards from one place (`/owner/settings/business`, "Branding" section): logo, cover image, welcome backgrounds, favicon, PWA icon, theme colour, background colour. `BusinessProfileInput`'s image/colour fields were changed from `string | undefined` to `string | null`, and are now always included on the update payload (rather than the previous `value || undefined` pattern) — this was a real, if minor, pre-existing gap: the old pattern made it structurally impossible to ever clear `logoUrl` back to empty once set, since `undefined` tells Prisma "don't touch this field," not "clear it." Fixed as part of migrating `logoUrl` onto `MediaPicker`, whose Remove button needs to actually clear the field.

Cover image was configured at install but **never rendered anywhere** — confirmed dead config. It now renders on the Home hero (falling back to the logo, then a plain background) and, once the owner adds Hero gallery images (§7), those take priority over it — a genuine fallback chain, not a value silently overridden.

---

## 5. Service Descriptions

`Service.description` already existed in the schema and was already fetched in the owner catalogue — it was simply never selected by the customer-facing `getAvailableServices()`/`ServiceSummary`/`AvailableService` types. Added to both, plus a collapsing (renders nothing when null/empty) paragraph in `ServiceCard` and the booking flow's `ServiceSelector`. The cheapest, safest change in the phase; verified end-to-end against real seeded data before moving on.

---

## 6. Loyalty Card Improvements

**A second real, if smaller, pre-existing gap fixed here**: `LoyaltyProgramme.cardBackgroundColor`/`cardBackgroundImageUrl`/`stampIcon` were stored and editable in the owner designer, but `LoyaltyCard` (the actual rendered component) never accepted or used any of the three — every business's card looked identical regardless of configuration. `getLoyaltySummary()` was also missing `cardBackgroundImageUrl` from its return type. Both fixed; verified end-to-end (owner sets background colour/image/icon → same values reach `getLoyaltySummary` → same values now genuinely change what `LoyaltyCard` renders).

- **Designer**: live preview (an actual `<LoyaltyCard>` rendered inline with the in-progress, unsaved form state), `ColorPicker` for background colour, `MediaPicker` for background image, `IconPicker` for the stamp icon (replacing free-text — `findCatalogIcon()` falls back gracefully for any legacy free-text value that doesn't match the curated set).
- **Customer card**: the 3D flip (front stamps / back a generic branding panel) is gone — `LoyaltyCard` is now a single static face, restyled with a CSS-only diagonal shine gradient and layered shadow for a "premium plastic card" feel, no extra image asset, so it stays cheap to render.
- **Navigation**: `(customer)/layout.tsx`'s bottom nav is now Home / Bookings / **Loyalty** / Profile (the `/settings` tab relabelled "Profile" to match; route unchanged).

---

## 7. Home Screen Redesign

The largest single piece, built last since it consumes almost everything above. Replaces the old flat, single-scroll Home page with: an owner-managed **hero gallery** (falls back gracefully all the way down to cover image → logo → plain background if empty) matching content width rather than bleeding edge-to-edge, followed by sticky **Services / Portfolio / Reviews / Details** tabs (`src/features/home/components/home-tabs.tsx`, built on the existing Radix `Tabs` primitive with `position: sticky`).

- **Services tab**: the full catalogue (not a 4-item preview), grouped by category, with a live client-side search box and category filter pills — all client-side state over data already fetched once server-side, not a network round trip per keystroke.
- **Portfolio tab**: owner-managed images with category badge filter pills.
- **Reviews tab**: the real (or demo-fallback) review data from §8, moved here instead of duplicating it on the flat page.
- **Details tab**: About Us, Staff, Opening Hours, and Social/Contact (website/Instagram/Facebook were fields on `Business` that were **never rendered anywhere customer-facing before** — confirmed and fixed here) — plus a map, via a **keyless** Google Maps embed iframe (`https://www.google.com/maps?q=<lat,lng or address>&output=embed`) using existing `BusinessLocation` coordinates, falling back to the street address when coordinates aren't set. Zero new dependency, zero API key needed for the map specifically (distinct from the Places API key §8 needs for reviews).

**Consolidation, not duplication**: Home's hero gallery and the Portfolio tab are powered by **one** new model (`BusinessGalleryImage`, discriminated by a `placement: HERO | PORTFOLIO` enum) and **one** service (`src/services/gallery/gallery.service.ts`) — not two near-identical "gallery" features. One owner page, `/owner/settings/gallery`, manages both sections (add via the Media Manager, up/down reorder, delete, and — Portfolio only — a category tag per image).

---

## 8. Google Reviews

The pre-existing `ReviewsProvider` abstraction (`src/services/reviews/reviews.service.ts`, from Phase 4) was explicitly built for this moment — "a real Google Places/Business Profile integration can implement this same interface later without any caller changing" — and that's exactly what happened: a new `DbReviewsProvider` reads the `Review` table instead of demo data, and `getBusinessReviews()`'s call sites (Home) didn't change at all.

- **Schema**: `Business.googlePlaceId`/`googleRating`/`googleRatingCount` (the aggregate, tracked separately from individual reviews — see below), a new `Review` model (unique on `businessId`+`externalId` for idempotent upsert), and `BusinessSettings.reviewsMinRating`/`reviewsExcludeRatingOnly` (the owner-facing visibility policy).
- **Provider**: `google-places.provider.ts` mirrors the existing `CalendarProvider` pattern deliberately — plain `fetch` against a documented REST contract (the legacy Place Details endpoint), no SDK, an injectable `MockReviewsProvider` for tests.
- **Sync**: a 24-hour scheduled job (`POST /api/cron/sync-google-reviews`, `CRON_SECRET`-gated exactly like the existing notification cron) is the **only** place that ever calls Google — `DbReviewsProvider` only ever reads what that job already wrote, satisfying "the customer application should always display reviews from the database" and "do not call the Places API on every page load" directly, not just in spirit. `DbReviewsProvider` falls back to demo data (clearly labelled `isDemoData: true`) only when a business has never had any reviews synced at all, so a fresh install's Reviews tab isn't empty.
- **Owner management**: `/owner/settings/reviews` — Google Place ID + visibility policy (minimum rating, exclude rating-only reviews) reusing the existing `updateBusinessProfile`/`updateBusinessSettings` functions rather than a parallel update path, plus a hide/unhide review list with client-side rating filter and text search, and a manual "Sync Now" button for immediate feedback after first configuring a Place ID.
- **Known, Google-side limitation** (not fixable from this codebase): Place Details only ever returns up to 5 "most relevant" individual reviews per call, regardless of how many the place actually has. The place-level aggregate rating/count is accurate and tracked separately; the individual review list is always a small sample. Using this feature for real also requires a billed Google Cloud project with the Places API enabled — real cost exposure worth being aware of before turning it on for a live business.

---

## Schema changes (all in one migration, `20260804134858_phase9_media_gallery_reviews_super_admin`)

- `Business`: `welcomeBackgroundDesktopUrl`, `welcomeBackgroundMobileUrl`, `googlePlaceId`, `googleRating`, `googleRatingCount`.
- `BusinessSettings`: `reviewsMinRating`, `reviewsExcludeRatingOnly`.
- `Service`: `imageUrl`.
- New models: `MediaAsset`, `BusinessGalleryImage` (+ `GalleryPlacement` enum), `Review`.
- New `Permission` values: `MANAGE_MEDIA_LIBRARY`, `MANAGE_REVIEWS` (both granted to Owner by default).
- Same MySQL-collation fix required as Phase 8 (new tables default to `utf8mb4_unicode_ci`; hand-corrected to match the database's actual `utf8mb4_0900_ai_ci` before applying).

## New domain services

- `src/services/media/media.service.ts` + `src/lib/media/media-storage.ts`
- `src/services/gallery/gallery.service.ts`
- `src/services/reviews/google-places.provider.ts`, `review-sync.service.ts`, `review-management.service.ts`, `mock-reviews-provider.ts` (`reviews.service.ts` itself was extended, not replaced)
- `src/lib/business/get-acting-business-context.ts`
- `scripts/ensure-super-admin.ts`

## New reusable components

- `MediaManagerModal` / `MediaPicker` (`src/features/media/components/`)
- `ColorPicker`, `IconPicker`, `ImageGallery` (`src/components/ui/`)
- `SettingsPageShell` (`src/components/settings/`) — extracted once six owner settings pages shared the identical `TopNav` + centered-container wrapper verbatim
- `HomeTabs` and its four tab sub-components (`src/features/home/components/home-tabs.tsx`)
- `GalleryManager`, `ReviewsManager` (`src/features/owner/components/`)

## New scheduled jobs

- `POST /api/cron/sync-google-reviews` — every 24h, `CRON_SECRET`-gated, same shape as the existing notification cron.

## Architectural improvements made

- Structural (not filter-based) exclusion of the Super Administrator from every staff-scoped query, by giving it no `StaffProfile` at all.
- One Media Manager, one Gallery model/service (Hero + Portfolio), one `ColorPicker`, one `IconPicker` — none duplicated per feature.
- Two real, pre-existing gaps fixed as direct consequences of this work, not separately: `logoUrl` (and siblings) could never actually be cleared once set; `LoyaltyCard` silently ignored its own configured colour/image/icon.
- `SettingsPageShell` extracted from six now-identical page wrappers.
- Media upload permission split into "add/browse" (any staff) vs. "delete" (Owner/Super Admin only) rather than one coarse gate.

## Intentionally postponed

- S3-compatible object storage for the Media Manager (local disk + Docker volume for v1; swappable later behind the same storage-helper interface).
- Full PWA manifest icon regeneration from one uploaded source image — no image-resize pipeline exists (deliberately avoided pulling `sharp`/libvips into the Docker build); the favicon/apple-touch-icon `<head>` tags do update from the uploaded image, the manifest's fixed icon set doesn't.
- Drag-and-drop reordering for gallery/portfolio images (up/down buttons instead — a full DnD library was judged not worth it for this).
- Price/duration range filters on the Home Services tab beyond category + text search.
- Super Administrator performing genuine staff-ledger actions (loyalty stamp authorship, appointment reassignment) — it has no `StaffProfile` to attribute those to, by design.
- A true single-service deep link from the Home Services tab's "Book" button into the booking flow (currently opens `/book` fresh, same as before this phase) — not asked for at that granularity.

## Future recommendations

- Swap local-disk media storage for S3-compatible object storage behind `media-storage.ts`'s existing interface once running more than one app container.
- A real image-resize pipeline (`sharp`/Squoosh) for full multi-size PWA icon generation from one uploaded source image.
- If Google's 5-review-per-call cap becomes limiting, investigate the newer Places API (v1) or a paid third-party reviews aggregator as an alternative data source behind the same `ReviewsFetchProvider` interface.
- Drag-and-drop gallery/portfolio reordering.
- Extend the Super Administrator with a dedicated `/admin` platform-level area if multi-business support is ever added — the schema (`businessId` on every model) already anticipates it.