net/PROJECT_SCAFFOLDING.md

🏗️ SPARK ALPHA - COMPLETE PROJECT SCAFFOLDING

Created: December 13, 2025
Status: Structure Ready, Implementation Pending
Progress: 61% (100/165 tasks)

---

✅ DEPENDENCIES INSTALLED

Core Libraries (Already Installed)

• @craftjs/core - Visual page builder
• react v19 - UI framework
• @directus/sdk - Backend API
• astro - SSR framework

New Libraries Installed (This Session)

{
  "recharts": "Charts and data visualization",
  "@tanstack/react-table": "Advanced tables with sorting/filtering",
  "@tanstack/react-query": "Server state management",
  "framer-motion": "Animations and transitions",
  "date-fns": "Date formatting and manipulation",
  "react-hot-toast": "Toast notifications",
  "zustand": "Lightweight state management",
  "immer": "Immutable state updates",
  "lodash-es": "Utility functions",
  "react-markdown": "Markdown rendering",
  "remark-gfm": "GitHub-flavored markdown",
  "react-syntax-highlighter": "Code highlighting",
  "react-dropzone": "File uploads",
  "papaparse": "CSV parsing",
  "pdfmake": "PDF generation",
  "html-to-image": "Screenshot/export functionality"
}

---

📁 COMPLETE FOLDER STRUCTURE

frontend/src/
├── components/
│   ├── admin/             ✅ COMPLETE (Dashboard, SystemStatus, etc.)
│   ├── analytics/         🆕 CREATED (Phase 4-6)
│   ├── assembler/         🆕 CREATED (Phase 5)
│   ├── blocks/            ✅ EXISTS (Page builder blocks)
│   ├── collections/       ✅ COMPLETE (CollectionManager)
│   ├── factory/           ✅ COMPLETE (Kanban, Grid, Workbench)
│   ├── intelligence/      🆕 CREATED (Phase 4)
│   ├── layout/            ✅ COMPLETE (AdminLayout)
│   ├── testing/           🆕 CREATED (Phase 6)
│   └── ui/                ✅ COMPLETE (Titanium Pro components)
│
├── pages/
│   ├── admin/
│   │   ├── analytics/     🆕 CREATED (Reports, dashboards)
│   │   ├── assembler/     🆕 CREATED (Content generation)
│   │   ├── collections/   ✅ COMPLETE (10 collection pages)
│   │   ├── content/       ✅ EXISTS
│   │   ├── factory/       ✅ COMPLETE
│   │   ├── intelligence/  🆕 CREATED (Pattern analysis)
│   │   ├── leads/         ✅ COMPLETE  
│   │   ├── media/         ✅ EXISTS
│   │   ├── pages/         ✅ EXISTS
│   │   ├── posts/         ✅ EXISTS
│   │   ├── seo/           ✅ EXISTS
│   │   ├── sites/         ✅ EXISTS
│   │   ├── testing/       🆕 CREATED (QA tools)
│   │   └── index.astro    ✅ COMPLETE
│   │
│   └── api/
│       ├── analytics/     🆕 CREATED (Analytics endpoints)
│       ├── assembler/     🆕 CREATED (Generation endpoints)
│       ├──collections/    ✅ EXISTS
│       ├── intelligence/  🆕 CREATED (Pattern endpoints)
│       ├── pages/         🆕 CREATED (Block editor endpoints)
│       └── testing/       🆕 CREATED (Validation endpoints)
│
├── lib/
│   ├── analytics/         🆕 CREATED (Analytics utilities)
│   ├── assembler/         🆕 CREATED (Content assembly)
│   ├── collections/       ✅ COMPLETE (Config)
│   ├── directus/          ✅ COMPLETE (API client)
│   ├── testing/           🆕 CREATED (Validators)
│   └── variables/         🆕 CREATED (Template variables)
│
├── hooks/                 🆕 CREATED (Custom React hooks)
├── store/                 🆕 CREATED (Zustand stores)
└── styles/                ✅ COMPLETE (Titanium Pro CSS)

---

📋 FILES TO CREATE (Phases 4-8)

Phase 4: Intelligence Station (15 files)

Components

components/intelligence/
├── PatternAnalyzer.tsx        # Pattern discovery dashboard
├── GeoTargeting.tsx           # Location targeting tools
├── AvatarMetrics.tsx          # Avatar performance charts
├── ContentEffectiveness.tsx   # Content ROI analysis
├── TrendChart.tsx             # Trend visualization
└── KeywordResearch.tsx        # SEO keyword tools

Pages

pages/admin/intelligence/
├── index.astro                # Intelligence dashboard
├── patterns.astro             # Pattern analysis
├── geo-targeting.astro      # Geo tools
├── avatar-metrics.astro       # Avatar performance
└── reports.astro              # Analytics reports

API

pages/api/intelligence/
├── patterns.ts                # GET/POST patterns
├── metrics.ts                 # GET avatar metrics
├── geo-performance.ts         # GET geo data
└── trends.ts                  # GET trend analysis

---

Phase 5: Assembler Engine (18 files)

Components

components/assembler/
├── TemplateComposer.tsx       # Visual template builder
├── VariableSubstitution.tsx   # {{var}} replacement UI
├── SpintaxExpander.tsx        # Spintax preview/expand
├── ContentAssembly.tsx        # Assembly workflow
├── QualityChecker.tsx         # Content QA
├── SEOOptimizer.tsx           # SEO suggestions
├── BulkGenerator.tsx          # Bulk generation UI
└── PreviewPanel.tsx           # Live preview

