# PostSync Pro — Process & Workflow Overview

This document explains how PostSync Pro works from login to published post.  
Use it to brief stakeholders, developers, or clients on **what data is collected**, **how context is built**, and **how posting content is generated**.

---

## 1. Core principle

PostSync Pro does **not** use a generic Knowledge Base for generation (KB is hidden for now).

All AI output is driven by **project-specific context only**:

```
Project Data + Brand Profile + Posting Context (sequence)
        ↓
   Context Builder (structured prompt)
        ↓
   AI Text + Image Generation
        ↓
   Post Review (human approval)
        ↓
   Publish to connected social accounts
```

**Rule:** No content is generated without project context.  
**Rule:** Paused projects do **not** generate or publish.

---

## 2. High-level flow (7-step wizard)

| Step | Screen | Purpose |
|------|--------|---------|
| 1 | **My Project** | Create workspace: name, website, industry, timezone, target countries. Set **Active / Paused**. |
| 2 | **Brand Profile** | Company name, tagline, industry, brand voice, logo upload. |
| 3 | **Posting Context** | Define rotating post sequence (Post 1 → 2 → 3 → loop). |
| 4 | **Smart Schedule** | Choose posts per day; system plans audience-optimized times. |
| 5 | **Automation** | Toggle rules (high-score publish, loop sequence, random timing). |
| 6 | **Connected Accounts** | Link LinkedIn, Facebook, Instagram, X, etc. |
| 7 | **Live Generation** | Generate and publish today’s post on demand. |

Navigation: **Previous / Next** in the footer bar on every step.

---

## 3. Authentication

1. User opens `/login`
2. Signs in via **LinkedIn OAuth** or **Demo login**
3. Lands on **My Project** (Step 1)

Environment: `LINKEDIN_*` variables in `.env.local`

---

## 4. What is “context”?

**Context** = structured business information the AI is allowed to use.

It is built from three sources (no external KB):

### A. Project context (Step 1)
- Project name  
- Website URL  
- Industry  
- Timezone  
- Target countries  
- Status: **Active** or **Paused**

### B. Brand context (Step 2)
- Company name  
- Tagline  
- Brand voice (Professional, Friendly, etc.)  
- Industry focus  
- Company logo (stored for brand identity; used in future image/branding flows)

### C. Posting context (Step 3)
- **Context name** (e.g. `Q3 Product Launch`)  
- **Post sequence** — a list of slots, not a calendar:

| Slot | Example title | Example brief | Category |
|------|---------------|---------------|----------|
| Post 1 | Product Launch Teaser | Introduce the Q3 suite… | Product Launch |
| Post 2 | Customer Success Story | How clients achieved 40% faster… | Customer Stories |
| Post 3 | Industry Insight | Why real-time posting wins… | Industry Insights |

The system **loops** through this sequence on each scheduled day:  
Post 1 → Post 2 → Post 3 → Post 1 → …

---

## 5. Context Builder (how prompts are made)

Before any AI call, the app merges project + brand + one sequence item into a single text block.

**Example structure sent to the AI:**

```text
## Project
Name: Fax Broadcasting
Website: https://example.com
Industry: Technology / Software
Timezone: America/New_York (EST)
Target markets: US, GB, IN, CA
Status: active

## Brand Profile
Company: Acme Corp
Tagline: Automate your reach
Brand voice: Professional
Industry focus: Technology / Software

## Posting Context
Context: Q3 Product Launch
Sequence slot: Post 3 — Industry Insight
Brief: Why real-time, context-driven posting wins in 2025.
Category: Industry Insights
```

**Code location:** `src/lib/context/build-project-context.ts`

**AI instructions (summary):**
- Write one publish-ready social post  
- Use **only** the facts above — no invented clients, metrics, or offers  
- Plain text, under ~280 words, 2–4 hashtags  

---

## 6. AI provider configuration

Provider is switched via **environment only** — no code changes.

| Variable | Purpose |
|----------|---------|
| `AI_PROVIDER` | `openai` or `anthropic` |
| `OPENAI_API_KEY` | OpenAI text (+ images via DALL-E) |
| `OPENAI_MODEL` | e.g. `gpt-4o` |
| `OPENAI_TIMEOUT` | Seconds |
| `ANTHROPIC_API_KEY` | Anthropic text |
| `ANTHROPIC_MODEL` | e.g. `claude-opus-5` |
| `ANTHROPIC_TIMEOUT` | Seconds |

