# MarichWellness — Project Architecture Report

> **Generated:** 2026-06-29  
> **Project Root:** `maggyafftng`  
> **Database:** SQLite (`database.sqlite`) with MySQL compatibility  
> **Framework:** Next.js (App Router)  
> **Language:** TypeScript  
> **Styling:** Tailwind CSS  
> **Rich Text:** TipTap Editor  

---

## 1. HIGH-LEVEL ARCHITECTURE

```
┌─────────────────────────────────────────────────────────────┐
│                    NEXT.JS APP ROUTER                        │
│  (src/app/)                                                  │
│                                                              │
│  ┌─────────────────────┐  ┌──────────────────────────────┐  │
│  │   PUBLIC SITE        │  │   ADMIN PORTAL               │  │
│  │   (marichwellness)   │  │   (admin subdomain/path)     │  │
│  │                      │  │                              │  │
│  │  - Home              │  │  - Dashboard                 │  │
│  │  - Products/Shop     │  │  - Products CRUD             │  │
│  │  - Journal/Blog      │  │  - Content Intelligence      │  │
│  │  - Contact           │  │  - Visitor Chat              │  │
│  │  - Fitness Planner   │  │  - Settings                  │  │
│  │  - User Profile      │  │  - Issues Tracker            │  │
│  │  - Auth (Email OTP)  │  │  - Affiliate Dashboard       │  │
│  └─────────────────────┘  └──────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              SHARED COMPONENTS (src/components/)      │   │
│  │  RichTextToolbar, WorkoutNav, GoBackButton,           │   │
│  │  AnalyticsProvider, TermsModal, Footer, Discover,     │   │
│  │  PreviewInsightsPanel, ContentWorkspaceTabs,          │   │
│  │  ContentIntelligencePreview, admin/*                  │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              API ROUTES (src/app/api/)                │   │
│  │  admin/*, auth/*, analytics/*, contact/*,             │   │
│  │  fitness/*, products/*, publish/*, user/*             │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              LIBRARIES (src/lib/)                     │   │
│  │  db.ts, auth.ts, config.ts, email.ts, password.ts,   │   │
│  │  verify.ts, useSubscription.ts,                       │   │
│  │  supplementRecommendations.ts,                        │   │
│  │  analytics/*, content-intelligence/*,                 │   │
│  │  workout-planner/db.ts                                │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. DATABASE SCHEMA (26 Tables)

### 2.1 Admin Portal Tables

| # | Table | Purpose | Key Columns |
|---|-------|---------|-------------|
| 1 | `admins` | Admin accounts | id, email, username, password_hash, otp_email, role, is_active |
| 2 | `admin_otps` | OTP verification codes | id, admin_email, code, expires_at |

### 2.2 Public Site Tables

| # | Table | Purpose | Key Columns |
|---|-------|---------|-------------|
| 3 | `User` | Customer accounts | id, email, passwordHash, name, username, role, is_active |
| 4 | `user_profiles` | Extended wellness profiles | user_email, wellness_goal, fitness_level, equipment, dietary, calculated_* |
| 5 | `Category` | Product categories | id, name, slug, image, description, parentId |
| 6 | `Product` | Products (supplements & equipment) | id, name, slug, price, image, brand, stock, badge, isAffiliate, affiliateLink, benefits, categoryId, publishStatus, commission, revenue, cookieLife, faqs, keywords |
| 7 | `ProductArticle` | Rich-text article content | id, productId, productDescription, richTextState |
| 8 | `Order` | Customer orders | id, userId, totalAmount, status |
| 9 | `OrderItem` | Order line items | id, orderId, productId, quantity, price |
| 10 | `SavedItem` | Wishlist/favorites | id, userId, productId |
| 11 | `CartItem` | Shopping cart | id, userId, productId, quantity |
| 12 | `BlogArticle` | Journal/blog articles | id, title, slug, content, excerpt, image, author, published |
| 13 | `ContactMessage` | Contact form submissions | id, name, email, message, status, reply_text, replied_at |
| 14 | `SiteConfig` | Site configuration | id, config_key, config_value |
| 15 | `UserAction` | Activity tracking/analytics | id, userId, visitorId, actionType, entityType, entityId, metadata |

### 2.3 Workout Planner Tables (v1.0)

| # | Table | Purpose | Key Columns |
|---|-------|---------|-------------|
| 16 | `exercise_library` | Exercise database (42 exercises) | id, name, muscle_group, secondary_muscles, equipment, difficulty, instructions, pro_tips, common_mistakes, is_cardio, is_bodyweight |
| 17 | `workout_templates` | Pre-built programs (9 programs) | id, name, description, level, goal, days_per_week, total_weeks, equipment_needed, who_is_for |
| 18 | `workout_template_weeks` | Template weeks | id, template_id, week_number, focus |
| 19 | `workout_template_days` | Template days | id, week_id, day_number, day_name, focus_area, is_rest_day |
| 20 | `workout_template_exercises` | Template day exercises | id, day_id, exercise_id, sets, reps, rest_seconds, order_index, notes |
| 21 | `user_saved_programs` | User-saved programs | id, user_id, template_id, name, is_active, is_custom, source, current_week, current_day |
| 22 | `user_workout_days` | Custom user days | id, user_program_id, week_number, day_number, day_name, focus_area, is_rest_day |
| 23 | `user_workout_exercises` | Custom user exercises | id, user_day_id, exercise_id, sets, reps, rest_seconds, order_index |
| 24 | `workout_sessions` | Active workout tracking | id, user_id, user_program_id, week_number, day_number, started_at, ended_at, duration_seconds, status |
| 25 | `user_workout_progress` | Daily/weekly progress | id, user_id, user_program_id, week_number, day_number, date, completed, exercises_done, sets_done, calories_burned, duration_minutes |

### 2.4 Utility Tables

| # | Table | Purpose |
|---|-------|---------|
| 26 | `test_upsert` | Test/utility table |

### 2.5 Migration Files (018 total)

| Migration | Tables Created | Status |
|-----------|---------------|--------|
| 001 | faq_cache | ✅ |
| 002 | published_articles | ✅ |
| 003 | conversations, conversation_messages | ✅ |
| 004 | analytics_events | ✅ |
| 005 | settings_tables | ✅ |
| 006 | issue_tracker | ✅ |
| 007 | token_usage_breakdown | ✅ |
| 008 | workout_planner (exercise_library, workout_templates, etc.) | ✅ |
| 009 | exercise_timing | ✅ |
| 010 | set_tracking | ✅ |
| 011 | verification_tokens | ✅ |
| 012 | weight_log | ✅ |
| 013 | Product, ProductArticle | ✅ |
| 014 | admins, admin_otps, User | ✅ |
| 015 | Category | ✅ |
| 016 | BlogArticle, ContactMessage | ✅ |
| 017 | SiteConfig, UserAction | ✅ |
| 018 | CartItem, SavedItem | ✅ |

---

## 3. ROUTE STRUCTURE

### 3.1 Public Routes (`src/app/`)

| Route | File | Purpose |
|-------|------|---------|
| `/` | `page.tsx` | Homepage |
| `/products` | `products/page.tsx` | Product listing |
| `/products/[slug]` | `products/[slug]/page.tsx` | Product detail |
| `/shop/[category]` | `shop/[category]/page.tsx` | Category shop |
| `/journal` | `journal/page.tsx` | Blog listing |
| `/contact` | `contact/page.tsx` | Contact form |
| `/terms` | `terms/page.tsx` | Terms & conditions |
| `/profile` | `profile/page.tsx` | User profile |
| `/verify-email` | `verify-email/page.tsx` | Email verification |
| `/fitness-planner` | `fitness-planner/page.tsx` | Fitness planner hub |
| `/fitness-planner/dashboard` | `fitness-planner/dashboard/page.tsx` | User dashboard |
| `/fitness-planner/my-plans` | `fitness-planner/my-plans/page.tsx` | User's saved plans |
| `/fitness-planner/library` | `fitness-planner/library/page.tsx` | Template library |
| `/fitness-planner/library/[templateId]` | `fitness-planner/library/[templateId]/page.tsx` | Template detail |
| `/fitness-planner/program/[programId]` | `fitness-planner/program/[programId]/page.tsx` | Active program view |
| `/fitness-planner/edit` | `fitness-planner/edit/page.tsx` | Program editor |
| `/fitness-planner/day` | `fitness-planner/day/page.tsx` | Day view |
| `/fitness-planner/day/[dayId]` | `fitness-planner/day/[dayId]/page.tsx` | Specific day view |

### 3.2 Admin Routes (`src/app/admin/`)

| Route | File | Purpose |
|-------|------|---------|
| `/admin` | `admin/page.tsx` | Dashboard |
| `/admin/login` | `admin/login/page.tsx` | Admin login |
| `/admin/settings` | `admin/settings/page.tsx` | Settings panel |
| `/admin/products` | `admin/products/page.tsx` | Product management |
| `/admin/visitors` | `admin/visitors/page.tsx` | Visitor chat interface |

### 3.3 API Routes (`src/app/api/`)

| Route | Purpose |
|-------|---------|
| `admin/auth/login` | Admin login |
| `admin/auth/verify-otp` | OTP verification |
| `admin/admins` | Admin user management |
| `admin/users` | User management |
| `admin/profiles` | Profile management |
| `admin/products` | Product CRUD |
| `admin/supplements` | Supplement management |
| `admin/settings` | Settings management |
| `admin/settings/profile` | Profile settings |
| `admin/issues` | Issue tracker |
| `admin/conversations` | Visitor conversations |
| `admin/conversations/[id]/messages` | Conversation messages |
| `admin/conversations/[id]/send` | Send message |
| `admin/conversations/[id]/close` | Close conversation |
| `admin/conversations/[id]/draft` | Draft management |
| `auth/send-verification` | Send email verification |
| `auth/verify-email` | Verify email |
| `analytics/track` | Track analytics events |
| `analytics/summary` | Analytics summary |
| `contact` | Contact form submission |
| `fitness/templates` | Workout templates CRUD |
| `fitness/templates/[templateId]` | Single template |
| `fitness/programs` | User programs CRUD |
| `fitness/programs/[programId]` | Single program |
| `fitness/programs/[programId]/exercises` | Program exercises |
| `fitness/sessions` | Workout sessions |
| `fitness/sessions/[sessionId]` | Single session |
| `fitness/sessions/[sessionId]/exercises` | Session exercises |
| `fitness/sessions/[sessionId]/sets` | Session sets |
| `fitness/dashboard` | User dashboard data |
| `fitness/progress` | Progress tracking |
| `products` | Products listing |
| `products/article` | Product articles |
| `products/upload` | Product image upload |
| `publish/status-change` | Publish status changes |
| `publish/article-data/[productId]` | Article data |
| `content-intelligence/analyze` | Content analysis |
| `content-intelligence/generate` | Content generation |
| `content-intelligence/optimize` | Content optimization |
| `content-intelligence/preset-estimate` | Preset estimates |
| `content-intelligence/export/pdf` | PDF export |
| `content-intelligence/export/docx` | DOCX export |
| `user/profile` | User profile |

---

## 4. COMPONENT ARCHITECTURE

### 4.1 Shared Components (`src/components/`)

| Component | Purpose |
|-----------|---------|
| `RichTextToolbar.tsx` | TipTap rich text editor toolbar |
| `WorkoutNav.tsx` | Fitness planner navigation |
| `GoBackButton.tsx` | Back navigation button |
| `AnalyticsProvider.tsx` | Analytics context provider |
| `TermsModal.tsx` | Terms & conditions modal |
| `Footer.tsx` | Site footer |
| `Discover.tsx` | Discovery section component |
| `PreviewInsightsPanel.tsx` | Content preview with insights |
| `ContentWorkspaceTabs.tsx` | Content workspace tab interface |
| `ContentIntelligencePreview.tsx` | AI content preview |

### 4.2 Admin Components (`src/components/admin/`)

| Component | Purpose |
|-----------|---------|
| `SettingsPanel.tsx` | Admin settings panel |
| `AffiliateDashboard.tsx` | Affiliate marketing dashboard |
| `VisitorChatInterface.tsx` | Visitor chat interface |

### 4.3 Context Providers (`src/context/`)

| Context | Purpose |
|---------|---------|
| `AnalyticsContext.tsx` | Analytics state management |
| `WishlistContext.tsx` | Wishlist/favorites state |

---

## 5. LIBRARY LAYER

### 5.1 Core Libraries (`src/lib/`)

| File | Purpose |
|------|---------|
| `db.ts` | Database connection (SQLite/MySQL abstraction) |
| `auth.ts` | Authentication utilities |
| `config.ts` | Application configuration |
| `email.ts` | Email sending utilities |
| `password.ts` | Password hashing/verification |
| `verify.ts` | Verification utilities |
| `useSubscription.ts` | Subscription management hook |
| `supplementRecommendations.ts` | Supplement recommendation engine |

### 5.2 Analytics (`src/lib/analytics/`)

| File | Purpose |
|------|---------|
| `tracker.ts` | Analytics event tracking |
| `service.ts` | Analytics service layer |
| `token-tracker.ts` | Token usage tracking |
| `scraping-tracker.ts` | Scraping detection |

### 5.3 Content Intelligence (`src/lib/content-intelligence/`)

| File | Purpose |
|------|---------|
| `config.ts` | Content intelligence configuration |
| `content-analyzer.ts` | Content analysis engine |
| `content-research.ts` | Content research utilities |
| `deepseek-service.ts` | DeepSeek AI integration |
| `export-service.ts` | PDF/DOCX export service |

### 5.4 Workout Planner (`src/lib/workout-planner/`)

| File | Purpose |
|------|---------|
| `db.ts` | Workout planner database queries |

---

## 6. MIDDLEWARE & AUTHENTICATION

### 6.1 Middleware (`src/middleware.ts`)

- **Purpose:** Route protection and admin subdomain handling
- **Key behaviors:**
  - Detects `admin.` subdomain or `/admin` path prefix
  - Verifies JWT token from `admin_session` cookie using `jose`
  - Redirects unauthenticated users to `/admin/login`
  - Redirects authenticated users away from login page
  - Rewrites admin subdomain paths to `/admin/*`
- **Matcher:** Excludes `/api`, `/_next/static`, `/_next/image`, `/favicon.ico`

### 6.2 Authentication Flow

```
Admin Login:
  1. POST /api/admin/auth/login → validates credentials
  2. Returns OTP sent to admin email
  3. POST /api/admin/auth/verify-otp → verifies OTP code
  4. Sets JWT cookie (admin_session)
  5. Redirects to /admin dashboard

User Auth:
  1. POST /api/auth/send-verification → sends verification email
  2. GET /api/auth/verify-email → verifies email token
```

---

## 7. FITNESS PLANNER ARCHITECTURE

### 7.1 Data Flow

```
Template Library → User saves program → User customizes days/exercises
                                          ↓
                                    Workout Session (active tracking)
                                          ↓
                                    Progress Logging (sets, reps, duration)
                                          ↓
                                    Dashboard (aggregated stats)
```

### 7.2 Key Relationships

```
workout_templates
  └── workout_template_weeks
        └── workout_template_days
              └── workout_template_exercises ──→ exercise_library

user_saved_programs (copied from template or custom)
  └── user_workout_days
        └── user_workout_exercises ──→ exercise_library

workout_sessions (active tracking)
  └── user_workout_progress (daily logs)
```

### 7.3 Seeded Data

- **Exercise Library:** 42 exercises across 9 muscle groups
- **Pre-Built Programs:** 9 programs (3 beginner, 3 intermediate, 3 advanced)
  - Beginner: Full Body Starter, Beginner Fat Burn, Beginner Muscle Builder
  - Intermediate: Push Pull Legs, Upper Lower Split, Endurance & Conditioning
  - Advanced: 5/3/1 Powerbuilding, Advanced Bodybuilding, Athletic Performance
- **Total Template Weeks:** 9 (1 week each)
- **Total Template Days:** 63
- **Total Template Exercises:** 190

---

## 8. CONTENT INTELLIGENCE SYSTEM

### 8.1 Architecture

```
User Input → Content Research (Tavily API) → DeepSeek AI Analysis
                                                ↓
                                    Content Generation/Optimization
                                                ↓
                                    Export (PDF/DOCX)
```

### 8.2 Components

- **Content Research:** Uses Tavily API for web research
- **DeepSeek Service:** AI-powered content analysis and generation
- **Export Service:** PDF (via Puppeteer) and DOCX (via docx library) export
- **Token Tracker:** Monitors API token usage with breakdowns

---

## 9. ANALYTICS SYSTEM

### 9.1 Architecture

```
User Action → Analytics Tracker → API Route → Database (UserAction table)
                                                ↓
                                    Analytics Service → Summary API
                                                ↓
                                    Dashboard Display
```

### 9.2 Features

- Page view tracking
- User action logging
- Scraping detection
- Token usage monitoring
- Dashboard aggregation

---

## 10. KEY TECHNICAL DECISIONS & PATTERNS

### 10.1 Database

- **Primary:** SQLite (`database.sqlite`) for development
- **Production:** MySQL (`marich_wellness_db`) compatibility
- **Connection:** Abstracted via `src/lib/db.ts`
- **Migrations:** Sequential SQL files in `migrations/` directory

### 10.2 Image Handling

- **Upload:** Sharp library for processing
- **Format:** WebP at quality 75
- **Size:** 800×800 pixels
- **Storage:** `public/uploads/products/`

### 10.3 Rich Text Editing

- **Editor:** TipTap (ProseMirror-based)
- **Extensions:** StarterKit (built-in), Link, Image, Placeholder, TextAlign
- **Storage:** JSON serialized editor state in `ProductArticle.richTextState`

### 10.4 Authentication

- **Admin:** JWT tokens via `jose` library
- **Users:** Email-based OTP verification
- **Session:** Cookie-based (`admin_session`)

### 10.5 Styling

- **Framework:** Tailwind CSS
- **Configuration:** `tailwind.config.js` with custom theme

---

## 11. PROJECT STRUCTURE SUMMARY

```
maggyafftng/
├── migrations/          # 18 SQL migration files
├── memory/              # Project documentation & memory
├── public/              # Static assets (images, uploads)
├── scratch/             # Development/test scripts
├── scripts/             # Utility scripts (seed, migrate)
├── src/
│   ├── app/             # Next.js App Router pages & API
│   │   ├── admin/       # Admin portal (8 routes)
│   │   ├── api/         # API routes (30+ endpoints)
│   │   ├── fitness-planner/  # Fitness planner (8 routes)
│   │   └── ...          # Public pages
│   ├── components/      # Shared React components
│   │   └── admin/       # Admin-specific components
│   ├── context/         # React context providers
│   └── lib/             # Utility libraries
│       ├── analytics/   # Analytics system
│       ├── content-intelligence/  # AI content tools
│       └── workout-planner/  # Fitness planner DB layer
├── package.json
├── tailwind.config.js
├── next.config.mjs
└── database.sqlite
```

---

## 12. DEPENDENCIES & INTEGRATIONS

| Integration | Purpose |
|-------------|---------|
| **Next.js 15** | Web framework (App Router) |
| **SQLite** | Development database |
| **MySQL** | Production database |
| **TipTap** | Rich text editor |
| **Tailwind CSS** | Styling |
| **Jose** | JWT token handling |
| **Sharp** | Image processing |
| **DeepSeek AI** | Content intelligence |
| **Tavily API** | Web research |
| **Puppeteer** | PDF generation |
| **docx** | DOCX generation |
| **Bcrypt** | Password hashing |
| **Nodemailer** | Email delivery |

---

## 13. CONFIGURATION FILES

| File | Purpose |
|------|---------|
| `.env` | Environment variables (JWT_SECRET, DB config, API keys) |
| `next.config.mjs` | Next.js configuration |
| `tailwind.config.js` | Tailwind CSS theme |
| `tsconfig.json` | TypeScript configuration |
| `eslint.config.mjs` | ESLint rules |
| `package.json` | Dependencies & scripts |
| `CLAUDE.md` | AI assistant instructions |
| `AGENTS.md` | Agent-specific rules (Next.js, TipTap) |