Pages

pages/admin/assembler/
├── index.astro                # Assembler dashboard
├── composer.astro             # Template composer
├── bulk-generate.astro        # Bulk generation
└── quality-check.astro        # QA dashboard

API

pages/api/assembler/
├── generate.ts                # POST generate content
├── expand-spintax.ts          # POST expand spintax
├── substitute-vars.ts         # POST variable sub
└── quality-check.ts           # POST quality check

Lib

lib/assembler/
├── spintax.ts                 # Spintax expansion logic
├── variables.ts               # Variable substitution
├── quality.ts                 # Quality scoring
└── seo.ts                     # SEO optimization

---

Phase 6: Testing & Quality (12 files)

Components

components/testing/
├── ContentTester.tsx          # Automated testing UI
├── SEOValidator.tsx           # SEO validation
├── LinkChecker.tsx            # Broken link checker
├── GrammarCheck.tsx           # Grammar/readability
├── DuplicateDetector.tsx      # Duplicate content
└── SchemaValidator.tsx        # Schema.org validator

Pages

pages/admin/testing/
├── index.astro                # Testing dashboard
├── seo-validation.astro       # SEO tests
├── content-quality.astro      # Quality tests
└── link-checker.astro         # Link validation

API

pages/api/testing/
├── validate-seo.ts            # POST SEO validation
├── check-links.ts             # POST link check
└── detect-duplicates.ts       # POST duplicate check

---

Phase 7: Polish & Optimization (8 files)

Components

components/analytics/
├── PerformanceDashboard.tsx   # Performance metrics
├── UsageStats.tsx             # Usage statistics
└── ErrorTracker.tsx           # Error monitoring

Pages

pages/admin/analytics/
├── index.astro                # Analytics dashboard
├── performance.astro          # Performance metrics
└── errors.astro               # Error logs

Lib

lib/analytics/
├── tracking.ts                # Event tracking
└── metrics.ts                 # Metric collection

---

Phase 8: Visual Block Editor (12 files)

Block Components

components/blocks/
├── HeroBlock.tsx              # Hero section
├── FeaturesBlock.tsx          # Features grid
├── FAQBlock.tsx               # FAQ accordion
├── RichTextBlock.tsx          # Rich text
├── ImageBlock.tsx             # Image block
├── CTABlock.tsx               # Call-to-action
├── TestimonialBlock.tsx       # Testimonial
├── PricingBlock.tsx           # Pricing table
├── StatsBlock.tsx             # Statistics
└── OfferBlock.tsx             # Offer block

Editor Components

components/factory/
├── BlockEditor.tsx            # Main editor
├── Toolbox.tsx                # Block toolbox
├── SettingsPanel.tsx          # Block settings
└── PageRenderer.tsx           # Frontend renderer

API

pages/api/pages/
├── [id]/
│   └── blocks.ts              # GET/POST/DELETE blocks

Lib

lib/variables/
├── interpolation.ts           # Variable replacement
├── context.ts                 # Context builder
└── templates.ts               # Template definitions

---

🎯 CUSTOM HOOKS TO CREATE

// hooks/
useDirectus.ts                 # Directus API hook
useCollections.ts              # Collection CRUD hook
usePatternAnalysis.ts          # Pattern analysis
useContentAssembly.ts          # Content generation
useSEOValidation.ts            # SEO validation
useBlockEditor.ts              # Block editor state
useVariableContext.ts          # Template variables
useAnalytics.ts                # Analytics tracking

---

🗄️ ZUSTAND STORES TO CREATE

// store/
editorStore.ts                 # Block editor state
assemblerStore.ts              # Content assembly state
patternsStore.ts               # Pattern analysis state
metricsStore.ts                # Analytics metrics state

---

📊 PROGRESS TRACKER

Category	Total Files	Created	Remaining
Components	45	25	20
Pages	30	20	10
API Endpoints	20	5	15
Lib/Utils	15	5	10
Hooks	8	0	8
Stores	4	0	4
TOTAL	122	55	67

File Creation Progress: 45% (55/122 files)

---

🚀 NEXT STEPS

1. ✅ Dependencies installed
2. ✅ Folder structure created
3. ⏸️ Create skeleton files with type definitions
4. ⏸️ Implement Phase 4 (Intelligence Station)
5. ⏸️ Implement Phase 5 (Assembler Engine)
6. ⏸️ Implement Phase 6 (Testing & Quality)
7. ⏸️ Implement Phase 7 (Polish & Optimization)
8. ⏸️ Implement Phase 8 (Visual Block Editor)

---

💡 IMPLEMENTATION STRATEGY

For Each Phase:

1. Create component skeletons with TypeScript interfaces
2. Build out API endpoints
3. Implement lib/utility functions
4. Wire components to APIs
5. Create pages
6. Test and iterate
7. Update documentation

Estimated Timeline:

• Phase 4: ~8 hours
• Phase 5: ~12 hours
• Phase 6: ~8 hours
• Phase 7: ~10 hours
• Phase 8: ~6 hours

Total Remaining: ~44 hours of development

---

Ready to start implementing! All dependencies and structure in place. 🚀