81 lines
6.4 KiB
Markdown
81 lines
6.4 KiB
Markdown
|
|
# 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.
|