Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(content): update README with v1.0 features and lessons learned

Browse Source
This commit is contained in:
Floke
2026-01-20 14:05:53 +00:00
parent 41e60c72bc
commit f68562d20c
1 changed files with 32 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
content-engine/README.md
View File

@@ -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.