`** — Never use CSS grid (`grid-cols-13`) for exercise tables as column spans mismatch between headers and rows.
- **Table columns**: Select (checkbox) | Exercise | Muscle Group | Sets | Reps | Rest (sec) | Equipment
- **Input fields**: Each input (Sets, Reps, Rest) must be in its own `| ` with fixed width (`w-14`, `w-16`) and centered text.
- **Responsive**: Muscle Group and Equipment columns should use `hidden md:table-cell` to hide on mobile.
- **Container**: Add `overflow-x-auto` to the table wrapper for horizontal scroll on narrow screens.
### 5.6 Program Structure Page — Workout Complete Overlay (CRITICAL)
- **`showWorkoutComplete` state** (line 116): `const [showWorkoutComplete, setShowWorkoutComplete] = useState(false);` — DO NOT rename or remove this state variable.
- **`handleCompleteSet()` trigger** (line 398-425): When `currentSet >= totalSets` AND `currentExerciseIndex >= exercises.length - 1`, the function MUST set `setShowWorkoutComplete(true)` — DO NOT change this logic.
- **Workout Complete Overlay** (lines 814-843): A full-screen overlay (`fixed inset-0 z-50`) that displays:
- A green `check_circle` Material Symbol icon (`text-7xl text-emerald-400`)
- "Workout progress saved" heading (`text-4xl md:text-5xl font-serif italic`)
- "Great work! Your progress has been recorded." message
- **Dashboard button**: Links to `/fitness-planner/dashboard` with `bg-emerald-900 text-white` styling
- **Workout Plans button**: Links to `/fitness-planner/my-plans` with `bg-zinc-100 dark:bg-zinc-800` styling
- **DO NOT** remove, rename, or restructure the overlay. DO NOT change the navigation links or button labels.
- **DO NOT** add additional buttons or options to the overlay without updating this rule.
### 5.7 Program Structure Page — Pointing Hand / Exercise Selection Prompt (CRITICAL)
#### 5.7.1 State Variable
- **`hasClickedExercise`** (line 156): `const [hasClickedExercise, setHasClickedExercise] = useState(false);` — DO NOT rename or remove this state variable.
- Initialized to `false` — the pointing hand shows until user clicks an exercise.
#### 5.7.2 Trigger
- **`handleSelectExercise()`** (lines 385-397) MUST call `setHasClickedExercise(true)` when any exercise is clicked — DO NOT remove this call.
- The function signature is: `function handleSelectExercise(dayId: string, exerciseId: string)`
#### 5.7.3 Conditional Render Block (lines 1349-1359)
- The pointing hand 👈 and instructional text render when `!hasClickedExercise`:
```tsx
{!hasClickedExercise ? (
👈
First choose a starting exercise on the left panel then return here to start
) : null}
```
- **DO NOT** remove, rename, or restructure this conditional block.
- **DO NOT** re-add the old checkbox in place of the pointing hand.
- The `animate-pointing-hand` class and inline `pointLeft` animation must remain.
#### 5.7.4 CSS Animation (`src/app/globals.css` lines 405-413)
```css
@keyframes pointLeft {
0%, 100% { transform: translateX(0); }
50% { transform: translateX(-8px); }
}
```
- **DO NOT** remove or rename the `@keyframes pointLeft` animation.
- **DO NOT** remove the `.animate-pointing-hand` class usage.
### 5.8 My Plans Page Font Sizes
- Subtitle: `text-5xl md:text-6xl text-black dark:text-white font-serif italic`
- Bookmark icon: `text-3xl text-black dark:text-white`
- Plans count: `text-lg font-bold uppercase tracking-widest text-black dark:text-white`
- Saved Programs heading: `text-lg font-bold uppercase tracking-widest text-black dark:text-white`
- Saved program descriptions: `text-3xl text-black dark:text-white leading-relaxed line-clamp-2`
- Active program description: `text-black dark:text-white font-serif italic text-2xl`
---
## 6. Shop / Product Preview Rules
### 6.1 Product Listing Card (`src/app/shop/[category]/page.tsx`)
- **Compact spacing**: Card info area uses `p-5`, `mt-0.5`, `pt-1.5`, `pt-2`, `gap-2`, `py-3`.
- **DO NOT** increase padding/margins on: `.p-5` (card), `.mt-0.5` (brand), `.pt-1.5` (price), `.pt-2` (button wrapper), `.gap-2` (button gap), `.py-3` (button).
- **DO NOT** change font sizes, weights, or colors on card elements.
- **Uniform heights**: Cards use `flex-1` + `mt-auto` to maintain equal height regardless of text length.
- **Button label**: "View Details" (not "Shop at Partner").
### 6.2 Product Preview Modal
- **Wide modal**: `max-w-[1600px]`, `w-[98vw]`, `max-h-[92vh]` — DO NOT narrow these values.
- **No inner wrapper**: The `max-w-6xl mx-auto` wrapper was removed — DO NOT re-add it.
- **Column split**: Image `md:w-[30%]`, Article `md:w-[70%]` — DO NOT reduce article width.
- **Content height**: `maxHeight: '700px'` on both columns — DO NOT reduce this.
- **Padding**: Modal wrapper `p-6`, article column `p-6` — DO NOT increase these.
- **CTA label**: "Shop Now" (not "Shop at Partner").
### 6.3 Preview Article Typography (`.preview-article-content`)
- **Base font**: `20px` with `line-height: 1.7` — DO NOT reduce font size below 18px.
- **H1**: `34px` with `line-height: 1.3`.
- **H2**: `28px` with `line-height: 1.35`.
- **H3**: `24px` with `line-height: 1.4`.
- **Paragraph/List**: `line-height: 1.7`.
- All preview typography is scoped to `.preview-article-content` — no global impact.
### 6.4 Price Range Filter
- Default `priceRange`: `1000` (not `500`).
- Slider `max`: `1000` (not `500`).
---
## 7. Analytics & Tracking Rules
### 7.1 Token Tracking
- MUST log after every DeepSeek API call in `deepseek-service.ts`.
- MUST log after every AI draft generation in `draft/route.ts`.
- `getDailyTokenBreakdown()` in `token-tracker.ts` must return `inputTokens`/`outputTokens` from SQL SUM of `input_tokens` and `output_tokens` columns.
### 7.2 Scraping Tracking
- MUST log after every Tavily API call in `content-research.ts`.
### 7.3 AnalyticsProvider Placement
- MUST be placed **inside** `` wrapper in `src/app/layout.tsx` — never outside.
---
## 8. Admin Layout & Auth Rules
### 8.1 Sidebar
- All `AdminNavLink` components must have `prefetch={true}` — never omit prefetch on admin nav links.
### 8.2 Auth
- Admin uses JWT via `jose` library, stored in `admin_session` cookie.
- Fitness users use sessionStorage-based auth (NOT NextAuth).
- Admin login flow: email/password → OTP verification → JWT session.
### 8.3 Import Paths
- All imports in `src/app/admin/visitors/page.tsx` must use `@/` alias path — never use relative imports (`./`) for same-directory modules.
- `VisitorChatInterface` must use `@/components/admin/VisitorChatInterface`.
- `RegisteredMembersSection` must use `@/app/admin/visitors/RegisteredMembersSection`.
---
## 9. Database & Migration Rules
### 9.1 SQLite Schema
- Dual-mode DB: SQLite primary (no MySQL currently active).
- All queries use `@/lib/db` helper.
- `Product` table has `faqs` as TEXT (JSON stringified).
- `ProductArticle` table has `richTextState` as TEXT (JSON serialized).
- `user_profiles` uses `user_email` as PK (not `id`).
### 9.2 Migration Pattern
- Migrations are SQL files in `migrations/` directory.
- Run via `node scratch/run_*_migration.js` scripts.
- ALTER TABLE must use `IF NOT EXISTS` for idempotency.
### 9.3 Admin Credentials
- `mngarii@gmail.com` / `admin32i`
- `magdah785@gmail.com` / `admin32i`
- Passwords are bcrypt-hashed via `setup_admin.js`.
---
## 10. Build & Dev Server Rules
### 10.1 Dev Server
- Use `next dev --turbopack` (NOT plain `next dev` which has webpack persistent cache races on Windows).
- If Turbopack cache corrupts: clear `.next-dev` directory and restart.
- If webpack dev path is ever needed: add project directory to Windows Defender exclusions to avoid file-lock race.
### 10.2 Build Verification
- `next build` must compile with zero errors.
- `tsc --noEmit` must produce zero type errors.
### 10.3 VS Code Settings
- `css.lint.unknownAtRules`: `"ignore"` — suppresses false positive warnings for `@tailwind` directives.
- `js/ts.preferences.importModuleSpecifier` — use this (NOT deprecated `typescript.preferences.importModuleSpecifier`).
---
## 11. CSS & Styling Rules
### 11.1 globals.css
- `.ProseMirror` styles handle editor content (NOT `prose prose-sm` class from `@tailwindcss/typography`).
- Blockquote: `border-left: 3px solid #10b981` with CSS `quotes` property for quotation marks.
- `em`, `u`, `strong` must have `!important` to prevent Tailwind CSS reset overrides.
- `.article-content` class provides premium typography for product articles.
### 11.2 Tailwind Config
- `@tailwindcss/typography` plugin is installed and configured.
- Custom colors: `primary`, `surface`, `on-surface`, `primary-container`, `on-primary-container`.
### 11.3 Color Scheme
- Primary: `#064e3b` (emerald-900).
- Secondary: `#059669` (emerald-600).
- Border radius: 12px (`rounded-xl`) and 32px (`rounded-[2rem]`).
---
## 12. Import & Module Rules
### 12.1 CSS Side-effect Imports
- `global.d.ts` at project root declares `declare module '*.css'` plus common stylesheet extensions.
- `tsconfig.json` includes `**/*.d.ts` so the declaration is recognized.
### 12.2 Next.js Config
- Use default `.next` output directory (NOT custom `.next-dev`).
- `next-env.d.ts` points at `./.next/types/routes.d.ts`.
### 12.3 Package.json
- Dev script: `"dev": "next dev --turbopack"`.
---
## 13. API Route Rules
### 13.1 Products API (`/api/products`)
- **GET**: Joins `Product p` with `Category c`, supports `category`, `affiliate`, `page`, `limit`, `published` query params.
- **POST**: UUID v4 ID generation, inserts all fields including `commission`, `revenue`, `cookieLife`.
- **PUT**: Updates all fields, returns `{ product: { ...product, id: result.lastInsertRowid } }`.
- **DELETE**: Deletes by `id` query param.
- Error handling: Use `req.clone().text()` instead of `req.text()` to avoid "body stream already read" error.
### 13.2 Products Upload API (`/api/products/upload`)
- Accepts multipart form upload via `formidable`.
- Sharp pipeline: resize to 800×800 (`fit: 'inside'`), convert to WebP (quality 75).
- Sharp fallback: save original file with original extension if Sharp fails.
- Returns `{ success: true, url, filename, size }`.
### 13.3 Products Article API (`/api/products/article`)
- **POST**: Save article content with `productId`, `productDescription`, `richTextState`.
- **GET**: Retrieve saved article by `productId`. Falls back to `Product.productDescription` if no `ProductArticle` record exists.
### 13.4 Content Intelligence Generate API (`/api/content-intelligence/generate`)
- Pipeline: DeepSeek crafts research query → 1 Tavily call → DeepSeek generates article.
- **3 Tavily calls per generation was reduced to 1** via DeepSeek query crafting.
- Returns `{ content: { articleHtml, ... } }`.
### 13.5 Settings API (`/api/admin/settings`)
- **GET**: Returns all settings including `tokenDailyBreakdown` from `getDailyTokenBreakdown()`.
- **PUT**: Updates settings in `admin_settings` table.
### 13.6 Issues API (`/api/admin/issues`)
- **GET**: Returns issues with optional `period` query param. Returns `issues`, `severityTotals`, `statusCounts`, `categoryCounts`, `totalIssues`.
- **POST**: Creates new issue with title, category, severity, description, steps_to_reproduce.
- **PUT**: Updates issue status.
### 13.7 Admins API (`/api/admin/admins`)
- **GET**: Paginated list with `page` and `limit` params.
- **POST**: Create admin with email, username, password, role. Validates email uniqueness, password min 6.
- **PUT**: Update admin. Email uniqueness check excludes current admin. Only superadmin can change roles.
- **DELETE**: Delete admin. Prevents self-deletion (403 if `targetAdmin[0].email === session.email`).
### 13.8 Fitness API Routes
- All must use shared `getDb()` from `@/lib/workout-planner/db` — never raw `sqlite3`.
- Programs: `/api/fitness/programs?userId=...&status=active` (NOT `/api/fitness/programs/active`).
---
## 14. Content Intelligence Rules
### 14.1 DeepSeek + Tavily Pipeline
- **Step 1**: DeepSeek `generateResearchQuery()` crafts ONE optimized Tavily search query from product data.
- **Step 2**: Tavily `singleResearchCall()` executes the query (1 call total).
- **Step 3**: DeepSeek `generateContent()` produces final SEO-optimized article.
- Total: **1 Tavily call per generation** (reduced from 3).
### 14.2 Legacy Functions
- `searchProductResearch()`, `searchComparisonData()`, `consolidatedFAQResearch()`, `batchSearchFAQs()` — kept for backward compatibility but NOT used by the generate route.
- `generateSEOBlogPost()` — legacy client-side template function, NOT used by "Generate Article" button.
### 14.3 Error Handling
- Always check `!res.ok` before `res.json()` in ALL Content Intelligence API calls.
- Fallback query generation if DeepSeek API fails.
---
## 15. Fitness Planner Rules
### 15.1 Profile Save
- SQLite schema migration runs on every POST request via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` block.
- Idempotent: gracefully skips columns that already exist.
### 15.2 Form Field Mapping
- `mapFormDataToApi()` function maps form field names to API expectations:
- `formData.goal` → `apiData.goals`
- `formData.level` → `apiData.fitness_level`
- `formData.days` → `apiData.days_per_week`
### 15.3 Progress Display
- `visibleSteps` computed based on `focus` to exclude irrelevant steps (dietary, calories, etc. for "workout" focus).
- Progress bar shows correct fraction (e.g., "6 out of 6 steps").
### 15.4 Dashboard Workout Plan Extraction
- Use `(workoutPlan?.dailyWorkouts?.[0]?.exercises || fallbackWorkoutPlan).slice(...)` — NOT `(workoutPlan || fallbackWorkoutPlan).slice(...)` which crashes when workoutPlan is an object.
### 15.5 Calorie Tracker / Meal Planner
- Must show "Coming Soon" badge with `isComingSoon` flag.
- Coming Soon text and icon must be legible (increased size, padding, shadow).
### 15.6 Program Library Page (`src/app/fitness-planner/library/page.tsx`)
- **Inline navigation**: Uses its own inline nav with brand link + back arrow — NOT `WorkoutNav` component. Do NOT replace with WorkoutNav unless layout is intentionally redesigned.
- **GSAP animation pattern**: Cards use `gsap.fromTo()` with `{ opacity: 0, y: 30 }` → `{ opacity: 1, y: 0, stagger: 0.06, duration: 0.5, ease: "power3.out" }` triggered by `filteredTemplates` change.
- **Save Plan flow**: `handleSaveProgram()` first checks user profile (`/api/user/profile`), alerts and redirects to `/fitness-planner` if no email found, then POSTs to `/api/fitness/programs`.
- **Set Active flow**: `handleSetActive()` first checks if program is already saved; if not, saves with `is_active: true`; if saved, finds user program by `template_id` and PUTs `is_active: true`, then redirects to `/fitness-planner/dashboard`.
- **LEVEL_BADGE_STYLES**: beginner = `bg-emerald-600 text-white`, intermediate = `bg-blue-600 text-white`, advanced = `bg-orange-600 text-white`.
- **Card footer**: Always has "Select Workout" Link (left) + conditional button: "Active" (disabled green), "Set Active" (clickable), or "Save Plan" (clickable).
### 15.7 WorkoutNav Component (`src/components/WorkoutNav.tsx`)
- **currentPage prop**: Accepts `'dashboard' | 'my-plans' | 'program' | 'library'`.
- **Used by**: `my-plans/page.tsx` (currentPage="my-plans"), `program/[programId]/page.tsx` (currentPage="program").
- **NOT used by**: `library/page.tsx` (uses inline nav).
- **Link styling**: `text-[18px] font-bold uppercase tracking-widest` with emerald-600 active state.
- **Links**: Dashboard → `/fitness-planner/dashboard`, Workout Plans → `/fitness-planner/my-plans`, Change Workout Goal → `/fitness-planner`.
### 15.8 Program Structure Page (`src/app/fitness-planner/program/[programId]/page.tsx`)
- **File size**: 1855 lines, 86,152 bytes — EXTREME CAUTION required for modifications.
- **WorkoutNav**: Uses `` at line 865.
- **Pointing hand state**: `hasClickedExercise` (line 156) is set to true in `handleSelectExercise()` . **CRITICAL**: Renders when `!hasClickedExercise`.
- **Set tracking**: Auto-saves every 10 seconds during workout mode via `setInterval` in useEffect (lines 195-200).
- **Rest timer capture fix (CRITICAL)**: `captureRestTime()` uses `lastCompletedSetRef.current` (NOT `currentSet - 1`) to determine which set's rest data to save. When completing the last set of an exercise, `currentSet` gets reset to 1 for the next exercise before the rest timer starts. Using `lastCompletedSetRef` (set in `handleCompleteSet()`) ensures rest time is always saved to the correct set. DO NOT revert to `currentSet - 1` -- this broke rest capture for the last set of each exercise.
- **Two-column layout**: Left panel (collapsible, `w-[35%]`) + Right panel (exercise details + set tracking table) during workout mode.
---
## APPENDIX: Quick Reference — Files That Must NOT Be Modified Without Full Understanding
| File | Risk Level | Reason |
|------|-----------|--------|
| `src/app/admin/products/page.tsx` | 🔴 CRITICAL | 2143 lines, 20+ state vars, complex preview/edit/create flow |
| `src/components/RichTextToolbar.tsx` | 🔴 CRITICAL | TipTap extension conflicts, image picker, resize, drag-drop |
| `src/components/admin/SettingsPanel.tsx` | 🔴 CRITICAL | 7 tabs, 12+ issue state vars, plugin management, token charts |
| `src/app/shop/[category]/page.tsx` | 🟡 HIGH | Card spacing, preview modal dimensions, typography |
| `src/app/globals.css` | 🟡 HIGH | ProseMirror, preview-article-content, blockquote styles |
| `src/app/layout.tsx` | 🟡 HIGH | AnalyticsProvider placement, editor bridge script |
| `src/app/api/products/route.ts` | 🟡 HIGH | PUT returns id, error handling, body stream fix |
| `src/lib/content-intelligence/deepseek-service.ts` | 🟡 HIGH | Token tracking hook, research query generation |
| `src/lib/content-intelligence/content-research.ts` | 🟡 HIGH | Scraping tracking hook, singleResearchCall |
| `src/components/admin/VisitorChatInterface.tsx` | 🟡 HIGH | Border rules, column structure, draft area |
| `src/app/fitness-planner/library/page.tsx` | 🟡 HIGH | 391 lines, GSAP card animation, inline nav (no WorkoutNav), save/active program flow, filter tabs, level badge color rules |
| `src/app/fitness-planner/dashboard/page.tsx` | 🟡 HIGH | Workout plan extraction, no next-auth import |
| `src/app/admin/layout.tsx` | 🟡 HIGH | Sidebar prefetch, auth gate |
| `src/app/admin/visitors/page.tsx` | 🟢 MEDIUM | Import path rules |
| `src/lib/workout-planner/db.ts` | 🟢 MEDIUM | Shared DB module for fitness routes |
| `src/app/api/admin/admins/route.ts` | 🟢 MEDIUM | Role sanitization, self-deletion prevention |
| `src/app/api/admin/issues/route.ts` | 🟢 MEDIUM | Issue CRUD with period aggregation |
| `src/app/api/admin/settings/route.ts` | 🟢 MEDIUM | Token daily breakdown in response |
| `src/app/api/products/upload/route.ts` | 🟢 MEDIUM | Sharp fallback, fit: 'inside' |
| `src/app/api/content-intelligence/generate/route.ts` | 🟢 MEDIUM | 1 Tavily call pipeline |
| `src/app/fitness-planner/program/[programId]/page.tsx` | 🔴 CRITICAL | 1855 lines / 86KB, pointing hand state, WorkoutNav integration, set tracking, auto-save timer, two-column workout layout |
| `src/app/fitness-planner/my-plans/page.tsx` | 🟢 MEDIUM | Font size rules |
| `src/app/fitness-planner/page.tsx` | 🟢 MEDIUM | Form mapping, progress display, coming soon |
| `src/app/api/user/profile/route.ts` | 🟢 MEDIUM | SQLite schema migration on POST |
| `src/components/WorkoutNav.tsx` | 🟢 MEDIUM | 35 lines, currentPage prop type, used by my-plans + program pages (NOT library page) |
| `src/components/admin/AffiliateDashboard.tsx` | 🟢 MEDIUM | Print/PDF/Word export functions |
| `src/app/api/publish/article-data/[productId]/route.ts` | 🟢 MEDIUM | Promise<{ productId }> params type |
### 15.9 Email Verification System
- **verification_tokens table**: Stores tokens with 5-min expiry. Tokens are one-time use (used flag).
- **src/lib/verify.ts**: Uses crypto.randomBytes(24) for tokens. NEVER change to Math.random().
- **src/app/verify-email/page.tsx**: useSearchParams MUST be wrapped in Suspense boundary.
- **SMTP config**: Uses existing .env vars (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS).
### 15.10 Subscription Dev Testing
- **API mode override**: Add ?mode=trial|premium|expired|bypass to test subscription states.
- **Dev page**: public/dev-subscription.html - DELETE before production deployment.
- **Default behavior**: No mode param = normal subscription logic from profile creation date.
### 15.11 Template Generator
- **scripts/seed-templates-all.py**: Safe to re-run (INSERT OR IGNORE). Generates 105 templates.
- **Exercise pools**: Maps muscle groups x difficulty. Edit to add/modify exercises.
- **Level scaling**: beginner=3x10-12, intermed=4x8-10, advanced=5x5-8.
|