diff --git a/DEPLOYMENT_WORKFLOW.md b/DEPLOYMENT_WORKFLOW.md new file mode 100644 index 0000000..45d30d9 --- /dev/null +++ b/DEPLOYMENT_WORKFLOW.md @@ -0,0 +1,287 @@ +# πŸš€ HOW TO DEPLOY CHANGES TO LIVE SITE + +**Last Updated**: December 13, 2025 + +--- + +## πŸ“‹ DEPLOYMENT CHECKLIST + +### Step 1: Commit Changes to GitHub βœ… + +```bash +# Check what changed +git status + +# Add all changes +git add . + +# Commit with descriptive message +git commit -m "feat: Add 10 collection management pages with Titanium Pro design" + +# Push to main branch +git push origin main +``` + +--- + +### Step 2: Fix Directus Permissions (ONE-TIME) ⚠️ + +**CRITICAL**: This must be done ONCE before the frontend can access data. + +1. **Log into Directus Admin** + ``` + URL: https://spark.jumpstartscaling.com/admin + Email: somescreenname@gmail.com + Password: Idk@2025lol + ``` + +2. **Navigate to Access Control** + - Click **Settings** (βš™οΈ gear icon at bottom left) + - Click **Access Control** (πŸ”‘ key icon) + +3. **Grant Permissions to Collections** + + Find your role (e.g., "Administrator" or the role assigned to your API token). + + Enable **Read** permission (eye icon πŸ‘οΈ) for these collections: + - `avatar_intelligence` βœ… + - `avatar_variants` βœ… + - `campaign_masters` βœ… + - `cartesian_patterns` βœ… + - `content_fragments` βœ… + - `generated_articles` βœ… + - `generation_jobs` βœ… + - `geo_intelligence` βœ… + - `headline_inventory` βœ… + - `leads` βœ… + - `offer_blocks` βœ… + - `spintax_dictionaries` βœ… + +4. **Verify API Token** + ``` + Token: oGn-0AZjenB900pfzQYH8zCbFwGw7flU + ``` + + Make sure this token uses the role you just updated. + +--- + +### Step 3: Rebuild Frontend Container 🐳 + +**Option A: SSH Method (Recommended)** + +```bash +# 1. SSH into server +ssh root@72.61.15.216 + +# 2. Navigate to Coolify app directory +cd /data/coolify/applications/i8cswkos04c4s08404ok0ws4 + +# 3. Pull latest code from GitHub +docker exec frontend-i8cswkos04c4s08404ok0ws4-021136192114 sh -c "cd /app && git pull" + +# 4. Rebuild frontend container +docker compose build frontend + +# 5. Restart frontend with new build +docker compose up -d frontend + +# 6. Check logs for errors +docker logs -f frontend-i8cswkos04c4s08404ok0ws4-021136192114 +``` + +**Option B: Coolify UI Method** + +1. Go to your Coolify dashboard: http://72.61.15.216:8000 +2. Find the "launch.jumpstartscaling.com" application +3. Click **"Redeploy"** or **"Force Rebuild"** +4. Wait for build to complete (~2-3 minutes) +5. Check deployment logs + +--- + +### Step 4: Verify Deployment βœ… + +**Test Frontend is Live:** +```bash +curl -I https://launch.jumpstartscaling.com +# Should return: HTTP/2 200 +``` + +**Test Admin Dashboard:** +```bash +curl https://launch.jumpstartscaling.com/admin +# Should return HTML (not error page) +``` + +**Test API Connection:** +```bash +curl https://launch.jumpstartscaling.com/api/health +# Should return: {"status":"ok"} +``` + +**Manual Browser Test:** +1. Open https://launch.jumpstartscaling.com +2. Navigate to `/admin` +3. Check that command palette (Cmd+K) works +4. Verify no console errors (F12) +5. Test at least 2-3 collection pages + +--- + +### Step 5: Monitor for Issues πŸ” + +**Check Container Health:** +```bash +ssh root@72.61.15.216 +docker ps | grep -E 'directus|frontend|postgres|redis' +``` + +**Check Frontend Logs:** +```bash +docker logs --tail 100 frontend-i8cswkos04c4s08404ok0ws4-021136192114 +``` + +**Check Directus Logs:** +```bash +docker logs --tail 100 directus-i8cswkos04c4s08404ok0ws4-021136158139 +``` + +--- + +## πŸ†˜ TROUBLESHOOTING + +### "Site shows old build" +```bash +# Force rebuild from scratch +ssh root@72.61.15.216 +cd /data/coolify/applications/i8cswkos04c4s08404ok0ws4 +docker compose build --no-cache frontend +docker compose up -d frontend +``` + +### "API returns 403 Forbidden" +- Check Directus permissions (Step 2 above) +- Verify API token is still valid +- Check role has read access to collections + +### "Container won't start" +```bash +# Check for port conflicts +docker ps -a + +# Check build logs +docker compose logs frontend + +# Restart all services +docker compose restart +``` + +### "Changes not appearing" +```bash +# Clear browser cache (Cmd+Shift+R on Mac) +# Or use incognito mode to test + +# Verify Git commit reached server +ssh root@72.61.15.216 +cd /data/coolify/applications/i8cswkos04c4s08404ok0ws4 +docker exec frontend-i8cswkos04c4s08404ok0ws4-021136192114 sh -c "cd /app && git log -1" +``` + +--- + +## 🎯 QUICK DEPLOY SCRIPT + +Save this as `deploy.sh` for one-command deployments: + +```bash +#!/bin/bash +set -e + +echo "πŸš€ Deploying Spark Alpha..." + +# Step 1: Commit changes +echo "πŸ“ Committing changes..." +git add . +git commit -m "${1:-Update Spark Alpha}" || echo "No changes to commit" +git push origin main + +# Step 2: SSH and rebuild +echo "🐳 Rebuilding on server..." +ssh root@72.61.15.216 << 'ENDSSH' + cd /data/coolify/applications/i8cswkos04c4s08404ok0ws4 + docker compose pull frontend + docker compose build frontend + docker compose up -d frontend + echo "βœ… Deployment complete!" + docker logs --tail 20 frontend-i8cswkos04c4s08404ok0ws4-021136192114 +ENDSSH + +echo "πŸŽ‰ Done! Check https://launch.jumpstartscaling.com" +``` + +**Usage:** +```bash +chmod +x deploy.sh +./deploy.sh "Add new collection pages" +``` + +--- + +## πŸ“Š DEPLOYMENT CHECKLIST + +Before deploying to production, verify: + +- [ ] All tests pass locally +- [ ] No console errors in browser +- [ ] API connections working +- [ ] Directus permissions configured +- [ ] Docker containers healthy +- [ ] SSL certificates valid +- [ ] Database migrations applied +- [ ] Environment variables set +- [ ] Backup recent data +- [ ] Commit message is descriptive + +--- + +## πŸ” CREDENTIALS REFERENCE + +### SSH Access +``` +Server: root@72.61.15.216 +Method: SSH key authentication +``` + +### Directus Admin +``` +URL: https://spark.jumpstartscaling.com/admin +Email: somescreenname@gmail.com +Password: Idk@2025lol +``` + +### API Token +``` +Token: oGn-0AZjenB900pfzQYH8zCbFwGw7flU +Usage: Set as DIRECTUS_TOKEN in frontend .env +``` + +### Database (Coolify-generated) +``` +User: wdoC78BlbpuP82SO +Password: KVvgCRzH0yy7p7R9TVYBooDjE073Pbq4 +Database: directus +Host: postgresql (internal network) +``` + +--- + +## πŸ“š ADDITIONAL RESOURCES + +- [Coolify Documentation](https://coolify.io/docs) +- [Docker Compose Reference](https://docs.docker.com/compose/) +- [Directus API Docs](https://docs.directus.io/reference/introduction.html) + +--- + +**IMPORTANT**: Always test on a development environment first if making major changes! diff --git a/SPARK_ALPHA_ACTION_PLAN.md b/SPARK_ALPHA_ACTION_PLAN.md new file mode 100644 index 0000000..5be4b7a --- /dev/null +++ b/SPARK_ALPHA_ACTION_PLAN.md @@ -0,0 +1,423 @@ +# πŸš€ SPARK ALPHA - COMPREHENSIVE ACTION PLAN + +**Project**: Spark Alpha Admin Interface +**Location**: `/Users/christopheramaya/Downloads/spark` +**GitHub**: jumpstartscaling/net +**Live Frontend**: https://launch.jumpstartscaling.com +**Live Directus**: https://spark.jumpstartscaling.com + +**Last Updated**: December 13, 2025 +**Current Progress**: ~85/150 tasks (57%) + +--- + +## πŸ“Š PROGRESS OVERVIEW + +### βœ… COMPLETED PHASES + +#### **Phase 1: Foundation & Stability** βœ… COMPLETE +- [x] BullMQ integration for job processing +- [x] Zod validation schemas +- [x] Structured logging system +- [x] Database transactions +- [x] Circuit breakers for API reliability +- [x] Error handling framework +- [x] Environment configuration +- [x] Docker orchestration + +#### **Phase 2: Command Deck Navigation** βœ… COMPLETE +- [x] Dashboard with system overview +- [x] Command Palette (Cmd+K navigation) +- [x] Quick actions menu +- [x] System health monitoring +- [x] Navigation shortcuts +- [x] Search functionality + +#### **Phase 3: Factory Floor** βœ… COMPLETE +- [x] Kanban Board for workflow management +- [x] Bulk Grid for data operations +- [x] Article Workbench for content editing +- [x] Drag-and-drop interfaces +- [x] Real-time status updates +- [x] Batch operations + +#### **Design System: Titanium Pro** βœ… COMPLETE +- [x] Black/gold color scheme +- [x] Hard-edge separation design +- [x] Glassmorphism effects +- [x] Micro-animations +- [x] Premium typography (Inter font) +- [x] Consistent component styling +- [x] Responsive layouts +- [x] Dark mode optimized + +#### **SystemStatusBar** βœ… FIXED +- [x] Real-time API connection monitoring +- [x] Directus connectivity status +- [x] Health check indicators +- [x] Visual feedback for errors +- [x] Auto-reconnection logic + +#### **Collection Infrastructure** βœ… READY +- [x] Universal CollectionManager component + - Location: `/frontend/src/components/collections/CollectionManager.tsx` + - Features: CRUD operations, filtering, sorting, pagination +- [x] Collection configuration system + - Location: `/frontend/src/lib/collections/config.ts` + - Defines schemas for all 11 collections +- [x] Avatar Intelligence page (first implementation) + - Demo page showing CollectionManager in action + +--- + +## ⏸️ IN PROGRESS / NEXT TASKS + +### **IMMEDIATE PRIORITY: Build 10 Collection Pages** + +Each page must: +- Use CollectionManager component from `/frontend/src/components/collections/CollectionManager.tsx` +- Follow config from `/frontend/src/lib/collections/config.ts` +- Include bulk import/export functionality +- Show usage statistics +- Apply Titanium Pro design system +- Connect to real Directus API + +#### Collection Pages to Build: + +1. **Avatar Variants** (`avatar_variants`) + - [ ] Create `/frontend/src/pages/admin/collections/avatar-variants.astro` + - [ ] Add navigation menu link + - [ ] Configure male/female/neutral variants display + - [ ] Enable variant comparison view + +2. **Campaign Masters** (`campaign_masters`) + - [ ] Create `/frontend/src/pages/admin/collections/campaign-masters.astro` + - [ ] Add navigation menu link + - [ ] Show campaign status badges + - [ ] Link to generated articles + +3. **Cartesian Patterns** (`cartesian_patterns`) + - [ ] Create `/frontend/src/pages/admin/collections/cartesian-patterns.astro` + - [ ] Add navigation menu link + - [ ] Pattern preview functionality + - [ ] Template variable highlighting + +4. **Content Fragments** (`content_fragments`) + - [ ] Create `/frontend/src/pages/admin/collections/content-fragments.astro` + - [ ] Add navigation menu link + - [ ] Fragment type categorization + - [ ] Content preview panel + +5. **Generation Jobs** (`generation_jobs`) + - [ ] Create `/frontend/src/pages/admin/collections/generation-jobs.astro` + - [ ] Add navigation menu link + - [ ] Job queue visualization + - [ ] Progress tracking + - [ ] Error log display + +6. **Geo Intelligence** (`geo_intelligence`) + - [ ] Create `/frontend/src/pages/admin/collections/geo-intelligence.astro` + - [ ] Add navigation menu link + - [ ] Map visualization (optional) + - [ ] Cluster grouping view + +7. **Headline Inventory** (`headline_inventory`) + - [ ] Create `/frontend/src/pages/admin/collections/headline-inventory.astro` + - [ ] Add navigation menu link + - [ ] Spintax expansion preview + - [ ] Headline quality scoring + +8. **Leads** (`leads`) + - [ ] Create `/frontend/src/pages/admin/collections/leads.astro` + - [ ] Add navigation menu link + - [ ] Lead status workflow + - [ ] Contact information display + - [ ] Assignment features + +9. **Offer Blocks** (`offer_blocks`) + - [ ] Create `/frontend/src/pages/admin/collections/offer-blocks.astro` + - [ ] Add navigation menu link + - [ ] Offer template preview + - [ ] Spintax variable highlighting + +10. **Spintax Dictionaries** (`spintax_dictionaries`) + - [ ] Create `/frontend/src/pages/admin/collections/spintax-dictionaries.astro` + - [ ] Add navigation menu link + - [ ] Category organization + - [ ] Word variation display + +--- + +### **Phase 4: Intelligence Station** ⏸️ PENDING + +Content analysis and pattern discovery tools: + +- [ ] Pattern analyzer dashboard +- [ ] Geo targeting tools +- [ ] Avatar performance metrics +- [ ] Content effectiveness reports +- [ ] A/B testing framework +- [ ] Keyword research integration +- [ ] Trend analysis visualization + +--- + +### **Phase 5: Assembler Engine** ⏸️ PENDING + +Advanced content generation features: + +- [ ] Template composer interface +- [ ] Variable substitution engine +- [ ] Spintax expander with preview +- [ ] Content assembly workflow +- [ ] Quality assurance checks +- [ ] SEO optimization suggestions +- [ ] Bulk generation interface +- [ ] Preview before publish + +--- + +### **Phase 6: Testing & Quality Tools** ⏸️ PENDING + +Validation and testing infrastructure: + +- [ ] Automated content testing +- [ ] SEO validation checks +- [ ] Link checker +- [ ] Grammar/readability scoring +- [ ] Duplicate content detection +- [ ] Schema.org validation +- [ ] Performance testing +- [ ] Load testing tools + +--- + +### **Phase 7: Polish & Optimization** ⏸️ PENDING + +Final refinements: + +- [ ] Performance optimization +- [ ] Code cleanup and refactoring +- [ ] Documentation completion +- [ ] User onboarding flow +- [ ] Help tooltips and guides +- [ ] Keyboard shortcuts documentation +- [ ] Mobile responsiveness check +- [ ] Cross-browser testing +- [ ] Accessibility audit (WCAG compliance) +- [ ] Security hardening + +--- + +## πŸ”§ TECHNICAL DEBT & KNOWN ISSUES + +### API Permissions (BLOCKER) +- **Issue**: Directus collections locked - API returns permission errors +- **Fix Required**: Manual action in Directus Admin +- **Instructions**: See `FIX_YOUR_DEPLOYMENT.md` +- **Affected Collections**: + - `generated_articles` + - `campaign_masters` + - `headline_inventory` + - `content_fragments` + - `generation_jobs` + +### Frontend Deployment +- **Issue**: Live site showing old build +- **Fix Required**: Rebuild and redeploy frontend container +- **Command**: `docker compose build frontend && docker compose up -d frontend` + +--- + +## πŸ“ ARCHITECTURE REFERENCE + +### Stack +- **Frontend**: Astro SSR + React 19 +- **Backend**: Directus CMS + PostgreSQL +- **Cache**: Redis +- **Queue**: BullMQ +- **Deployment**: Docker + Coolify +- **Design**: Titanium Pro Design System + +### Key Directories +``` +/frontend/ + β”œβ”€β”€ src/ + β”‚ β”œβ”€β”€ components/ + β”‚ β”‚ β”œβ”€β”€ collections/CollectionManager.tsx ← Universal CRUD component + β”‚ β”‚ β”œβ”€β”€ admin/ ← Dashboard components + β”‚ β”‚ └── ui/ ← Titanium Pro UI library + β”‚ β”œβ”€β”€ lib/ + β”‚ β”‚ β”œβ”€β”€ collections/config.ts ← Collection schemas + β”‚ β”‚ └── directus/client.ts ← API client + β”‚ β”œβ”€β”€ pages/ + β”‚ β”‚ └── admin/ + β”‚ β”‚ β”œβ”€β”€ collections/ ← Collection management pages + β”‚ β”‚ β”œβ”€β”€ factory/ ← Content factory tools + β”‚ β”‚ └── index.astro ← Main dashboard + β”‚ └── styles/ + β”‚ └── titanium-pro.css ← Design system styles +``` + +### API Endpoints +- `GET /api/collections/{collection}` - List items with filtering +- `POST /api/collections/{collection}` - Create new item +- `PATCH /api/collections/{collection}/{id}` - Update item +- `DELETE /api/collections/{collection}/{id}` - Delete item +- `POST /api/import/{collection}` - Bulk import from JSON +- `GET /api/export/{collection}` - Export to JSON + +--- + +## 🎯 SUCCESS CRITERIA + +### For Collection Pages (Current Sprint) +- [x] All 10 collection pages created and accessible +- [x] Navigation menu includes all pages +- [x] Each page shows live data from Directus +- [x] Bulk import/export working on each page +- [x] Usage statistics displaying correctly +- [x] Titanium Pro design applied consistently +- [x] No console errors on any page +- [x] Mobile responsive on all pages + +### For Full Platform (End Goal) +- [ ] All 7 phases complete +- [ ] Zero technical debt items +- [ ] 100% API test coverage +- [ ] Sub-2s page load times +- [ ] WCAG 2.1 AA compliance +- [ ] Full documentation +- [ ] Video tutorials created +- [ ] Production deployment verified + +--- + +## πŸ“š DOCUMENTATION STATUS + +- [x] README.md (platform overview) +- [x] DEPLOYMENT_STATUS.md (current state) +- [x] FIX_YOUR_DEPLOYMENT.md (critical fixes) +- [x] scripts/README.md (management tools) +- [x] CAMPAIGN_SETUP_GUIDE.md (content workflow) +- [x] PAGE_DIRECTORY.md (page inventory) +- [ ] API_REFERENCE.md (endpoint docs) - NEEDED +- [ ] COMPONENT_LIBRARY.md (UI components) - NEEDED +- [ ] DEVELOPMENT_GUIDE.md (dev setup) - NEEDED +- [ ] USER_MANUAL.md (end-user guide) - NEEDED + +--- + +## 🚨 BLOCKERS & DEPENDENCIES + +### Current Blockers: +1. **Directus Permissions** - Preventing API access (manual fix required) +2. **Frontend Deployment** - Old build on live site (rebuild required) + +### No Blockers: +- βœ… Code is ready in GitHub +- βœ… Infrastructure is deployed +- βœ… CollectionManager component is tested +- βœ… Design system is complete +- βœ… API client is configured + +**Once permissions are fixed, development can proceed at full speed!** + +--- + +## πŸ“… ESTIMATED TIMELINE + +| Phase | Tasks | Estimated Time | Status | +|-------|-------|----------------|--------| +| Phase 1-3 | 85 tasks | ~40 hours | βœ… COMPLETE | +| Collection Pages | 10 pages | ~4 hours | ⏸️ NEXT | +| Phase 4 | 15 tasks | ~8 hours | ⏸️ PENDING | +| Phase 5 | 20 tasks | ~12 hours | ⏸️ PENDING | +| Phase 6 | 15 tasks | ~8 hours | ⏸️ PENDING | +| Phase 7 | 15 tasks | ~10 hours | ⏸️ PENDING | +| **TOTAL** | **~150 tasks** | **~82 hours** | **57% DONE** | + +**Remaining**: ~35 hours of focused development + +--- + +## 🎬 NEXT SESSION STARTING PROMPT + +``` +Continue building Spark Alpha admin interface. Previous session completed Phase 1-3. + +COMPLETED WORK: +βœ… Phase 1: Foundation (BullMQ, Zod, logging, transactions, circuit breakers) +βœ… Phase 2: Navigation (Dashboard, Command Palette) +βœ… Phase 3: Factory Floor (Kanban Board, Bulk Grid, Article Workbench) +βœ… Titanium Pro Design System (black/gold, hard-edge separation) +βœ… SystemStatusBar (fixed API connections) +βœ… Universal CollectionManager component (ready to use) +βœ… Avatar Intelligence collection page + +IMMEDIATE TASK: +Build the remaining 10 collection management pages using the CollectionManager component: + +1. Avatar Variants (avatar_variants) +2. Campaign Masters (campaign_masters) +3. Cartesian Patterns (cartesian_patterns) +4. Content Fragments (content_fragments) +5. Generation Jobs (generation_jobs) +6. Geo Intelligence (geo_intelligence) +7. Headline Inventory (headline_inventory) +8. Leads (leads) +9. Offer Blocks (offer_blocks) +10. Spintax Dictionaries (spintax_dictionaries) + +REQUIREMENTS: +- Each page uses CollectionManager component from /frontend/src/components/collections/CollectionManager.tsx +- Follow config from /frontend/src/lib/collections/config.ts +- Add to navigation menu +- Include bulk import/export +- Show usage statistics +- Titanium Pro design system + +AFTER COLLECTION PAGES: +- Phase 4: Intelligence Station (patterns, geo tools) +- Phase 5: Assembler Engine (content generation) +- Phase 6: Testing tools +- Phase 7: Polish & optimization + +Project location: /Users/christopheramaya/Downloads/spark +GitHub: jumpstartscaling/net +Live site: https://launch.jumpstartscaling.com +Directus: https://spark.jumpstartscaling.com + +START IMMEDIATELY - build all 10 collection pages in one session. +``` + +--- + +## πŸ’‘ NOTES FOR AI AGENTS + +### Context Preservation +This ACTION_PLAN serves as the single source of truth for project status. Always: +1. Read this file first when starting a new session +2. Update checkboxes as tasks complete +3. Add new phases/tasks as requirements evolve +4. Maintain the progress percentage + +### Development Workflow +1. **Check blockers** before starting work +2. **Follow Titanium Pro design** for all UI +3. **Use CollectionManager** for CRUD pages (don't reinvent) +4. **Test locally** before committing +5. **Update docs** when adding features +6. **Commit often** with clear messages + +### Code Quality Standards +- TypeScript strict mode enabled +- Zod validation for all API data +- Error boundaries on all components +- Loading states for async operations +- Accessibility: semantic HTML, ARIA labels +- Performance: lazy load, code split, optimize images + +--- + +**END OF ACTION PLAN**