Core Concepts

Reference vocabulary for PowerMarketing. Read this first to understand how the platform works — how humans and agents collaborate to produce and publish content continuously.

Platform Purpose

PowerMarketing is an AI-powered content distribution platform for B2B brands. It automates the full loop from content planning → AI generation → human review (when needed) → publishing. It is multi-brand: one installation serves multiple brands, each with its own settings, API keys, and calendar.

Human action AI Agent Approval gate Auto-publish Output

Human vs Agent — Who Does What

PowerMarketing splits work between humans (strategy, review, approval) and AI agents (generation, publishing). Understanding this split is the key to using the platform well.

Brands

A Brand is the central entity. Everything in PowerMarketing belongs to a brand: posts, calendar entries, leads, subscribers, credentials, API keys.

Users & Roles

PowerMarketing has its own user accounts — no external authentication required. JWT Bearer tokens, bcrypt passwords, 8-hour sessions.

The Two-Track Publication Pipeline

This is the central design of PowerMarketing. Every AI-generated post takes one of two paths, determined by its content type and the brand's publication rules.

Track 1 — Auto-publish ⚡

Zero human action required. The dispatcher generates content and publishes it directly. Used for time-sensitive, lightweight content: news, trend_scan, short_post, repurposed.

Track 2 — Approval required 👁

Human reviews the AI draft before it goes live. Used for strategic, high-visibility content: article, post, story, carousel. video and email are always Track 2 — this cannot be changed.

Safe fallback: If a Track 1 auto-publish fails (no credential configured, API error), the post falls back to the Track 2 Decision Inbox instead of being lost.

Per-entry override: Any calendar entry can have its "Require approval" checkbox checked, forcing Track 2 regardless of the brand's publication rules.

The Agent Crew

PowerMarketing runs eight specialised AI agents. Each has a single responsibility and a defined trigger.

Headless Audience Acquisition

The audience subscribes on each product's own website — never inside PowerMarketing. PowerMarketing is the headless brain behind the brand: it ingests subscribers from the product's site, social, and feeds, then manages and nurtures them. Three ingestion paths feed one unified per-brand contacts store:

• A · Embeddable widget — a tiny vanilla-JS snippet (copy it from Settings → Ingestion) the product site drops onto a page.
• B · Ingest API + webhook — the product backend POSTs to /api/ingest/{public_key}/subscribe (or sends an HMAC-verified webhook).
• C · Pull connectors — PowerMarketing pulls from a REST source or CSV the product already uses.

Every brand has an ingest_public_key (shown and rotatable in Settings → Ingestion). Capture uses double opt-in for GDPR/CAN-SPAM compliance, and a public unsubscribe link is always honored. The confirm and unsubscribe links open branded HTML pages (themed per brand, with website & close buttons) rather than raw responses. Re-subscribing is idempotent: an already-confirmed address is told “you're already subscribed” (no duplicate email), a pending address gets a fresh confirmation, and a previously unsubscribed address is re-opted-in.

Contacts & Lifecycle

Every captured person becomes a contact in one unified, per-brand store — with a stage, a behavioral score, a consent status, and a source. Newsletter subscribers and sales leads automatically link into the same record, matched by email — one person, one row, no matter how they arrived. The People page is the day-to-day view (filters, tags, CSV import, saved segments); click Manage → on a row for the deep contact view (event timeline, score, one-click enroll into a nurture sequence).

Behavioral scoring: email opens (+1) and clicks (+3) arrive via the Resend webhook and raise the contact's score. Crossing a threshold auto-promotes the stage — 10 → engaged, 25 → hot — so the hottest leads surface automatically.

Nurture Sequences

A nurture sequence is an ordered set of steps (each with a delay, a channel, and an AI prompt). Enroll a contact and the scheduler processes due steps automatically: the AI drafts the message, the autopilot level gates it, and it either sends or queues for approval — then the sequence advances. Manage sequences on the Nurture page ("Run due now" triggers them on demand).

Newsletter Automation

Recurring schedules assemble an auto-digest from the period's published posts. Because email is always Track 2, the digest is queued as a Decision for human approval, then sent to a segment (filtered by stage / score). A deliverability guardian automatically pauses a brand's sending if complaints or bounces spike, and the public unsubscribe link is always honored. Manage it on the Newsletters page (with a live digest preview).

Autopilot — Human Supervision Dial

Every brand has an autopilot level that decides how much the crew does without asking. Set it from the Command Center dial. It gates every outward action (publish, send) — it never removes your ability to step in.

Earned autonomy: the dial isn't the only path to hands-off. The platform tracks how often you approve each content type without editing it; once a type crosses 20+ reviews at ≥95% unedited approvals in the last 90 days, it proposes a 🎓 Autonomy Upgrade in the approval inbox. Approving grants that content type auto-publish — even at Review level. Locked types (video, email) and per-entry "require approval" flags always keep their human gate. The intended trajectory: you approve everything at first, the system earns trust type by type, and you end up approving only exceptions.