- **Text:** uses `AI_PROVIDER`  
- **Images:** uses OpenAI DALL-E when `OPENAI_API_KEY` is set; otherwise a placeholder gradient  

**Code location:** `src/lib/ai/`

---

## 7. Content generation process (step by step)

### When generation runs

Generation is triggered when:
- User clicks **Generate from context** on a sequence item (Posting Context), or  
- User clicks **Generate Now** on Live Generation, or  
- Automation + schedule run (foundation in place; manual triggers are primary today)

### Preconditions (all required)

| Check | If failed |
|-------|-----------|
| Project status = **Active** | Error: project paused |
| Posting context **saved** | Error: save context first |
| At least one sequence post exists | Error: add posts |
| AI API key configured | Error: missing provider key |

### Generation pipeline

```
1. Pick sequence item (specific slot or “next” in rotation)
2. buildProjectContextPayload()  → structured context text
3. AI generateText()             → post caption
4. buildImagePrompt()            → image description from caption + brand
5. AI generateImage()            → image URL (or placeholder)
6. Save GeneratedPost            → status: draft
7. User reviews in Post Review
8. Approve → Publish            → status: published
```

**Code location:** `src/lib/generation/run-generation.ts`  
**API:** `POST /api/generation/generate`  
**Storage:** `data/generated-posts.json`

### What is stored per generated post

| Field | Description |
|-------|-------------|
| `caption` | AI-written post text |
| `imageUrl` | Generated image (if available) |
| `imagePrompt` | Prompt used for image |
| `title` | Sequence slot title |
| `contextSnapshot` | Full context block used (audit trail) |
| `provider` / `model` | Which AI was used |
| `platforms` | LinkedIn, Facebook, etc. |
| `status` | `draft` → `approved` → `published` |
| `engagementScore` | Estimated score for preview |

---

## 8. Post review before publishing

**Screen:** Post Review (`/generated-posts`)

1. User sees full caption + image + platforms  
2. **Approve** — marks post ready  
3. **Publish** — sends to connected platforms (simulated publish in current build; stores `published` status)

Paused projects **cannot** publish.

---

## 9. Project status: Active vs Paused

| Status | Generate content | Publish | Show schedule times |
|--------|------------------|---------|---------------------|
| **Active** | Yes | Yes | Yes |
| **Paused** | No | No | Hidden |

Set on **My Project** → Project status toggle.

---

## 10. Connected accounts & platforms

On **Connected Accounts**, user links social platforms.

When generating:
- If accounts are connected → post targets those platforms  
- If none connected → defaults to `linkedin`

LinkedIn login OAuth is separate from “Connect Account” for publishing.

---

## 11. End-to-end user journey (summary)

```
Login
  → Create Project (Active)
  → Save Brand Profile (+ logo)
  → Define & Save Posting Context (sequence)
  → Save Schedule
  → Configure Automation rules
  → Connect social accounts
  → Generate from context (or Live Generation)
  → Review in Post Review
  → Approve & Publish
```

---

## 12. What we tell clients (short pitch)

> PostSync Pro collects **your** project and brand information, builds a **structured context** for each post in your rotating sequence, and uses AI to generate **personalized captions and images** — only from that context, never from a generic knowledge base. Every post is **saved for review** before it goes live. Only **active** projects publish; paused projects stop all automation.

---

## 13. Future (not in current build)

- Knowledge Base module (hidden in navigation until context-driven KB is ready)  
- Fully automated cron-based publishing without manual “Generate Now”  
- Real OAuth publish to LinkedIn/Facebook APIs (current publish updates status + preview)  
- Video generation step on Live Generation  

---

## 14. Key files reference

| Area | Path |
|------|------|
| Context builder | `src/lib/context/build-project-context.ts` |
| AI providers | `src/lib/ai/` |
| Generation runner | `src/lib/generation/run-generation.ts` |
| Generated posts storage | `src/lib/storage/generated-posts.ts` |
| API: generate | `src/app/api/generation/generate/route.ts` |
| API: list posts | `src/app/api/generation/posts/route.ts` |
| UI: Posting Context | `src/app/posting-context/page.tsx` |
| UI: Post Review | `src/app/generated-posts/page.tsx` |
| UI: Live Generation | `src/app/live-generation/page.tsx` |
| Env config | `.env.local` / `.env.example` |
| Design reference images | `images/` |

---

*Last updated: matches current PostSync Pro Next.js implementation.*