moalem-shop/AGENTS.md

moalem.shop — context for AI agents and tooling

Storefront for فروشگاه موبایل معلم built on the Meshkee CMS contract. Keep this file current: every prompt that changes structure, data sources or fallbacks should update it.

Stack

• Next.js 16.3 (App Router, Turbopack) · React 19 · TypeScript
• Tailwind CSS v4 (@theme inline tokens in src/app/globals.css)
• Swiper 14 for every slider/carousel
• fa / RTL, flat design, no gradients

Data — Meshkee Website API

• Base: https://api.meshkee.com/api/v1, docs: https://api.meshkee.com/docs/website
• Tenant: moalem.shop (business id 27, specialProductsSource: store_item)
• Every public read goes through src/lib/api.ts; wrap calls in safe() so an empty or failing module degrades one section instead of the page.
• Never invent CMS/admin endpoints. If OpenAPI and any prose conflict, OpenAPI wins.

What the tenant actually returns today (2026-09-06)

Endpoint	State
enabledModules (GET /tenants/moalem.shop)	["products", "blog", "finance"] — workshops is not enabled. Do not build a workshops page/nav entry until it is.
/products	479 items, real titles, images, categories
/categories?entityType=product	48 items, 3 levels under «کالای دیجیتال». Products are filed on leaf categories only — a parent category page/carousel must query its whole subtree (subtreeIds/subtreeIdsAll in src/lib/categoryTree.ts).
/store-items, /store-specials	empty → no prices, no discounts, everything inStock:false. /store-items/by-product/{id} returns a single { storeItem } (or null) — for a product's full variant list use /store-items?productId=&pageSize=100 ({ items }) instead, see getStoreItemsByProduct in src/lib/api.ts.
/website/sliders, /website/category-groups	empty
/website/static-images	filled — slider (2), categories (8 of 15), one/two/three-banner-bg all have real images. Verified live and rendering correctly; if a future check finds otherwise, suspect a stale build/deploy before suspecting the wiring.
/blogs	empty (module enabled)
/website/business-info	phones/addresses/socialMedia still empty; logoUrl/faviconUrl are now set but point to a different business's mark (see "Brand")
/products/by-id/{id}/technical-info	{ form: null, values: [] } — empty on every product checked so far
/comments	empty, but POST works (no bearer required by the API itself)

Fallbacks in place until the CMS is filled

Gap	Fallback	Remove when
No prices	src/lib/demoPricing.ts, gated by NEXT_PUBLIC_DEMO_PRICING=1 — deterministic price per product id	store-items exist
No blog posts	src/data/fallbackBlogs.ts — the real posts from moalem.shop/articles, shown on the homepage and /blog as non-clickable cards (no real detail page exists for them)	/blogs returns items
No category art past slot position 8	placeholder SVGs in public/images/categories/{id}.svg, generated by scripts/gen-category-placeholders.mjs for every category at every level, not just level-2	the categories slot has an image for that position
Wrong logo/favicon in API	getFavicon() is wired live (see "Brand") but the uploaded asset itself is wrong; no code fallback needed once the dashboard upload is fixed	the correct asset is uploaded

Brand

Colors taken from the live moalem.shop theme, not invented: primary #E51E22, dark #B10123, ink #2E2E2E, body #7C7C7C. Fonts: IRANYekan (fa, local public/fonts) + Montserrat (latin, next/font).

