PlateAI

Imported from armanmikoyan/PlateAI (AGENTS.md). Install upstream with npx skills add armanmikoyan/PlateAI. Copyright stays with the author.

PlateAI — Monorepo (AGENTS.md)

Mindset

1. Think before acting. Reason through the change before writing code.
2. Research, then implement. Check installed Next.js docs and existing patterns here before inventing a new one. Training data loses when it conflicts with package.json versions or node_modules/next/dist/docs/.
3. Fix the root cause. Do not stack workarounds on a broken foundation.
4. No breadcrumbs. If you delete or move code, remove it cleanly. Do not leave // moved to X comments.
5. Leave the repo better. Delete unused props, helpers, and imports. Prefer the simplest code that matches this file.
6. Do not pivot unless the user asks or evidence requires it.

Skills

• Next.js APIs (routing, RSC, metadata, images, fonts, errors): .agents/skills/next-best-practices/SKILL.md
• React / Next performance (bundles, re-renders, hydration): .agents/skills/vercel-react-best-practices/SKILL.md
• shadcn / Base UI (add, compose, or style components): .agents/skills/shadcn/SKILL.md
• UI / a11y / UX review: .agents/skills/web-design-guidelines/SKILL.md
• Looking for another skill: .agents/skills/find-skills/SKILL.md

Monorepo layout

