# 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
*   [x] **GTM Bridge:** Lists and imports strategies directly from GTM Architect.
*   [x] **Context Loading:** Automatically extracts Product Category, ICPs, and Core Value Propositions.

### 3.2. Phase 2: SEO Strategy
*   [x] **AI Brainstorming:** Generates 15 strategic Seed Keywords (Short & Long Tail) based on the imported strategy.
*   [ ] **Keyword Selection:** User can select primary/secondary keywords (Planned).
*   [x] **Persistence:** Saves the generated SEO strategy (all keywords) to the database.

### 3.3. Phase 3: Website Copy Generator
*   [x] **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)
*   [x] **Editor UI:** Integrated Markdown editor for manual refinement.
*   [x] **Human-in-the-Loop:** "Re-Generate" (AI) and "Save Changes" (Manual) functionality.
*   [x] **Content Persistence:** Generated/edited content for sections persists across tab changes/reloads.
*   [x] **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.