Command Center — Mission Control

The Command Center is the operator's home screen. At a glance: live stat tiles (new contacts, pending approvals, newsletter status, monthly budget), the audience funnel, the autopilot dial, a unified approvals queue (posts, newsletters, nurture, plans), an AI command box (describe a change in plain English → the Planner proposes a plan), plus today's pipeline, "Run Agents Now", and quick actions.

Proof Library — the Trust Layer

The Proof Library is a managed set of trust assets the AI crew cites instead of inventing — testimonials, case studies, metrics, and credentials. Stored per brand (the Proof page in the sidebar); only active assets are used.

• Proof is injected into the ContentCreator and newsletter prompts, so generated content quotes real customers and numbers — and is instructed to never fabricate proof.
• A dedicated social_proof content type / generation mode builds a post around your proof assets.
• The Planner sees when proof exists and can propose proof-led posts.

The Distribution Stack Scorecard

Adoption — not just the product — wins. The Command Center scores each brand across the five layers of the AI distribution stack, each 0–100, computed from data the platform already holds, so you can see and close the gaps.

Each layer shows its score, a short detail, and a one-line "how to improve" on the Command Center's Distribution Stack card, plus an overall adoption-coverage score.

Cost Control — Optional LLM Gateway

Agents can route every LLM call through an optional LiteLLM gateway that enforces a per-brand monthly budget and picks the cheapest capable model via tiers:

When the gateway is off, each brand uses its own provider API key directly — a graceful fallback that needs no extra infrastructure.

Plans & Self-Serve Onboarding

PowerMarketing is multi-tenant and sellable. Plan tiers map to a monthly budget and seat limit:

A public Signup page provisions a new brand, an admin user, and ingest keys in one step. Access is brand-scoped — non-members are blocked (tenant isolation).

Content Calendar

The calendar is the source of truth for what gets generated and when. Each calendar entry contains: topic, content type, platforms (comma-separated), scheduled date, optional owner, and optional "require approval" override.

One entry with platforms = linkedin,twitter creates two posts — one per platform — each generated independently for that platform's format.

Calendar Auto-Fill — "✦ Plan this week"

The Dispatcher — Sequence of Events

When dispatch runs (automatically or manually), for each pending calendar entry:

Brand Readiness

Before dispatch runs, the platform evaluates a readiness checklist. If any blocking check fails, dispatch returns 412 Precondition Failed with the full checklist. The Command Center shows an amber card with Fix → links.

• ✗
  Brand voice (80+ chars) — blocks dispatch
• ✗
  Content pillars defined — blocks dispatch
• ✗
  LLM API key present — blocks dispatch
• ✗
  LLM model configured — blocks dispatch
• ✗
  Calendar entries for target date — blocks dispatch
• ✗
  Credentials for target platforms — blocks dispatch
• ⚠
  Auto-publish types configured — warning only
• ⚠
  Tavily key (if web search enabled) — warning only

Brand Quick-Start

New brands arrive empty. The Quick-Start card auto-appears in Settings → Brand Profile. One LLM call from 3 plain-language inputs fills all four profile fields simultaneously.

Generation Modes

You never choose a mode. Since 2026-07-26 the mode is a property of the content type, declared once in the content-type registry (app/services/content_types.py) and applied everywhere — the dispatcher, the planner, and the Create page alike. Picking News means trend_scan; picking Article means product_topic. Content type and writing angle used to be two separate dropdowns, one of them hidden under Advanced options and sharing a name with a content type; that was the most confusing part of the model. competitor_signal has no content type of its own and remains available as an explicit override.

Decisions

A Decision is created for every Track 2 post. It sits in the Decision Inbox until a human acts.

• Approve — marks post as approved, unlocks the Publish button
• Reject — removes from queue; post stays as ai_draft

Decisions can be actioned from the Command Center inbox (inline, no navigation) or the Decisions page (full list with AI Guidance).

API Keys — Per Brand, Not Global

All API keys live in the database per-brand — never in environment variables. Configure in Settings → API Keys.

Scheduler

APScheduler polls every 15 minutes. On each tick it dispatches brands whose effective dispatch time (fixed, or learned from engagement in auto mode) falls within ±7 minutes of the current time. Each brand has its own independent dispatch time. Idempotent — brands already dispatched today are skipped unless ?force=true.

Around the dispatch loop, a set of background jobs keeps the engine self-sustaining: a nightly metrics refresh (04:00 UTC) pulls engagement for recent posts and feeds it back into planning and timing; weekly planning (Mon 05:00) fills the calendar; a daily top-up (05:15) re-plans any non-manual brand with an empty 3-day window; evergreen recycling (Wed 05:30, opt-in) re-queues proven winners; the autonomy check (Mon 05:45) proposes auto-publish upgrades; and the approval digest (06:30) emails pending decisions with one-click approve links. The full timetable is in the Admin Guide.

Glossary