# ContentOS — Developer Handover Guide

This document outlines the architecture, data flow, and next steps for the **ContentOS AI Content Machine**. It is designed to help you (the developer) take this fully functional prototype and turn it into a production-ready SaaS application.

## 1. System Architecture overview

ContentOS currently operates on a **decoupled, two-tier architecture**:

*   **Frontend:** A single-page application (SPA) built with Vanilla HTML/CSS/JS (`contentos.html`). It uses a futuristic "Punkit Creative" UI design system.
*   **Backend / AI Engine:** An **n8n automation workflow** (`contentos_workflow.json`) that acts as the backend API. It orchestrates the AI logic, calling external APIs (Groq, Pollinations) and returning structured JSON.
*   **Publishing Engine:** A secondary **n8n automation workflow** (`contentos_publish_workflow.json`) designed to catch approved content and route it to social networks.

### The Data Flow
1. User fills out the "New Brief" form in the UI.
2. UI fires an asynchronous `POST` request to the n8n webhook URL.
3. n8n extracts the payload, injects it into a prompt, and queries the **Groq API** (`llama-3.3-70b-versatile`).
4. n8n parses the response and dynamically builds a **Pollinations.ai** image URL.
5. n8n responds to the webhook with a structured JSON object.
6. The UI receives the JSON, updates the state, and renders a new card in the "Content Vault".
7. (Phase 4) User clicks "Authorize", pushing the payload to the Publishing Webhook.

---

## 2. Webhook API Schema

When the frontend communicates with the backend, it uses the following schema. 

### Request (Frontend → n8n)
```json
POST /webhook/generate-content
Content-Type: application/json

{
  "topic": "5 Reasons Your Business Needs Automation",
  "brand": "Punkit Creative",
  "industry": "Technology",
  "tone": "Professional & Bold"
}
```

### Response (n8n → Frontend)
```json
{
  "success": true,
  "data": {
    "topic": "5 Reasons...",
    "brand": "Punkit Creative",
    "industry": "Technology",
    "tone": "Professional & Bold",
    "linkedin": "...",
    "facebook": "...",
    "twitter": "...",
    "blog": "...",
    "youtube": "...",
    "imageUrl": "https://image.pollinations.ai/...",
    "videoUrl": null,
    "videoLabel": null,
    "generatedAt": "2026-06-04T12:00:00Z"
  }
}
```

---

## 3. Production Roadmap: What Needs to be Built

To take this from a prototype to a secure, scalable application, here are the key development phases:

### Phase 1: Database & Persistence
Currently, data is stored in the browser's `localStorage` (`punkit_content`).
*   **Action:** Spin up a backend database (e.g., Supabase, Firebase, or MongoDB).
*   **Action:** Update the UI to `fetch()` historical vault data on load.
*   **Action:** Modify the n8n workflow to `POST` the generated content directly to your database, rather than just returning it to the client.

### Phase 2: Authentication & Security
Currently, the login screen is a static UI gate.
*   **Action:** Implement real authentication (e.g., NextAuth, Supabase Auth, Auth0).
*   **Action:** Protect the n8n webhook endpoint with an API Key or Bearer token so it cannot be spammed publicly.

### Phase 3: Premium Media Integration (Images & Video)
Currently, images use a free fallback generator, and video is disabled.
*   **Action:** Replace the Pollinations.ai node in n8n with an **OpenAI DALL-E 3** or **Midjourney API** node for high-end, brand-consistent image generation.
*   **Action:** Reactivate the **Pexels API** node in n8n (already built into the original workflow architecture) to fetch b-roll stock video automatically.

### Phase 4: Auto-Publishing (The Final Frontier)
*   **Action:** Import the `contentos_publish_workflow.json` into n8n.
*   **Action:** Connect your LinkedIn, Facebook, and Twitter credentials directly to the nodes inside n8n.
*   **Action:** Ensure the "Publishing Webhook Endpoint" in the dashboard settings points to this new n8n workflow.