searcher/.codex/skills/wallora-searcher/SKILL.md

name, description

name

description

wallora-searcher

Project-specific guide for working on the Wallora searcher Next.js app. Use when Codex is asked to modify, debug, design, review, build, lint, or explain this project, especially public APIs with JWT auth, admin session auth, protected admin pages, SEO public pages, shadcn UI, Supabase data with wg_ table prefixes, gallery photo sync jobs, Aliyun OSS images, NextAuth authentication, Swagger/OpenAPI docs, files under app/, public/, Next.js configuration, Tailwind CSS styling, package scripts, or project setup.

Wallora Searcher

Purpose

Use this skill to work consistently inside the Wallora searcher project. Treat the local codebase as the source of truth and keep changes aligned with the current Next.js App Router, React, TypeScript, and Tailwind CSS setup.

First Steps

1. Confirm the working directory is the project root: /Users/luoyangwei/Documents/workspace/wallora.top/searcher.
2. Read references/project.md when the task involves commands, current baseline state, or project conventions.
3. Read references/architecture.md when the task involves API design, authentication, authorization, admin features, public website pages, data storage, image upload/storage, or API documentation.
4. Read references/supabase-gallery-sync.md when the task involves gallery photos, Unsplash sync, cron jobs, Supabase migrations, or wg_gallery_* tables.
5. Inspect the relevant files before editing. Prefer rg and targeted sed -n reads.

Project Workflow

• Use pnpm commands because the project has pnpm-lock.yaml and pnpm-workspace.yaml.
• Use the App Router under app/; avoid creating a pages/ tree unless the project intentionally changes architecture.
• Keep UI work in React Server Components by default. Add "use client" only when interactivity, state, effects, or browser APIs require it.
• Use shadcn/ui as the base UI system once it is initialized. Check components.json and installed UI components before importing or adding components.
• Prefer Tailwind utility classes and the existing app/globals.css theme variables before adding custom CSS.
• Keep metadata in app/layout.tsx current when building user-facing pages.
• Do not assume a Git repository is present in this directory; verify before using Git-based workflows.
• Do not add Vercel-specific deployment config unless the user explicitly changes the deployment target. This project is not planned for Vercel.

Product Architecture

• Separate three surfaces clearly: public API clients, authenticated admin users, and public SEO website visitors.
• Treat API JWT authorization and admin session authorization as different trust boundaries. Do not reuse admin session checks as public API authorization.
• Store application data in Supabase and design RLS/policies deliberately for every exposed table.
• Prefix application-owned Supabase table names with wg_.
• Store image files in Aliyun OSS; keep metadata, ownership, and public/private visibility decisions in Supabase.
• Treat raw gallery rows as admin curation data. Public gallery APIs should expose picked rows only.
• Picked photos use wg_gallery_photos.is_picked plus picked_* and oss_* metadata; admin pick/unpick should mirror selected images to Aliyun OSS when OSS_* env vars are configured.
• App photo APIs live under /api/v1/gallery/photos; list/detail endpoints expose picked photos only and include isFavorited when a Bearer app-user JWT is provided.
• Collections are built from picked photos with wg_photo_collections and wg_photo_collection_items; admin CRUD lives at /admin/collections and public APIs live under /api/v1/gallery/collections.
• App user features use wg_app_users, wg_user_favorites, and wg_user_settings; public app user auth is email/password plus Bearer JWT, kept separate from admin NextAuth sessions. Admins can view and enable/disable app users under /admin/users.
• Use NextAuth for authentication flows where appropriate, especially account/password admin login and session persistence.
• Generate and update swagger.yaml when API routes or request/response contracts change.
• Protect every page under app/(admin) except /admin/login. Use route middleware/proxy and server-side layout checks for protected admin route groups.

Frontend Expectations

• Build the actual usable experience as the first screen; avoid placeholder landing copy unless explicitly requested.
• Keep layouts responsive from mobile through desktop using stable dimensions, clear spacing, and readable type.
• Use visual assets for website/app experiences when they materially improve the feature. Prefer existing public assets only when they are relevant.
• Avoid adding decorative gradients, oversized marketing sections, or generic template aesthetics unless the user asks for that direction.
• When adding interactive UI, include loading, empty, error, and disabled states where the workflow naturally needs them.

Verification

Run the smallest useful checks after edits:

pnpm format:check
pnpm lint
pnpm build

For visual or interaction changes, start the dev server with pnpm dev and verify in the browser at http://localhost:3000. Use screenshots or browser inspection when layout quality matters.

If a command fails because dependencies are missing, install with pnpm install only after confirming that is appropriate for the workspace.

References

• references/project.md: project snapshot, file map, scripts, conventions, and current baseline notes.
• references/architecture.md: role model, auth boundaries, storage choices, API documentation expectations, and implementation guardrails.
• references/supabase-gallery-sync.md: wg_ table naming, gallery sync schema, Unsplash cron workflow, and non-Vercel scheduler expectations.