God Mode - Technical Stack & CTO Log

🏗 Technical Architecture

Core Stack

Framework: Astro 4.0 (Server-Side Rendering mode)
Runtime: Node.js 20+
Language: TypeScript
Styling: TailwindCSS with custom "God Mode" palette

Backend & Data

Database: PostgreSQL 16 (on Coolify)
ORM: Native pg queries (raw SQL for performance) + Custom Migration scripts
Queue: BullMQ (Redis-backed) for async content generation
Caching: Redis (shared with queue)

The "Directus Shim" - Critical Innovation

Problem: Standard CMS (Directus) is too slow for high-volume operations.
Solution: Custom shim layer that mimics Directus SDK but queries PostgreSQL directly.

How It Works:

All admin components import getDirectusClient() from src/lib/directus/client.ts
They use familiar Directus SDK syntax: readItems('sites', { filter: {...} })
The shim translates this to raw SQL: SELECT * FROM "sites" WHERE ...
Server-side: Direct PostgreSQL connection via pg pool (fast)
Client-side: HTTP proxy to /api/god/proxy → then PostgreSQL (secure)

Benefits:

✅ No Directus runtime dependency
✅ 10x faster queries (no API overhead)
✅ Developer-friendly syntax (not raw SQL everywhere)
✅ Can swap to real Directus later if needed

Files: src/lib/directus/client.ts (274 lines), src/pages/api/god/proxy.ts, src/lib/db.ts

Content Engine

Spintax: Custom recursive resolver ({A|B|{C|D}} support)
Variables: Handlebars-style expansion ({{CITY}})
Uniqueness: SHA-256 hashing of variation paths to prevent duplicates

📔 CTO Log & Decision Record

2025-12-15: The "God Mode" Pivot

Decision: Shifted from standard CMS to "God Mode" - a high-throughput, automated content engine. Rationale: The previous "Spark" manually managed content was too slow. We need to generate thousands of local SEO pages programmatically. Implementation:

Built SpintaxResolver to deterministically generate content.
Created variation_registry to ensure we never publish the same article twice (Google Duplicate Content penalty prevention).
Implemented BullMQ to handle the heavy processing load off the main web thread.

2025-12-15: Architecture Standardization

Decision: Enforce strict folder structure for Admin UI. Rationale: The admin panel grew to 70+ pages. Direct file-based routing in src/pages/admin mirrored by src/api ensures maintainability. Standards:

All lists must use the standard StatCard and Table components.
All pages must have inline <DevStatus> if they aren't fully wired up.

2025-12-15: Production Readiness

Decision: Multi-stage Docker build. Rationale: Build times were increasing. We separated dependencies installation from the build process in Dockerfile to leverage layer caching. Strategy:

We commit package-lock.json strictly.
We run linting before build in CI.

🛠 Feature Roadmap

Phase 8 (Next)

Connect sites table to Admin UI.
Implement campaign_masters fetch logic.
Wire up the generation_jobs queue monitor.

Future

Vector Database: Add pgvector for semantic search of content fragments.
LLM Integration: Add OpenAI/Anthropic step to contentGenerator worker for non-spintax dynamic writing.
Multi-Tenant: Allow multiple users to have their own "God Mode" instances (requires tenant_id schema update).

3.4 KiB Raw Blame History