# Spark Platform: AI Agent Onboarding Guide

> **Current State**: 🚀 LAUNCH READY (All 4 Milestones Complete)  
> **Last Updated**: 2025-12-13  
> **Priority**: Live Verification, Performance Monitoring, and Marketing

---

## 1. Project Overview

Spark is a high-performance content scaling platform. It leverages:
- **Directus** (Headless CMS + PostgreSQL) for data
- **Astro + React** (SSR + Islands) for frontend
- **Frontend Engine**: Universal Render Engine for Landers, Hubs, and Articles
- **Queue System** (BullMQ + Redis) for background processing

**Goal**: Generate and manage millions of SEO-optimized articles at scale.

---

## 2. Architecture

### Frontend (`/frontend`)
- **Framework**: Astro 4.7 (SSR)
- **UI**: React 18.3 (Interactive Islands)
- **Styling**: Tailwind CSS (Titanium Pro Design)
- **Engine**: `[...slug].astro` + `BlockRenderer.tsx`
- **Build**: Vite

### Backend (`/backend`)
- **CMS**: Directus 11
- **Database**: PostgreSQL 16 (PostGIS)
- **Cache**: Redis 7
- **Queue**: BullMQ

### Deployment
- **Platform**: Coolify (Docker Compose)
- **Frontend**: `launch.jumpstartscaling.com`
- **Backend**: `spark.jumpstartscaling.com`

---

## 3. Current Features (Working)

### ✅ Intelligence Library (Fully Interactive)
**Location**: `/admin/intelligence/*` and `/admin/collections/*`
**Status**: ✅ Full CRUD + Stats + Visual Dashboards

**Collections**:
1. **Avatar Intelligence**: Manager, Stats, Variant Generator
2. **Avatar Variants**: Grouped View, DNA Style UI
3. **Geo Intelligence**: Interactive Map (Leaflet), Clusters, City Stats
4. **Spintax Dictionaries**: Manager, Live Preview, Import/Export
5. **Cartesian Patterns**: Formula Builder, Dynamic Preview

### ✅ Content Factory (Kanban & Automation)
**Location**: `/admin/factory/*`
**Status**: ✅ Full Pipeline Operational

**Components**:
- **Kanban Board**: Drag-and-drop workflow (Queued -> Published)
- **Jobs Queue**: Real-time progress monitoring
- **Scheduler**: Calendar view for campaigns
- **Leads Manager**: CRM with status workflow
- **Send to Factory**: One-click generation from WordPress

### ✅ Launchpad (Site Builder)
**Location**: `/admin/sites/*`
**Status**: ✅ Fully Functional

**Components**:
- **Site Manager**: Multi-site support
- **Page Editor**: Visual Block Editor (Hero, Content, Features)
- **Navigation Editor**: Drag-and-drop menu builder
- **Theme Settings**: Global styles and logos

### ✅ Frontend Engine
**Location**: Public URL / Preview
**Status**: ✅ Rendering Live Content

**Features**:
- **Universal Router**: Handles Sites, Pages, and Articles
- **Block Renderer**: Renders JSON blocks to UI
- **Dynamic SEO**: Auto-generates meta tags
- **Preview Mode**: 1:1 match with production

---

## 4. Completed Roadmap

See **IMPLEMENTATION_ROADMAP.md** for history.

- ✅ **Milestone 1**: Intelligence Library (Completed)
- ✅ **Milestone 2**: Factory & Forms (Completed)
- ✅ **Milestone 3**: All Collections (Completed)
- ✅ **Milestone 4**: Launchpad Site Builder (Completed)

---

## 5. Development Standards

### Titanium Pro Design System

**Colors**:
- Background: `#09090b` (Zinc-950)
- Accents: `#eab308` (Yellow-500), `#22c55e` (Green-500), `#a855f7` (Purple-500)
- Text: White/Slate

**Components**:
- Always use Shadcn/UI components (`/components/ui/*.tsx`)
- Icons: Lucide React
- Animations: Framer Motion (admin), CSS (public)

---

## 6. Key Files & Locations

### Intelligence Library
```
frontend/src/components/admin/intelligence/
├── AvatarIntelligenceManager.tsx (Built)
├── GeoIntelligenceManager.tsx (Built)
├── SpintaxManager.tsx (Built)
└── CartesianManager.tsx (Built)
```

### Factory & Forms
```
frontend/src/components/admin/factory/
├── KanbanBoard.tsx (Built)
├── SendToFactoryButton.tsx (Built)
```

### Frontend Engine
```
frontend/src/
├── pages/[...slug].astro (The Router)
└── components/engine/BlockRenderer.tsx (The Renderer)
```

### API Endpoints
```
frontend/src/pages/api/
├── factory/send-to-factory.ts (Working)
├── seo/generate-article.ts (Working)
```

---

## 7. Development Workflow

### Local Development
```bash
cd /Users/christopheramaya/Downloads/spark/frontend
npm run dev
# Access at http://localhost:4321
```

### Deployment
```bash
git add .
git commit -m "feat: Description of changes"
git push origin main
# Coolify auto-deploys in ~2 minutes
```

---

## 8. Troubleshooting Tools

### React Query Devtools
**Access**: Bottom-right corner of admin pages

### Vite Inspector
**Access**: `http://localhost:4321/__inspect/`

### Deployment Verification
See `DEPLOYMENT_VERIFICATION.md`

---

## 9. Next Actions (Post-Launch)

### Immediate Focus:
1. **User Verification**: Ensure all flows work in production.
2. **Content Strategy**: Build templates and patterns.
3. **Marketing**: Launch the platform to users.

---

## 10. Important Notes

### For AI Agents:
- **Project Status**: Stable & Complete.
- **Future Work**: Features requests, bug fixes, performance tuning.
- **Documentation**: Use this file and `DEPLOYMENT_VERIFICATION.md` as source of truth.

### For Humans:
- **Access Admin**: `https://launch.jumpstartscaling.com/admin`
- **Access Directus**: `https://spark.jumpstartscaling.com`
- **Frontend**: `https://launch.jumpstartscaling.com`

**Current Status**: 🚀 OPERATIONAL
**Next Milestone**: 📈 Scale & Growth

🚀 **Ready to Scale!**