docs: add OpenCode project memory for git workflow

2026-04-03 21:06:15 +02:00
parent cbbcaace22
commit 6caefb420a
1 changed files with 189 additions and 0 deletions
--- a/.opencode/PROJECT_MEMORY.md
+++ b/.opencode/PROJECT_MEMORY.md
@@ -0,0 +1,189 @@
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+npm run dev          # Start dev server
+npm run build        # Production build
+npm run test         # Run tests
+```
+
+### Kubernetes (doorwaysftw server)
+```bash
+# 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