Admin Features — Frontpics Image Marketplace

The admin portal lives under /{locale}/admin in the Next.js app. It is protected by route checks in apps/web/src/proxy.ts and by API role guards. Admin UI uses the shared panel navigation components in apps/web/src/components/admin.

Navigation and Badge Counts

The admin sidebar and mobile panel navigation call:

GET /api/v1/admin/action-counts

Returned counts:

• pendingImages for /admin/moderation
• unreadEmails for /admin/emails
• unreadFeedback for /admin/feedback
• pendingPayouts for /admin/payouts

Badges refresh every 30 seconds on the client.

Current Admin Routes

/{locale}/admin
  moderation/          image review queue
  images/              all image management
  images/titles/       title tooling
  upload/              admin upload
  shooting-requests/   buyer photoshoot requests
  users/               users and role/account controls
  brands/              AgencyBrand management
  credit-packs/        configurable credit packs
  billing/             billing and invoice views
  payouts/             photographer payout requests
  feedback/            feedback inbox
  emails/              incoming email inbox
  audit/               audit logs
  page-customization/  configurable page copy/media
  tags/                tag management
  system/              system dashboards

System subroutes include image processing, diagnostics, storage management, storage diagnostics, logs, and failed events.

Dashboard

GET /api/v1/admin/stats returns grouped user counts, image counts by status, order totals, pending payout count, and storage totals by bucket/variant.

The dashboard is a high-level operational view; action-specific queues live in their own pages.

Image Moderation

Moderation uses images with status = pending_review.

Admins can:

• review watermarked previews and metadata;
• approve images and set/confirm credit price;
• reject with a moderation reason;
• inspect photographer and location metadata;
• rely on queue badge counts from action-counts.

Important model fields:

• Image.status
• Image.basePriceCredits
• Image.imageTags
• Image.moderationNote
• Image.rejectionReason

Image Management

The all-images admin page can list images across statuses and filter by status, text, city, photographer, tags, exact title, and sort mode. Admin deletion must respect purchase history and storage cleanup.

Storage object cleanup goes through StorageService; do not delete only database rows.

Users and Credits

Admins can:

• list users by role/status;
• suspend or activate accounts;
• change roles;
• reset passwords;
• remove accounts where allowed;
• manually adjust credits with an audit trail.

Use User.firstName and User.lastName; there is no displayName.

Agency Brands

Agency branding is centralized through AgencyBrand and related office/domain matching.

Admins manage:

• agency display name;
• logo URL;
• watermark position;
• map pin URL;
• email domain and office matching.

Buyer downloads resolve branding centrally. Do not add per-agent watermark upload paths.

Payout Management

Payouts are manual bank-transfer requests from photographers.

Photographer request flow:

1. Photographer enters amount and optional note/reference.
2. API validates minimum amount and bank details.
3. API creates Payout(status = pending).
4. API deducts/reserves credits from the photographer wallet.
5. API stores the photographer note/reference in the linked CreditTransaction description.

Admin payout list:

• defaults to pending payouts;
• shows photographer identity and bank details;
• shows requestReference as the photographer-provided reference;
• records the admin payment/transaction reference in paymentRef when marked paid.

Admin actions:

Action	Endpoint	Effect
Mark paid	PATCH /admin/payouts/:id/process	Sets status to completed, sets processedAt, stores admin paymentRef.
Reject	PATCH /admin/payouts/:id/reject	Sets status to failed and refunds credits to the photographer wallet.

Pending payouts also appear as a numeric badge in the admin navigation.

Shooting Requests

Buyer photoshoot requests are visible in admin and to photographers as open jobs.

Important behavior:

• Photoshoot requests are free for buyers for now.
• Creating a request does not reserve or deduct buyer credits.
• Location coordinates are saved from the buyer-supplied lookup or API geocoding fallback.
• Photographer available jobs use those coordinates for map markers.
• Completing a request credits the photographer wallet; it does not create a payout by default.

Feedback and Incoming Emails

Feedback and incoming email pages are operational queues. Their unread/open counts are shown in the admin navigation through action-counts.

Feedback statuses are handled in the feedback module. Incoming email statuses are handled in the incoming email module.

Storage and System Settings

Admins can switch the active storage backend at runtime:

• r2
• s3
• local

The active backend is stored in Redis as config:storage_backend. Existing files stay in their original backend and storage profile. Do not assume a backend switch migrates existing objects.

System diagnostics pages inspect storage, image processing, Redis, failed events, and logs.

Audit Logging

Sensitive admin actions should call AuditService.

Examples:

• image approval/rejection;
• user role/status changes;
• payout processing/rejection;
• credit adjustments;
• destructive storage/image operations.