# User-Driven Content Architecture

**Updated:** 2026-08-28

---

## Core principle

The system is **fully user-driven**. No predefined demo project, brand, industry, or content ships in the production path. A new customer starts empty, configures project/markets → website + brand → business context, then creates content via AI, manual compose, or CSV — all through **one pipeline**.

```
Business Understanding → Context Intelligence → Storytelling → Content Generation → QA → Scheduling → Publishing
```

---

## Required flow

```
Project config (timezone + markets)
        → Website Intelligence + Brand Profile
        → Business Context (review / confirm)
        → Storytelling framework + content sequence
        → AI | Manual | CSV
        → Unified Content Library
        → Edit → QA → Review → Approve → Schedule → Publish
```

Fully automated publishing is opt-in only: **Auto Approval + Auto Publish**.

---

## Layers

| Layer | Source | Role |
|-------|--------|------|
| **Project** | My Project | Configuration: name, URL, industry label, timezone, markets |
| **Website intelligence** | Homepage scrape | Extracted facts; missing fields stay `missing`/`unknown` |
| **Brand profile** | User + website fill of empty fields | Identity, voice, logo, contact |
| **Business context** | Combined + user confirm | Primary factual source for generation |
| **Storytelling framework** | Configurable 10-beat structure | Narrative order only — no novel text |
| **Platform RAG** | `data/knowledge/` | How to write for each platform |
| **AI** | Caption/image/video models | Transformation/generation |

---

## Unified content model

All content uses `GeneratedPost` (`src/types/workflow.ts`):

| Field | Purpose |
|-------|---------|
| `origin` | `ai_rag` \| `manual` \| `csv_import` (`ai` treated as `ai_rag`) |
| `caption`, `title`, `hashtags`, `linkUrl`, `cta` | Text |
| `imageUrl`, `videoUrl`, `mediaType` | Media |
| `status` | `draft` → `approved` → `published` |
| `sequencePostId` | Optional — omitted/`manual` for ad-hoc posts |

Storage: `src/lib/storage/generated-posts.ts` + MariaDB `generated_posts`.

---

## Scheduling

- **1–5 posts/day** per project (`src/lib/scheduling/plan-times.ts`)
- Times computed in the **primary project timezone**
- **±30 minute** active window per slot (`slot-check.ts`)
- Minute variation via seeded offsets — posts never fire at identical times
- Target markets store per-country timezone for **future** multi-market slots; publishing today does not hardcode one country for all markets
- Applies to **AI, manual, and CSV** after approval (unless Auto Approval + Auto Publish is ON)

---

## Publishing

Single hub: `src/lib/social/publish-post.ts` → used by Quick Publish, cron, and manual override.

---

## Demo data policy

No Acme, B2BEFAX, demo company, sample captions, or hardcoded products/services in the live generation path. Forbidden-term validators still block those strings if a model emits them.