manoon-headless/.opencode/PROJECT_MEMORY.md

ManoonOils Project Memory

Project Overview

• Name: ManoonOils Headless Storefront
• Type: Next.js 16 + Saleor e-commerce
• URL: https://manoonoils.com
• Tech Stack: React 19, TypeScript, Tailwind CSS v4, GraphQL/Apollo

Git Workflow (CRITICAL)

feature/* → dev → master

Rules (MUST FOLLOW)

1. All work starts on feature branch - Never commit to dev/master directly
2. Commit working code immediately - No uncommitted files in working directory
3. Clean working directory before switching branches - Run git status first
4. Flow forward only - feature → dev → master, never skip
5. Reset feature branches after merge - Keep synchronized with master

Workflow Steps

# 1. Create feature branch
git checkout -b feature/description

# 2. Work and commit WORKING code
git add .
git commit -m "type: description"
git push origin feature/description

# 3. Merge to dev for testing
git checkout dev
git merge feature/description
git push origin dev

# 4. Merge to master for production
git checkout master
git merge dev
git push origin master

# 5. Reset feature branch to match master
git checkout feature/description
git reset --hard master
git push origin feature/description --force

Commit Types

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• style: - Formatting
• refactor: - Code restructuring
• test: - Tests
• chore: - Build/process

Project Structure

Key Directories

src/
├── app/[locale]/          # i18n routes
├── components/
│   ├── home/              # Homepage sections
│   ├── layout/            # Header, Footer
│   ├── providers/         # Context providers
│   └── ui/                # Reusable UI
├── hooks/                 # Custom hooks
├── lib/
│   ├── mautic.ts         # Mautic API client
│   ├── geoip.ts          # GeoIP service
│   └── analytics.ts      # Analytics tracking
├── i18n/messages/        # Translations (sr, en, de, fr)
k8s/                      # Kubernetes manifests

Important Files

• k8s/deployment.yaml - Production deployment config
• src/app/[locale]/layout.tsx - Root layout with ExitIntentDetector
• src/lib/mautic.ts - Mautic integration
• .env.local - Environment variables

Environment Variables

Required for Production

# Saleor
NEXT_PUBLIC_SALEOR_API_URL=https://api.manoonoils.com/graphql/

# Mautic
MAUTIC_CLIENT_ID=2_23cgmaqef8kgg8oo4kggc0w4wccwoss8o8w48o8sc40cowgkkg
MAUTIC_CLIENT_SECRET=4k8367ab306co48c4c8g8sco8cgcwwww044gwccs0o0c8w4gco
MAUTIC_API_URL=https://mautic.nodecrew.me

# Analytics
NEXT_PUBLIC_RYBBIT_HOST=https://rybbit.nodecrew.me
NEXT_PUBLIC_RYBBIT_SITE_ID=1
RYBBIT_API_KEY=...

# Email
RESEND_API_KEY=...

Current Features

Email Capture Popup

• Location: src/components/home/EmailCapturePopup.tsx
• Trigger: src/components/home/ExitIntentDetector.tsx
• Triggers: Scroll 10% OR exit intent (mouse leaving viewport)
• Delay: Scroll has 5s delay, exit intent shows immediately
• Fields: First name (optional), Email (required)
• Tracking: UTM params, device info, time on page, referrer
• Integration: Creates contact in Mautic with tags

API Routes

• /api/email-capture - Handles form submission to Mautic
• /api/geoip - Returns country/region from IP

i18n Support

• Locales: sr (default), en, de, fr
• Translation files: src/i18n/messages/*.json

Common Commands

Development

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests

Kubernetes (doorwaysftw server)

# Check pods
ssh doorwaysftw "kubectl get pods -n manoonoils"

# Restart storefront
ssh doorwaysftw "kubectl delete pod -n manoonoils -l app=storefront"

# Check logs
ssh doorwaysftw "kubectl logs -n manoonoils deployment/storefront"

# Verify env vars
ssh doorwaysftw "kubectl exec -n manoonoils deployment/storefront -- env | grep MAUTIC"

Known Issues & Solutions

Hydration Errors

• Cause: AnalyticsProvider returning null
• Solution: Return <></> instead, or remove component

Popup Not Showing

• Check ExitIntentDetector is in layout.tsx
• Verify useVisitorStore isn't showing popup already shown
• Check browser console for errors

Mautic API Failures

• Verify env vars in k8s deployment
• Check Mautic credentials haven't expired
• Ensure country code isn't "Local" (use "XX" instead)

Deployment Checklist

Before deploying to production:

• All tests pass (npm run test)
• Build succeeds (npm run build)
• No uncommitted changes (git status)
• Merged to dev and tested
• Merged to master
• K8s deployment.yaml has correct env vars
• Pod restarted to pick up new code
• Smoke test on production URL

Architecture Decisions

Why No AnalyticsProvider?

Removed because it returns null causing hydration mismatches. Analytics scripts loaded directly in layout.

Why Direct Rybbit URL?

Using https://rybbit.nodecrew.me/api/script.js instead of /api/script.js preserves real visitor IP.

Why Exit Intent + Scroll?

Exit intent catches leaving users immediately. Scroll trigger catches engaged users after delay.

Contact

• Maintainer: User
• K8s Server: doorwaysftw (100.109.29.45)
• Mautic: https://mautic.nodecrew.me