diff --git a/content-engine/README.md b/content-engine/README.md index 9045b12d..501d93d0 100644 --- a/content-engine/README.md +++ b/content-engine/README.md @@ -1,3 +1,4 @@ + # Content Engine (v1.0 - MVP) **Status:** Live / MVP Implemented @@ -27,40 +28,53 @@ It is a **Content Generation Dashboard** designed to produce high-quality, SEO-o ## 3. Implemented Features (MVP) -### Phase 1: Project Setup & Import +### 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. -### Phase 2: SEO Strategy +### 3.2. Phase 2: SEO Strategy * [x] **AI Brainstorming:** Generates 15 strategic Seed Keywords (Short & Long Tail) based on the imported strategy. -* [x] **Persistence:** Saves the chosen SEO strategy to the database. +* [ ] **Keyword Selection:** User can select primary/secondary keywords (Planned). +* [x] **Persistence:** Saves the generated SEO strategy (all keywords) to the database. -### Phase 3: Website Copy Generator +### 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. Lessons Learned (Development Log) +## 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). -### 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. -* **Nginx Routing:** Frontend fetch calls must use **relative paths** (e.g., `api/import` instead of `/api/import`) to respect the reverse proxy path (`/content/`). Absolute paths lead to 404/502 errors because Nginx tries to route them to the root. -* **502 Bad Gateway:** Often caused by the Node server crashing immediately on startup. *Common cause:* Missing backend dependencies (like `express`) in the Docker image because `package.json` wasn't copied/installed for the backend context. +## 5. Lessons Learned (Development Log) -### Frontend (Vite/React) -* **TypeScript Configuration:** `tsc` requires a valid `tsconfig.json`. Without it, `npm run build` fails silently or with obscure errors. -* **Linting vs. Prototyping:** Strict linting (`noUnusedLocals: true`) is good for production but blocks rapid prototyping. *Solution:* Relax rules in `tsconfig.json` during MVP phase. -* **ES Modules vs. CommonJS:** When `package.json` has `"type": "module"`, configuration files like `postcss.config.js` MUST be renamed to `.cjs` if they use `module.exports`. +These are critical insights from the development of Content Engine v1.0: -### Python & Backend -* **Standard Libs:** Do NOT include standard libraries like `sqlite3` in `requirements.txt`. Pip will fail. -* **Strings in Prompts:** ALWAYS use `r"""..."""` (Raw Strings) for prompts to avoid syntax errors with curly braces in JSON templates. +### 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. Roadmap +### 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. \ No newline at end of file +* **Press Kit:** Automated PR generation.