Brancheneinstufung2/content-engine

Content Engine (v1.0 - MVP)

Status: Live / MVP Implemented Date: Jan 20, 2026 URL: /content/

1. Vision & Purpose

The Content Engine acts as the execution arm ("The Mouth") for the strategies developed in the GTM Architect ("The Brain"). It is a Content Generation Dashboard designed to produce high-quality, SEO-optimized, and sales-ready marketing assets based on the strategic foundation of the GTM Architect.

Core Philosophy:

• SEO First: Keywords guide the structure, not just metadata.
• Human-in-the-Loop: Every generated asset is a draft that invites manual refinement.
• Context-Aware: It inherits deep strategic knowledge (ICPs, Pain Points, Hybrid Service Logic) from the GTM Architect database.
• Tone: Professional, fact-based, compelling, and "slightly aggressive" (Challenger Sale).

2. Architecture & Tech Stack

Data Layer

• Persistence: A dedicated SQLite database (content_engine.db) stores all content projects, SEO strategies, and drafts.
• Integration: Read-only access to gtm_projects.db via Docker volume mounts to import strategy baselines.

The Stack

• Frontend: React (Vite + TypeScript + Tailwind CSS).
• Backend: Node.js Bridge (server.cjs, Express) communicating with a Python Orchestrator (content_orchestrator.py).
• Container: Dockerized service (content-app), integrated into the central Nginx Gateway.

3. Implemented Features (MVP)

3.1. Phase 1: Project Setup & Import

• GTM Bridge: Lists and imports strategies directly from GTM Architect.
• Context Loading: Automatically extracts Product Category, ICPs, and Core Value Propositions.

3.2. Phase 2: SEO Strategy

• AI Brainstorming: Generates 15 strategic Seed Keywords (Short & Long Tail) based on the imported strategy.
• Keyword Selection: User can select primary/secondary keywords (Planned).
• Persistence: Saves the generated SEO strategy (all keywords) to the database.

3.3. Phase 3: Website Copy Generator

• Section Generator: Generates structured copy for:
  • Hero Section (Headline, Subline, CTA)
  • Challenger Story (Problem/Agitation)
  • Value Proposition (Hybrid Solution Logic)
  • Feature-to-Value (Tech Deep Dive)
• Editor UI: Integrated Markdown editor for manual refinement.
• Human-in-the-Loop: "Re-Generate" (AI) and "Save Changes" (Manual) functionality.
• Content Persistence: Generated/edited content for sections persists across tab changes/reloads.
• Copy-to-Clipboard: Quick export for deployment.

4. Logging & Observability

To ensure full transparency and debuggability, comprehensive logging has been implemented:

• Node.js Server Logs: /app/Log_from_docker/content_node_server.log (INFO, ERROR, Python Spawn details).
• Python Orchestrator Logs: /app/Log_from_docker/content_python_debug.log (DEBUG level, detailed step-by-step execution, API calls).

5. Lessons Learned (Development Log)

These are critical insights from the development of Content Engine v1.0:

5.1. Docker & Networking

• Volume Mounts: Never mount a local folder over a container folder that contains build artifacts (like node_modules or dist). Solution: Build frontend inside Docker and serve via Node/Express static files, or be extremely precise with volume mounts to prevent accidental overwrites.
• Nginx Routing (502 Bad Gateway): Frontend fetch calls MUST use relative paths (e.g., api/import instead of /api/import) when running behind a reverse proxy (/content/). Absolute paths lead to 404/502 errors because Nginx tries to route them to the root domain.
• 502 Bad Gateway (Backend Crash): Often caused by the Node.js server (server.cjs) crashing immediately on startup. Common cause: Missing backend dependencies (elike express). Solution: Create a separate package.json for the backend and run npm install for Node.js dependencies in the Dockerfile.
• Database Mounts (Bind mount failed): If a database file (.db) is mounted as a volume but doesn't exist on the host, Docker will fail. Solution: Manually touch your_db_file.db on the host before docker-compose up.

5.2. Frontend (Vite/React)

• TypeScript Configuration (tsc fails): tsc (TypeScript compiler) requires a valid tsconfig.json and potentially tsconfig.node.json in the frontend directory. Without these, npm run build will fail or produce obscure errors.
• Linting vs. Prototyping (TS6133 errors): Strict TypeScript linting rules (noUnusedLocals: true, noUnusedParameters: true) are beneficial for production but block rapid development. Solution: Temporarily loosen these rules (false) in tsconfig.json during MVP creation.
• ES Modules vs. CommonJS (module is not defined): When package.json in the frontend root has "type": "module", configuration files (.js) using module.exports syntax will fail. Solution: Rename these files to .cjs (e.g., postcss.config.js to postcss.config.cjs).
• State Persistence (Texts disappear): Frontend state (e.g., generated text) held only in useState will be lost when components unmount (e.g., on tab switch). Solution: Implement an onUpdate callback to the parent component, which triggers a loadProject to refresh data from the persistent backend database.

5.3. Python & Backend

• Standard Libraries in requirements.txt (No matching distribution): Do NOT include Python standard libraries like sqlite3 in requirements.txt. Pip will fail to find them. Solution: Remove them.
• Raw Strings for Prompts (SyntaxError: unterminated string): ALWAYS use r"""...""" (Raw Triple-Quoted Strings) with the .format() method for complex multi-line prompts (especially those containing JSON or curly braces) to prevent syntax errors in Python.
• Database Schema Mismatch (no such column): If the database schema is updated in the code (CREATE TABLE IF NOT EXISTS) but the physical .db file already exists with an older schema, new columns will not be added. Solution: During early development, deleting the .db file and letting init_db() recreate it is the fastest fix.

6. Roadmap (Future Modules)

• LinkedIn Matrix: Generate posts for (Persona x Content Type).
• Outbound Email: Cold outreach sequences.
• Press Kit: Automated PR generation.