Imported from AndyZHENG0715/verona-gelato (AGENTS.md). Install upstream with npx skills add AndyZHENG0715/verona-gelato. Copyright stays with the author.

Verona Gelato - Agent Guide

OVERVIEW

• Bilingual Next.js 15 site for Verona Gelato, Hong Kong gelato business.
• Surfaces: storefront, events, inquiries, admin CMS.
• Stage 1 complete; Stage 2 waits on client feedback.
• Stack: Next.js 15, TypeScript, Tailwind CSS, Prisma, NextAuth, Nodemailer.
• Client-first now: ~30 use client files.
• Stage 2 target: Server Components migration + loading/error/revalidate work.
• Planning/workflow lives in .planning/.

STRUCTURE

.
├── .planning/ (15)
│   ├── PROJECT.md
│   ├── REQUIREMENTS.md
│   ├── ROADMAP.md
│   ├── STATE.md
│   ├── config.json
│   └── codebase/ (7)
├── docs/ (12)
├── prisma/ (5)
│   └── migrations/ (2)
├── public/ (56)
│   └── images/ (56)
│       ├── about/ (2)
│       ├── cups/ (15)
│       ├── events/ (9)
│       ├── flavors/ (21)
│       └── home/ (7)
└── src/ (110)
    ├── app/ (93)
    │   ├── (components)/ (13)
    │   ├── admin/ (33)
    │   ├── api/ (19)
    │   ├── about/ (3)
    │   ├── contact/ (3)
    │   ├── events/ (9)
    │   ├── flavors/ (3)
    │   └── shop/ (3)
    ├── components/ (6)
    │   └── admin/ (4)
    ├── data/ (1)
    ├── i18n/ (3)
    ├── lib/ (5)
    └── types/ (1)

• (components) is a route group, not a URL segment.
• src/components/ is shared/admin; route-scoped UI stays near the route.

WHERE TO LOOK

CODE MAP

• src/app/layout.tsx — RootLayout, metadata
• src/components/ConditionalLayout.tsx — ConditionalLayout
• src/components/SessionProvider.tsx — default AuthSessionProvider
• src/i18n/I18nProvider.tsx — I18nProvider, useI18n
• src/lib/db.ts — prisma
• src/lib/auth.ts — authOptions
• src/lib/email.ts — sendContactEmail, sendEventInquiryEmail, sendWholesaleInquiryEmail
• src/app/(components)/ui/index.tsx — Button, Card, Section, Heading, Container
• src/app/(components)/Navbar.tsx — Navbar
• src/app/(components)/Footer.tsx — Footer
• src/app/(components)/Hero.tsx — Hero
• src/app/(components)/Events.tsx — Events
• src/app/(components)/Highlights.tsx — Highlights
• src/app/(components)/MadeInHK.tsx — MadeInHK
• src/app/(components)/FadeIn.tsx — FadeIn
• src/app/(components)/LangSwitch.tsx — LangSwitch
• src/app/(components)/PlaceholderImage.tsx — PlaceholderImage
• src/app/(components)/EventInquiryForm.tsx — default EventInquiryForm
• src/app/(components)/WholesaleInquiryForm.tsx — default WholesaleInquiryForm
• src/components/admin/EventForm.tsx — default EventForm
• src/components/admin/FlavorForm.tsx — default FlavorForm
• src/components/admin/ImageUpload.tsx — default ImageUpload
• src/middleware.ts — default auth middleware, config.matcher
• src/data/home.ts — deprecated static data

CONVENTIONS

• Keep shell components in src/app/(components); no URL path from the group.
• Reuse src/app/(components)/ui/index.tsx before inventing new button/card variants.
• src/components/ = shared/admin helpers; route-specific UI stays close to the route.
• Use "use client" only for state/effects/handlers/browser APIs.
• Current architecture is client-first; Stage 2 pushes static pieces toward Server Components.
• Preserve EN/ZH-Hant copy on user-facing + admin surfaces.
• useI18n() + locale JSONs are the copy source of truth.
• Homepage marketing sections prefer /api/homepage/*; src/data/home.ts is archival.
• Admin forms serialize arrays to JSON strings before submit (highlights, allergens, multi-image picks).
• ImageUpload path contract: /public/images/<folder>/ + /api/admin/upload + /api/admin/images.
• ConditionalLayout controls navbar/footer suppression on /admin*.
• authOptions + middleware gate admin via credentials; session user.id is injected in callbacks.
• Keep PlaceholderImage for asset-heavy views; fallback/blur behavior is intentional.

ANTI-PATTERNS

• Modify database schema without discussion.
• Change auth flow without security review.
• Remove i18n support from any user-facing page.
• Deploy without build verification.
• Commit .env.local or secrets.

COMMANDS

npm run dev      # Start dev server (Turbopack)
npm run build    # Production build
npm run lint     # ESLint
npx prisma studio # Database GUI

NOTES

• No test infrastructure yet; build + lint are the current gates.
• src/app/(components) is a route group, not a route.
• src/data/home.ts is reference only; active homepage content comes from DB/API.
• ConditionalLayout is path-based; /admin/login bypasses shell, other /admin/* routes do not.
• ImageUpload can browse or upload; multi-select returns JSON-stringified paths.
• PlaceholderImage swaps to fallback art on error; broken assets may be masked.
• Events fetch failures are silent; Highlights logs and keeps fallback.
• GSD source of truth lives in .planning/; keep roadmap/state changes there.
• Stage 2 work should bias toward Server Components, route loading/error files, and revalidate.