Create content-hub-database-schema.md via n8n
This commit is contained in:
parent
21a5e746dd
commit
041172df32
231
PBS/Tech/Projects/content-hub-database-schema.md
Normal file
231
PBS/Tech/Projects/content-hub-database-schema.md
Normal file
@ -0,0 +1,231 @@
|
|||||||
|
---
|
||||||
|
project: content-hub-database-schema
|
||||||
|
type: project-plan
|
||||||
|
status: active
|
||||||
|
tags:
|
||||||
|
- pbs
|
||||||
|
- flask
|
||||||
|
- mysql
|
||||||
|
- n8n
|
||||||
|
- instagram
|
||||||
|
- automation
|
||||||
|
created: 2026-03-20
|
||||||
|
updated: 2026-03-20
|
||||||
|
path: PBS/Tech/Projects/
|
||||||
|
---
|
||||||
|
|
||||||
|
# PBS Content Hub — Database Schema & Table Relationships
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This document defines the database schema and table relationships for the
|
||||||
|
PBS Content Hub. It supplements the Phase 5 Architecture & Planning
|
||||||
|
Decisions doc and serves as a handoff for Claude Code implementation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Three Data Domains Being Unified
|
||||||
|
|
||||||
|
### 1. PBS Video Manager (migrating from local SQLite to MySQL)
|
||||||
|
- Local app being migrated to the server as part of the Content Hub
|
||||||
|
- `projects` table stores all project info (name, status, description, etc.)
|
||||||
|
- Projects are the central concept — a project can be a reel, YouTube
|
||||||
|
video, or any future content type
|
||||||
|
|
||||||
|
### 2. PBS Recipe App (live on production MySQL)
|
||||||
|
- Already in MySQL (`pbs_automation` database)
|
||||||
|
- `pbs_recipes` table — stores WordPress recipe data
|
||||||
|
- Powers Jenny's admin page and n8n recipe lookups
|
||||||
|
|
||||||
|
### 3. Instagram Reel Workflow (currently in n8n data tables)
|
||||||
|
- Being migrated from n8n internal storage to MySQL
|
||||||
|
- Becomes the generic `platform_posts` table to support Instagram now and
|
||||||
|
YouTube/other platforms later
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Relationship Model
|
||||||
|
|
||||||
|
`projects` is the hub that connects everything. It reaches out to both
|
||||||
|
`pbs_recipes` and `platform_posts`. Neither of those tables needs to
|
||||||
|
reference back to projects or to each other.
|
||||||
|
|
||||||
|
```
|
||||||
|
project_types
|
||||||
|
id ←─── type_id
|
||||||
|
\
|
||||||
|
projects
|
||||||
|
/ \
|
||||||
|
recipe_id ───→ ←─── platform_post_id
|
||||||
|
pbs_recipes platform_posts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why platform_posts has no FK to projects
|
||||||
|
The platform table is just platform data. There is no scenario where
|
||||||
|
platform_posts needs to look up project info. Projects owns the
|
||||||
|
relationship to both recipes and platform posts.
|
||||||
|
|
||||||
|
### Why pbs_recipes has no FK to projects
|
||||||
|
Same reasoning. Recipes exist independently in WordPress. Projects link to
|
||||||
|
them, not the other way around.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table Definitions
|
||||||
|
|
||||||
|
### `pbs_recipes` (exists in MySQL, no changes)
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| post_id | INT, PK | WordPress post ID |
|
||||||
|
| recipe_title | VARCHAR(255) | |
|
||||||
|
| recipe_url | VARCHAR(255) | |
|
||||||
|
| keyword | VARCHAR(100), nullable | Trigger word for automation |
|
||||||
|
| created_at | TIMESTAMP | |
|
||||||
|
| updated_at | TIMESTAMP | auto-update |
|
||||||
|
|
||||||
|
CRUD: Yes — existing Jenny admin page migrates into Content Hub.
|
||||||
|
|
||||||
|
### `project_types` (new)
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| id | INT, PK, auto increment | |
|
||||||
|
| name | VARCHAR(50) | reel, youtube, etc. |
|
||||||
|
| created_at | TIMESTAMP | |
|
||||||
|
|
||||||
|
CRUD: Yes — managed in Settings tab. Allows adding new content types
|
||||||
|
without code changes.
|
||||||
|
|
||||||
|
### `projects` (new — replaces local SQLite video_projects)
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| id | INT, PK, auto increment | |
|
||||||
|
| title | VARCHAR(255) | Working title |
|
||||||
|
| type_id | INT, FK → project_types.id | |
|
||||||
|
| status | VARCHAR(50) | draft, ready, live-matched, live-needs-review.
|
||||||
|
Kept as VARCHAR for now — will become a lookup table when Trello
|
||||||
|
integration is built |
|
||||||
|
| recipe_id | INT, FK → pbs_recipes.post_id, nullable | Linked recipe |
|
||||||
|
| platform_post_id | INT, FK → platform_posts.id, nullable | Linked
|
||||||
|
platform post |
|
||||||
|
| created_at | TIMESTAMP | |
|
||||||
|
| updated_at | TIMESTAMP | auto-update |
|
||||||
|
|
||||||
|
CRUD: Yes — this is the main workspace in the Content Hub.
|
||||||
|
|
||||||
|
Note: Additional columns from the existing SQLite video_projects schema
|
||||||
|
(description, file paths, checklist data, etc.) will be added separately.
|
||||||
|
This doc focuses on the connecting fields.
|
||||||
|
|
||||||
|
### `platform_posts` (new — replaces n8n insta_reel table)
|
||||||
|
|
||||||
|
| Column | Type | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| id | INT, PK, auto increment | Internal ID |
|
||||||
|
| platform | VARCHAR(50) | instagram, youtube, tiktok, etc. |
|
||||||
|
| platform_post_id | VARCHAR(50) | Native ID from the platform. VARCHAR
|
||||||
|
because Instagram IDs overflow JavaScript integer limits |
|
||||||
|
| url | VARCHAR(255), nullable | Link to the post on the platform |
|
||||||
|
| published_at | TIMESTAMP, nullable | When it went live |
|
||||||
|
| created_at | TIMESTAMP | When we recorded it |
|
||||||
|
| updated_at | TIMESTAMP | auto-update |
|
||||||
|
|
||||||
|
CRUD: Yes — view/manage platform data in the Content Hub.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## n8n Lookup Path (Comment Reply Automation)
|
||||||
|
|
||||||
|
When n8n receives a comment on an Instagram reel and needs the keyword +
|
||||||
|
recipe URL:
|
||||||
|
|
||||||
|
```
|
||||||
|
platform_posts (match on platform_post_id = reel ID from webhook)
|
||||||
|
→ projects (WHERE platform_post_id = platform_posts.id)
|
||||||
|
→ pbs_recipes (WHERE post_id = projects.recipe_id)
|
||||||
|
→ return keyword + recipe_url for the reply
|
||||||
|
```
|
||||||
|
|
||||||
|
If any join in the chain returns null, n8n triggers the existing error
|
||||||
|
notification to Travis.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Auto-Match Routine
|
||||||
|
|
||||||
|
Triggered by n8n ping to `POST /api/match/run` after new `platform_posts`
|
||||||
|
insert.
|
||||||
|
|
||||||
|
```
|
||||||
|
For each project in "Ready" status with no platform_post_id:
|
||||||
|
→ Look in platform_posts for unmatched rows (no project pointing at
|
||||||
|
them) where:
|
||||||
|
- Matching criteria (post_id via recipe link, keyword, or other
|
||||||
|
heuristics)
|
||||||
|
→ Single confident match → update projects.platform_post_id, status →
|
||||||
|
"live-matched"
|
||||||
|
→ Multiple matches → status → "live-needs-review"
|
||||||
|
→ No match → leave as-is
|
||||||
|
```
|
||||||
|
|
||||||
|
Manual match UI is the fallback — Jenny selects from unmatched
|
||||||
|
platform_posts to link to a project.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Checking / Healthcheck (Real-Time)
|
||||||
|
|
||||||
|
No separate table needed. The Status Dashboard computes checks on page load
|
||||||
|
by querying the four tables:
|
||||||
|
|
||||||
|
- Platform posts with no project linked (unmatched)
|
||||||
|
- Projects in "ready" status with no platform_post_id for X days
|
||||||
|
- Projects linked to a recipe that has no keyword
|
||||||
|
- Broken join chains (project → recipe or project → platform_post returns
|
||||||
|
null)
|
||||||
|
|
||||||
|
Displayed as green/yellow/red indicators per project and per system on the
|
||||||
|
Status tab.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CRUD Summary
|
||||||
|
|
||||||
|
| Table | CRUD Location | Primary User |
|
||||||
|
|---|---|---|
|
||||||
|
| pbs_recipes | Reels tab (migrated admin page) | Jenny |
|
||||||
|
| project_types | Settings tab | Travis |
|
||||||
|
| projects | Projects + Reels tabs | Both |
|
||||||
|
| platform_posts | Status tab / Reels tab | Both |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Existing Tables to Keep (n8n automation logging)
|
||||||
|
|
||||||
|
These tables remain in `pbs_automation` and are not part of the Content Hub
|
||||||
|
schema, but n8n continues to use them:
|
||||||
|
|
||||||
|
- `instagram_posts_processed` — tracks processed Instagram posts (prevents
|
||||||
|
duplicate processing)
|
||||||
|
- `instagram_replies` — comment reply log for debugging/analytics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Notes
|
||||||
|
|
||||||
|
- `pbs_recipes` already exists in MySQL — no migration needed
|
||||||
|
- `projects` replaces local SQLite `video_projects` — SQLAlchemy model
|
||||||
|
update + data migration
|
||||||
|
- `platform_posts` replaces n8n internal `insta_reel` data table — data
|
||||||
|
migration from n8n to MySQL
|
||||||
|
- `project_types` is new — seed with initial values (reel, youtube)
|
||||||
|
- All new tables go in the `pbs_automation` database (or new
|
||||||
|
`pbs_content_hub` database — TBD, still an open question)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Project: Plant Based Southerner Content Hub*
|
||||||
|
*Planning Session: March 20, 2026*
|
||||||
|
*Participants: Travis & Claude*
|
||||||
Loading…
Reference in New Issue
Block a user