Spark Platform: Zero-to-One Onboarding Guide

Current State: Phase 8 Complete (Premium Features Active) Last Updated: 2025-12-13

1. Project Overview

Spark is a high-performance content scaling platform ("Titanium Pro" edition). It leverages Directus (CMS/Data) and Astro/React (Frontend) to deliver enterprise-grade mass content generation.

2. Key Architecture

Frontend: Astro (SSR) + React (Interactive Islands).
Backend: Directus Headless CMS (Postgres).
Styling: TailwindCSS (Titanium Pro Design System: Dark Mode, Glassmorphism, Neon Accents).
Deployment: Coolify (Dockerized).

3. Core Modules (Implemented)

🏭 Factory Floor (`/admin/content/factory`)

The bread and butter of the operation.

Components: KanbanBoard, BulkGrid.
Purpose: Manage the lifecycle of thousands of articles.

🧠 Intelligence Station (`/admin/intelligence`)

Data-driven insights engine.

Geospatial Map (/geo-targeting): visualize market dominance with heatmaps using Leaflet.
Trend Analysis: Analyze keyword volatility.
Avatar Metrics: Track performance by user persona.

🧩 Assembler Engine (`/admin/assembler`)

The heart of content generation.

Template Composer: 3-pane editor for Spintax templates.
Automation Builder (/automations/workflow): [NEW] Visual Node-based editor (React Flow) to design content pipelines (Trigger -> Generate -> Publish).

📊 Command Center (`/admin/analytics`)

Metrics Dashboard (/metrics): [NEW] Professional Tremor-based analytics (Area Charts, Donut Charts) tracking traffic and engagement.

🛡️ Testing Suite (`/admin/testing`)

Visual Editor (/blocks/editor): Drag-and-drop page builder (Craft.js).
SEO/Readability: Real-time content scoring (Flesch-Kincaid).

4. Development Standards

"Titanium Pro" Design Rules

Colors: Background #09090b (Zinc-950), Accents #eab308 (Yellow-500) and #22c55e (Green-500).
Components: Always use Shadcn/UI (/components/ui/*.tsx).
Icons: Lucide React (<Edit className="h-4 w-4" />).
Animations: Use framer-motion for complex interactions, or CSS transitions for hover states.

Code Quality

Typescript: Strict mode. No any unless absolutely necessary (and temporarily).
Linting: Run npm run lint before committing.
Testing: Use the internal /admin/testing/suite to validate logic changes.

5. Deployment Workflow

Commit: git push triggers Coolify build.
Build Process: Dockerfile builds frontend (SSR).
Validation: Check https://launch.jumpstartscaling.com for the live site.
Staging: Use the "Preview" button in CollectionManager to vie draft content at https://launch.jumpstartscaling.com/site/[id]/preview/[post_id].

6. Next Actions (Phase 7: Polish)

The logic is done. The next phase is strictly Polish:

Accessibility Audit: Ensure ARIA labels on all new UI.
Documentation: Expand inline JSDoc for complex engines (engine.ts).
Performance: Optimize React Flow rendering for large graphs.

Note to AI Agent: You are working on a codebase that is feature-complete for Alpha. Your goal is stability and refinement. Do not refactor core engines without explicit instruction.

3.3 KiB Raw Blame History