• Logo/favicon: getFavicon() in src/lib/api.ts reads GET /tenants/moalem.shop/website/favicon — the documented single source — and Header.tsx/Footer.tsx/generateMetadata() in layout.tsx all use it, falling back to the bundled /images/logo.png / /favicon.png only when the API field is null. As of 2026-09-06 the dashboard has a logo/ favicon uploaded, but it's the wrong business's (a home-appliances store's mark, not موبایل معلم) — the wiring is correct and will pick up the right asset automatically the moment it's replaced in the dashboard; don't "fix" this by hardcoding the local fallback again.
• Contact data (phone, mobile, branch addresses, Instagram/Telegram) in src/data/site.ts is real, pulled from the live theme's footer — GET /website/business-info still returns empty phoneNumbers/addresses/ socialMedia for this tenant, so these stay hand-maintained here until that's filled in. Update both together when it is.

Layout conventions

• Content width --container-boxed: 1200px, applied with the boxed utility.
• Homepage order: promo strip → header → hero slider → category carousel → hot deals → product carousels (interleaved with promo banners) → magazine carousel → footer. Exact interleaving is in "Static-image slots" below.
• Section header (title + one-line desc on the right, «مشاهده همه» pill on the left) is src/components/ui/SectionHeader.tsx — reuse it for every carousel.
• Product card: ui/ProductCard.tsx, 8px radius, discount badge top-right, strikethrough old price above the current one. The price block is a fixed 44px row and the old-price line is always rendered (empty when there is no discount) so every card in a carousel is exactly the same height — keep that invariant when adding badges or meta lines.
• Carousel arrows: ui/CarouselNav.tsx, passed to SectionHeader as nav so they sit beside the «مشاهده همه» pill on desktop; the copy under the track is lg:hidden for thumbs.
• Prices are Toman and rendered with Persian digits (src/lib/format.ts).

Navigation

• Desktop (lg+): full header — logo, search, account/cart, then the product mega menu and the main nav.
• Mobile: no hamburger. The header carries the search box alone; everything else lives in MobileBottomNav.tsx, a fixed bottom bar with خانه / سبد خرید / دسته‌بندی‌ها / ورود (or the account menu once signed in). «دسته‌بندی‌ها» opens a bottom sheet with the level-2 categories and an accordion for their children. Any new mobile entry point belongs in that bar, not in a drawer.

Auth / account menu

Login itself happens off-site, on the customer portal (customer.{domain}) — this storefront never renders a login form. For the header/bottom-nav account menu to show "نام عزیز" instead of "ورود | ثبت‌نام", the customer portal needs to set a non-HttpOnly cookie on the shared parent domain (.{domain}) named AUTH_TOKEN_COOKIE (src/lib/config.ts, currently "meshkee_token") holding the bearer access token. Until that exists, getSession() in src/lib/auth.ts always resolves to null and the anonymous view is all anyone will see — this is expected, not a bug, and nothing else breaks.

• src/lib/auth.ts — server-only (next/headers): getSession() reads the cookie and calls GET /auth/me.
• src/lib/authUser.ts — pure helpers (displayName, isAdmin), safe to import from client components. Never import auth.ts from a client component — it pulls in next/headers and breaks the build; that's the entire reason this file is split out.
• Admin detection (isAdmin()) reads user.isAdmin/user.role defensively — the OpenAPI schema doesn't document a role field on the user object, so this is a best guess. Update it once the real shape is confirmed.
• Cart ("افزودن به سبد خرید" in ProductBuyPanel.tsx) needs a real storeItemVariantId, which only exists once a product has store-items — today that's none of them, so the button always shows "این محصول هنوز برای خرید آنلاین فعال نشده است" regardless of login state. That's correct given the data, not a bug either.

Static-image slots

Slot catalog: src/app/meshkee/static-image-slots/route.ts. Keys and where each is consumed:

Key	Kind	Consumed by
slider	list	HeroSlider.tsx — wins over FALLBACK_SLIDES when it has images
categories	list	CategoryCarousel.tsx — images matched positionally to the category list (business fills them in the same order); a category past the end of the slot keeps its SVG placeholder
one-banner-bg	single	PromoBanners.tsx → OneBanner
two-banner-bg	list (2)	PromoBanners.tsx → TwoBanners
three-banner-bg	list (3)	PromoBanners.tsx → ThreeBanners

Rule: every aspectRatio/recommendedWidth in that route file must match what the component actually renders. If you change a banner's size or ratio, update its slot entry in the same commit — that file is the only thing telling the dashboard (and the designer) what to upload.

Homepage banner placement (mirrors the logilook.com reference given for this layout): hero → categories → hot deals → three-banner-bg → موبایل carousel → two-banner-bg → لوازم جانبی → لپ تاپ → one-banner-bg → کنسول بازی → مجله.

Static pages

• /about — real copy transcribed from the live moalem.shop theme's about-us module (verified against its cached HTML, not invented); brand strip is plain text wordmarks (no scraped logo images — avoids a trademark/asset-licensing headache for names we don't have real logo files for) with real product photos pulled from the API.
• /contact — ContactForm.tsx posts to the real POST /contact-submissions (no bearer required); branch cards use BRANCHES from src/data/site.ts plus a key-less Google Maps output=embed iframe per branch (no API key needed for a query-based embed).
• /installments — flat, brand-colored hero (no photo, no gradient — this site stays flat) instead of the reference design's photographic banner; category highlights reuse the same categories static-image slot images as the homepage carousel, matched by the same positional index. One reference category ("خانه هوشمند") has no equivalent on this tenant and is swapped for "لوازم برقی" — see HIGHLIGHT_IDS in the page for the mapping.

Product / blog pages

• /products — full catalog, ?name= search, ?page=.
• /products/category/{id}/{slug} — category listing; merges every leaf in the subtree (see the leaf-category note above) and paginates in memory.
• /products/{id}/{slug} — detail: ProductGallery.tsx (click-to-lightbox + hover-zoom via a background-position overlay, desktop only), ProductBuyPanel.tsx (variants, price, auth-aware cart), ProductInfoTabs.tsx (توضیحات / مشخصات فنی / دیدگاه کاربران), related products from relatedProducts on the by-id response.
• /blog, /blog/{id}/{slug} — same shape, no variants/tabs; just content + CommentSection.tsx. Fallback posts (see table above) only exist in the listing grid, not as real detail pages.
• Technical specs: values[] from technical-info carries no label, only a fieldId — never render it directly. Join against form.fields first via src/lib/technicalInfo.ts#buildSpecRows.
• Comments: POST /comments doesn't require a bearer token at the API level, but CommentSection.tsx gates the form behind getSession() per the page brief — anonymous visitors get a login prompt instead of a textarea.

URLs (Meshkee canonical shapes)

• Product /products/{id}/{nameFaSlug}
• Category /products/category/{id}/{nameFaSlug}
• Blog /blog/{id}/{titleSlug}
• Helpers live in src/lib/slug.ts — build links with those, never by hand.

Published for the platform

• GET /meshkee/static-image-slots — slot catalog for the dashboard Refresh button
• GET /meshkee/sitemap-config.json — static pages only, auto-scanned from src/app at request time (src/app/meshkee/sitemap-config.json/route.ts) rather than hand-listed, so it can never advertise a page that doesn't exist yet. Product/category/blog/portfolio detail pages are excluded on purpose — Meshkee resolves those straight from the API.
• Do not add app/sitemap.ts or app/robots.ts: nginx proxies /sitemap.xml and /robots.txt to the API.

SEO rules for every new page

Unique <title> + meta description, exactly one <h1>, real <h2> structure, non-empty alt on every content image.

Scripts

npm run dev     # localhost:3000
npm run build
node scripts/gen-category-placeholders.mjs   # refresh category thumb placeholders