190 lines
5.3 KiB
Markdown
190 lines
5.3 KiB
Markdown
# 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
|