npm workspaces at the root. All commands run from the root (apps/* and packages/* globs):

plateai/
├── apps/
│   ├── plateUI/        # Next.js app (@plate/plate-ui)
│   └── plateServer/    # Express + OAuth + MongoDB (@plate/plate-server)
├── packages/           # shared TS packages (types, utils, domain libs)
├── tsconfig.base.json  # shared TS options (apps extend via "extends")
├── vitest.config.mts   # vitest workspaces: plateUI + plateServer projects
├── .oxfmtrc.json       # oxfmt formatter config

Package manager: npm (do not hand-edit package-lock.json). packageManager + engines are pinned in the root package.json.

Shared config at root: tsconfig.base.json (common TS options; each app extends it and overrides), vitest.config.mts (per-app projects with name + @ alias), .oxfmtrc.json, .oxlintrc.json. tsconfig.json stays per-app (Next needs DOM/JSX/bundler resolution + next plugin; the server needs NodeNext + ESM emit).

Root scripts (from package.json):

Env files live per-app: apps/plateUI/.env.local (from apps/plateUI/.env.example), apps/plateServer/.env (from apps/plateServer/.env.example).

TypeScript

Do not inline structural types in props or signatures (no { children: ReactNode } or Readonly<{ … }> on the function). Declare a named type (or interface) and use that name.

Put types immediately after imports when they only reference imported types. If a type needs typeof some value in the same file (for example VariantProps<typeof buttonVariants>), declare that type right above the component/function that uses it, after the value exists.

No types or static constants in component files. Feature *.tsx subcomponents (e.g. pricing-comparison-table.tsx) must not declare type/interface or exportable const maps, arrays, or copy — put types in types.ts and static data in constants.ts. Component files import those siblings; they contain JSX and component logic only. app/ui/ follows the same split when a control needs feature-level copy or props types colocated nearby.

Naming

• Folders: use kebab-case (meal-plan, shopping-list). Single-word segments are lowercase (test, auth). Apply under app/components/, the server's src/routes/, and future packages/* entries.
• Constants (copy and other static values in constants.ts, plus root siteMetadata in layout.tsx): use UPPERCASE — export const FEATURE = { TITLE: '…', BODY: '…' } as const with SCREAMING_SNAKE_CASE keys, or top-level export const PAGE_TITLE = '…' as const. Do not use camelCase keys for exported copy objects.

oxlint enforces kebab-case folders under app/components/ (check-file/folder-naming-convention) via the root .oxlintrc.json. Per-app lint scripts run oxlint -c ../../.oxlintrc.json.

plateUI (Next.js app)

Entry apps/plateUI/app/layout.tsx; routes under apps/plateUI/app/<route>/page.tsx render feature components (return <Feature />).

Feature folders (apps/plateUI/app/components/<kebab-case-name>/)

Standard files (use only what the feature needs):

Do not add barrel files (index.ts that re-exports siblings, or re-export subcomponents through index.tsx). app/ui/ has no barrel either — import the concrete file (e.g. @/app/ui/button).

app/ui/ is for design-system controls built on Base UI / shadcn-style patterns (e.g. button.tsx). App chrome, marketing sections, and reusable composition components (e.g. scroll/, icon-text-card/) live under app/components/<kebab-name>/, not in app/ui/.

Non-component app logic lives under app/:

• app/api/<route>/ — Next route handlers (auth, meal-analyses, snap, health).
• app/utils/<kebab-name>/ — shared pure/domain helpers (e.g. device-detection/, meal-analyses/), not feature UI.
• app/utils/cn.ts — cn() class-merge helper; customers for CVA variants and composition.

plateServer (Express app)

Entry apps/plateServer/src/index.ts. Source layout:

Route features follow the same file pattern as app features — index.ts (router only), constants.ts (copy/static, UPPERCASE), types.ts (route/config/response types), utils.ts (pure helpers, co-located unit tests utils.test.ts), plus feature controller.ts / service.ts / repository.ts when it needs them (e.g. auth/):

• index.ts is the router only — import siblings via @/ (e.g. @/routes/auth/google-oauth.js), no re-exports, no ../ across folders.
• controller.ts / service.ts / repository.ts each hold only their own layer. Controllers contain route-handler wiring only — validate/forward, delegate to service.ts, respond. No helpers (crypto, parsing, mapping) — those go in utils.ts. Services hold business logic that calls repository.ts; repositories hold Mongoose/data access only. No cross-layer logic (e.g. no DB queries in controllers, no HTTP in repositories).
• Types live only in types.ts — never type/interface in constants.ts (consts stay UPPERCASE copy/static only). Pure helpers live in utils.ts with co-located utils.test.ts.
• Body parsing is app-level, not router-level. createApp mounts express.json() once for all routes and express.raw({ type: 'application/json' }) scoped to /webhook (before the JSON parser) so webhook signatures can read the raw body. Routers must not add express.json() / express.raw().
• ESM imports use .js extensions.

Dev: npm run dev:server (tsx watch).

AUTH.ACCESS_COOKIE_NAME (plateai.access) and AUTH.REFRESH_COOKIE_NAME (plateai.refresh) live in apps/plateServer/src/routes/auth/constants.ts and must match apps/plateUI/app/api/auth/constants.ts.

packages/ (shared code)

Shared, non-app-specific TS packages that both apps can consume. Keep them framework-agnostic (no Next or Express imports). Each gets package.json + tsconfig.json extending ../../tsconfig.base.json. Add to the root workspaces glob via the packages/* pattern (already configured) — no other wiring needed. Do not create packages/index.ts barrels.

Packages are self-contained and the single source of truth for their domain. Any concept a package owns (domain types, constants, status/plan enums, pure helpers) must be defined in the package and imported by both apps directly from the package subpath. Do not copy, re-declare, or alias a package-owned constant/type in an app (no export { X } from '...', no export type MealsX = PackageX, no duplicate const MEAL_ANALYSIS_STATUS = { ... } in app files). Apps import and use exactly what the package exports; if an app needs a derived value, compute it in the app from the package's public API rather than restating the definition. Never re-export — consumers import directly from the concrete subpath (@plate/plate-ai/constants, @plate/plate-ai/types, ...).

plate-ai (@plate/plate-ai)

The single source of truth for AI meal analysis: prompt, model/config (provider + model selection), analysis parsing, provider abstraction, and the domain types/constants that describe a meal analysis. Both apps depend on it ("@plate/plate-ai": "*"). It is provider-agnostic: it exposes a generic analyzeMealImage function plus ImageAnalysisProvider interface created via createImageAnalysisProvider, and implements it for many model providers (Gemini, OpenAI) internally.

• Public surface only, subpath entries — no barrel / no re-exports. @plate/plate-ai/constants (MEAL_ANALYSIS_STATUS, MEAL_ANALYSIS_CONFIDENCE, IMAGE_ANALYSIS_PROVIDER, DEFAULT_IMAGE_ANALYSIS_MODEL, prompt copy, test fixture, timing), @plate/plate-ai/types (generic AI types incl. MealAnalysisStatus, MealAnalysisConfidence, MealAnalysisResult, the shared API contract types MealAnalysisSummary / MealAnalysisItemResponse / MealAnalysisListResponse, provider ids/configs), @plate/plate-ai/errors (AiConfigError, AiParseError, AiProviderError), @plate/plate-ai/utils (pure helpers/parser), @plate/plate-ai/provider (analyzeMealImage, createImageAnalysisProvider). Consumers import from the concrete subpath; there is no . root entry.
• Providers are internal under src/providers/ (gemini.ts, openai.ts). No provider SDK types leak to the package consumers.
• @/ aliases + tsc-alias: uses @/* → ./src/* (NodeNext) like apps/plateServer, build runs tsc && tsc-alias. Never import across package folders with ../.
• Owns its SDK dependencies. @google/generative-ai and openai are declared in this package's package.json, not in apps/plateServer.
• The server keeps all HTTP (controller.ts) and DB (repository.ts) concerns; the package does the AI/prompt/parsing logic. meal-analyses/service.ts calls analyzeMealImage from @plate/plate-ai/provider and maps generic results/errors to HTTP. Server model + repository import MEAL_ANALYSIS_STATUS/MEAL_ANALYSIS_CONFIDENCE directly from @plate/plate-ai/constants.

plate-billing (@plate/plate-billing)

The single source of truth for plans, prices, and payments; both apps depend on it ("@plate/plate-billing": "*"). It is provider-agnostic: it exposes a generic BillingProvider interface (createCheckout, verifyWebhookSignature, parseWebhook) plus plan/status contracts, and implements that interface for Lemon Squeezy internally. Swap the provider and the server/UI stay unchanged.

• Public surface only, no barrel / no re-exports. The package exposes subpath entries instead of one index.ts barrel: @plate/plate-billing/constants (SUBSCRIPTION_PLAN, SUBSCRIPTION_STATUS), @plate/plate-billing/types (generic types incl. SubscriptionPlan/SubscriptionStatus, CreateCheckoutInput, CheckoutResult, WebhookResult, WebhookParseResult, CheckoutSessionResponse), @plate/plate-billing/utils (isPaidPlan, isActivePaidPlan), @plate/plate-billing/provider (createBillingProvider, BillingProviderConfig). Consumers import from the concrete subpath; there is no . root entry.
• Lemon Squeezy is internal under src/lemonsqueezy/ (constants.ts, types.ts, utils.ts, provider.ts). No LemonSqueezy* types leak to the package consumers.
• @/ aliases + tsc-alias: the package uses @/* → ./src/* (NodeNext) exactly like apps/plateServer, and its build runs tsc && tsc-alias to rewrite @/ into relative .js in dist. Never import across package folders with ../.
• Owns its SDK dependency. @lemonsqueezy/lemonsqueezy.js is declared in the package's package.json, not in apps/plateServer.
• The server keeps all HTTP (checkout/controller.ts) and DB (checkout/repository.ts) concerns; the package does the payment logic. checkout/utils.ts maps ServerConfig → BillingProviderConfig and generic WebhookResult → the persistence update. User billing columns are provider-agnostic (billingCustomerId, billingOrderId, billingSubscriptionId) — never Lemon-named.

Copy / UI strings

Do not hardcode user-visible text inside feature components. Import from app/components/<feature>/constants.ts using the UPPERCASE export(s) defined there. Root layout metadata copy is colocated in apps/plateUI/app/layout.tsx next to export const metadata (e.g. SITE_METADATA with SCREAMING_SNAKE_CASE keys — same convention as feature constants.ts).

Documentation

Skills provide specialized instructions and workflows for specific tasks. Use the skill tool to load a skill when a task matches its description.