# PromoMotion — Project Knowledge Doc
*Last updated: May 2026*

---

## Concept Summary

AI-powered real estate marketing package generator. Agent uploads listing photos + property details + MLS description. PromoMotion delivers a complete marketing package: headline, copy, flyer PDF, social posts, email teaser, and property reel video — in minutes.

The core promise: **Upload → Generate → Download.** No template editing. No drag-and-drop. No video editing skills required.

---

## Problem Being Solved

Agents have the raw materials (photos, MLS description, property details) but converting those into a full marketing package requires time, multiple tools, and skill sets most agents don't have or don't want to spend time on. The video reel specifically was confirmed as the highest-friction bottleneck by beta contacts.

---

## Target User

Individual real estate agents. Not brokerages (yet). Agents understand marketing value and treat it as a cost of doing business — low resistance to SaaS pricing.

**Beta testers:** 2 confirmed real estate agent contacts. Ready to test immediately.

---

## Revenue Model

- **SaaS subscription** — monthly/annual plans
- Subscription managed **outside the app** (separate billing page/portal)
- App access gated by active subscription status (flag in DB)
- No in-app Stripe checkout friction
- No per-listing charges at launch
- Brokerage/white-label: future consideration only, not in scope now

---

## Name Status

**ProMotion** ✅ LOCKED
**Domain:** promotion.casa ✅ SECURED

---

## Core User Workflow

### Step 1 — Agent Profile (one-time setup)
- Agent name
- Brokerage
- Phone / Email
- Logo upload
- Brand colors (hex)
- Preferred style: Luxury / Modern / Farm & Ranch / Family-Oriented / Investment

### Step 2 — Create New Listing
**Property details:**
- Address
- Price
- Beds / Baths / Square Footage
- Lot Size / Year Built
- MLS Description
- Property Features (checkbox or freeform)

**Media:**
- Property photo uploads (multiple)

### Step 3 — AI Analysis
OpenAI GPT-4o receives: property data + MLS description + selected images + agent branding profile.

**Returns JSON:**
```json
{
  "headline": "",
  "short_description": "",
  "long_description": "",
  "email_teaser": "",
  "facebook_post": "",
  "instagram_post": "",
  "youtube_description": "",
  "video_script": "",
  "scene_order": []
}
```

AI also identifies:
- Key selling points (Mountain Views, Chef's Kitchen, Primary Suite, etc.)
- Emotional marketing angle (Luxury, Family, Retirement, Entertainment, Investment, Move-Up Buyer)

### Step 4 — Output Package
Agent downloads a ZIP containing:
- `listing-flyer.pdf`
- `social-posts.txt`
- `email-copy.txt`
- `listing-reel.mp4`
- `youtube-description.txt`

---

## Marketing Assets Detail

### 1. Flyer PDF
- Hero image
- Headline
- Property summary
- Feature list
- Agent branding (logo, colors, contact)
- QR code

### 2. Social Package
- Facebook: long-form post
- Instagram: caption + hashtags
- LinkedIn: professional version
- X: short-form version

### 3. Email Marketing
- Subject line
- Preview text
- Email teaser body
- CTA

### 4. Property Reel (Hero Feature)
AI determines scene order, durations, text overlays, voiceover script, CTA.

**Example scene structure:**
```
Scene 1: Exterior — "Just Listed"
Scene 2: Kitchen — "Remodeled Chef's Kitchen"
Scene 3: Living Room — "Open Concept Living"
Scene 4: Primary Suite — "Private Owner's Retreat"
Scene 5: Backyard — "Perfect For Summer Entertaining"
Scene 6: Agent Branding
```

---

## Video Engine

### V1 — Remotion (launch version)
- No AI video generation
- Photos + motion (zoom/pan) + text overlays + music
- Renders real MP4 server-side
- Fast, cheap, reliable
- Runs as async job on server

### V2 — Premium Upgrade (future)
- Runway or Luma AI
- Cinematic motion, push-ins, slow camera moves
- Enhanced hero shots
- Premium plan tier only

---

## Tech Stack

| Layer | Choice |
|---|---|
| Frontend | Next.js (React) |
| Backend | Node.js + Express |
| AI Content | OpenAI GPT-4o |
| PDF Flyer | Puppeteer or @react-pdf/renderer |
| Video | Remotion (V1) |
| Storage | S3 or Lightsail Object Storage |
| Auth | Clerk or Supabase Auth |
| Payments | Stripe (subscription, external to app) |
| Database | Supabase (Postgres) |
| Email | Amazon SES (existing infrastructure) |

---

## Architecture Notes

### Async Video Render Flow
```
Agent submits listing
→ Job queued (Supabase or Redis)
→ Node worker picks it up
→ Remotion renders MP4
→ Uploads to S3
→ Job marked complete
→ Agent gets download link / notification
```

### Subscription Gate
- Stripe webhook updates `subscription_active` flag in Supabase
- App checks flag on login / route access
- No billing UI inside the app itself

### Hosting
- AWS Lightsail (Ubuntu/Apache) — existing infrastructure
- Worker process runs alongside Apache on same instance (or separate Lightsail instance if load warrants)

---

## Scope — V1 Launch (everything needed for real value)

**In scope:**
- Agent profile (one-time setup)
- New listing form + photo upload
- OpenAI content generation
- Social posts output
- Email copy output
- Flyer PDF (one clean template)
- Property reel (Remotion)
- Download package as ZIP
- SaaS subscription gate

**Out of scope for V1:**
- Multiple flyer templates
- Team / brokerage plans
- LinkedIn / YouTube outputs
- AI video generation (Runway/Luma)
- White-label

---

## Competitive Advantage

Most competitors require template editing, manual layout, drag-and-drop design, or video editing. PromoMotion's advantage is zero post-processing — the output is ready to use as delivered.

---

## Design / Brand Notes

- App name TBD — domain check required before branding decisions
- No CTAs, ads, or upsells inside the app
- Clean, professional UI appropriate for real estate agents
- DotComBot.com palette for reference (owner's existing brand):
  - `#5B7491` / `#D0D9E0` / `#060F1A` / `#FEFEFE` / `#CBD5DC`
  - PromoMotion may get its own palette once named

---

## Architecture Decisions (Locked)

| Decision | Choice | Rationale |
|---|---|---|
| Auth | Supabase Auth | Already using Supabase for DB, no extra dependency |
| Hosting | Single Lightsail instance | Launch simplicity; split later if load warrants |
| Video V1 | Remotion | Server-side MP4 render, no AI video cost, fast |
| Queue | Supabase polling | No Redis needed at launch volume |

## Open Items

1. **Confirm flyer template design** — base sketch done, style pass needed before PDF engine goes live
2. **Formalize beta agent agreement** (informal is fine)
3. **Build subscription billing page** — external to app, Stripe checkout link or embedded