Dr.Social

1. Mission

A single system that can create, read, update, and delete on any major social platform. V1 covers everything whose official API is rich enough to drive through Composio MCP: LinkedIn X / Twitter YouTube Facebook Reddit Instagram (read-only). V2 adds TikTok and Instagram-write via the Device channel, and Threads via Browser.

Who this is for

Dr.Social is built for marketing agencies. A single agency is one tenant and manages many independent talents (not a group — each talent is an autonomous, real human personality with their own goals, voice, look, and audience). Every talent runs one or more accounts across the V1 platform set, and is represented end-to-end in the system by a rich talent profile stored in the database.

What a talent profile holds

The profile is the source of truth for everything the system does on behalf of a talent:

• Identity & contact: display name, real name, emails, phone, timezone, language, owner-user link.
• Connected accounts: every social handle the talent owns. V1: LinkedIn, X, YouTube, Facebook, Reddit, and Instagram-read — all MCP-channel via Composio. TikTok and Instagram-write are profile-level placeholders until V2 §1 lands the Device channel.
• Credentials & secrets: per-account OAuth refresh tokens (via Composio) — all stored in Supabase Vault, never in plaintext columns.
• Personality & voice: personality narrative, tone-of-voice, content pillars, "do not say" list, goals and KPIs, stories and lore that frame how the talent presents online.
• Media library: face references, brand kit, pictures, videos — fed into Higgsfield (direct MCP) to train a per-talent Soul character so every generated image or video keeps the same face/brand on every channel. Voice samples are stored for V2 voice-clone use (Higgsfield-first; ElevenLabs only if needed).
• Content queue & schedule: drafts and ready-to-post pieces, posting cadence per account, time windows, blackout dates.
• Approval state: which pieces have been approved by the talent (the actual human owner) and are cleared to publish.

Capabilities (V1)

• Agency-grade tenancy: one agency manages many talents; one talent manages one-or-more accounts; every account is bound to exactly one platform and one channel.
• Account lifecycle: import existing accounts on the V1 platforms via Composio OAuth, manage them, retire them. Automated signup → V2 §6.
• Content production: generate text, images, video, and audio narration — always conditioned on the target talent's profile — then publish them. Image / voice / video synthesis is in V1.
• Inbound communications, in-character: read and respond to DMs, comments, and mentions on every V1 platform as that specific talent (subject to each platform's official-API scope).
• White-label PersonaAgent: a reusable agent template that is conditioned on a talent's profile at every call. Carries that talent's personality, media, goals; acts on their behalf. Stateless — each tick fires a fresh call.
• Owner approval gate: the talent portal gives the real human behind each talent a dedicated view to approve or reject their own content queue before anything is published.
• Autonomous operations: a tenant-wide cron tick fans out per-talent agent work.
• Operator supervision: a web dashboard exposes accounts, queue, and inbox for human override at the agency level.

1.b Multi-Tenancy & Talent Model

Dr.Social is a multi-tenant SaaS: every record in the system is owned by a tenant (a client of ours — an agency, a creator team, a brand). Inside a tenant, the unit of "who" is a talent — a real human personality whose social presence we manage. One talent can run many accounts, across many platforms, on any channel that's been wired up. This shape is the spine of the data model and shows up in every agent, every query, every dashboard view — independent of which channels are live in a given release.

What "talent-centric" buys us

• Cross-account media consistency. Every video, photo, and audio piece generated for the talent uses the same face reference / voice clone / brand kit. When a new channel lights up in V2, the new account inherits all of that on day one.
• Operator UX. The dashboard groups accounts by talent; the operator manages "Aurora Studios" as one entity, even though in V1 only her LinkedIn account is acted on.
• Compliant deletion. Tenant-scoped RLS plus a talent-level "right to erasure" makes GDPR/CCPA workflows tractable.

1.c V1 Assumptions (planning-mode autonomous choices)

This section records the calls I made when the user explicitly asked me to keep the V1 stack as minimal as possible and not interrupt for clarification. Override any of these by editing this section + the relevant downstream sections.

2. System Overview

The system stacks into six layers. Each upper layer only knows about the layer immediately below it through a stable interface, so the lower layers are individually replaceable. V1 has a single execution backend (MCP); the platform adapter layer is built so adding Device / Browser channels in V2 doesn't touch agents above.

3. The 6 Layers

4. Orchestration — 4 LLM Agents + Services

V1 has exactly four agents that need an LLM in the loop — anything reasoning, generating, or classifying. Everything else is a plain Python module (no agent ceremony). Don't commit to a heavyweight agent framework (e.g. Google ADK A2A) until V2 actually needs peer-to-peer agent topology; V1's orchestration is a star (Workflow → agent) and a simple async function-call graph is enough.

Services (plain Python — no agent ceremony)

Example tick (cron → per-talent fan-out)

workflow.tick()
  for talent in tenants.active_talents(due_now):
      ctx = load_talent_context(talent)                  # profile, recent posts, inbox, queue

      for account in ctx.accounts:                       # V1: every MCP-channel account
          if persona_decide_should_post(talent, account, ctx):
              brief  = persona_decide_brief(talent, account, ctx)
              draft  = content_generate(talent, brief)         # ContentAgent
              if moderation_approve(draft):
                  content_queue.enqueue(talent, account, draft,
                                        status='awaiting_owner_approval')

          # publish only what the owner has already approved
          for piece in content_queue.due_and_approved(talent, account):
              post_publish(account, piece)                     # PostAgent / adapter

          for msg in inbox_fetch(account):                     # InboxAgent
              if moderation_approve_inbound(msg):
                  reply = persona_draft_reply(talent, msg)
                  inbox_send(account, msg.thread, reply,
                             status='awaiting_owner_approval')

Two invariants to notice: (1) no backend is selected at runtime — the dispatcher reads accounts.channel and refuses any other (V1: always 'mcp'). (2) nothing publishes without owner approval — every draft and reply lands in the queue and only the pieces the human owner has approved are eligible.

5. LLM Provider — abfs.tech router

All four LLM agents call a single internal provider: the abfs.tech LLM router at https://www.abfs.tech/v1/. The router is already operational and serves Anthropic Claude models through Anthropic-compatible and OpenAI-compatible endpoints, with subscription rotation and per-key logging. Dr.Social doesn't talk to Anthropic / OpenAI / any model provider directly — only to this router.

Why this matters

• Single billing surface. Every LLM dollar Dr.Social spends shows up in the abfs.tech admin — usage attribution, key revocation, subscription rotation handled there, not here.
• Drop-in model swaps. Bumping Sonnet 4.6 → 4.7 (or trying GPT for an experiment) is a config change, not a code change. The router exposes a uniform shape on both sides.
• One thing to monitor. Latency / error rate / token consumption all observed at the router level (already wired). Dr.Social's worker just retries on 5xx.

# Pseudocode — every LLM call in Dr.Social goes through this client.
class LlmRouterClient:
    def __init__(self, base_url="https://www.abfs.tech", api_key=ENV["ABFS_LLM_API_KEY"]):
        self.base_url = base_url
        self.api_key  = api_key

    async def messages(self, *, model, system, messages, stream=False):
        # POST /v1/messages — Anthropic-shaped
        ...

    async def chat(self, *, model, messages, stream=False):
        # POST /v1/chat/completions — OpenAI-shaped
        ...

6. Platform Adapter Layer

Every social network is reduced to one Python interface. Agents above call this interface — they never know whether they're driving LinkedIn or Instagram or anything else.

class SocialPlatform(Protocol):
    name: str  # "linkedin" | "instagram" | "tiktok" | ...

    # account lifecycle (V1 = OAuth-import-only)
    async def import_account(self, profile: ImportedProfile, backend: Backend) -> Account: ...
    async def login(self, account: Account, backend: Backend) -> Session: ...
    async def logout(self, account: Account) -> None: ...
    async def health_check(self, account: Account) -> AccountHealth: ...

    # create / update / delete
    async def publish_post(self, account: Account, content: Content) -> PostRef: ...
    async def edit_post(self, account: Account, post: PostRef, patch: ContentPatch) -> PostRef: ...
    async def delete_post(self, account: Account, post: PostRef) -> None: ...

    # read
    async def read_feed(self, account: Account, limit: int) -> list[Post]: ...
    async def read_post(self, account: Account, post: PostRef) -> Post: ...
    async def read_dms(self, account: Account, since: datetime) -> list[Message]: ...
    async def read_comments(self, account: Account, post: PostRef) -> list[Comment]: ...
    async def read_mentions(self, account: Account, since: datetime) -> list[Mention]: ...

    # respond
    async def send_dm(self, account: Account, thread: ThreadRef, body: str, media: list = []) -> None: ...
    async def reply_comment(self, account: Account, comment: CommentRef, body: str) -> None: ...
    async def react(self, account: Account, target: Ref, reaction: str) -> None: ...

7. Execution Backend (V1: MCP only)

V1 ships with one execution backend — MCP. Device + Browser channels are documented in V2 (their absence is what makes V1 tractable). The MCP backend itself is multi-vendor by design: every social platform or media vendor is reached through a per-platform MCP server URL, looked up at dispatch time from a registry.

MCP server registry — direct first, Composio fallback

Rule: if a platform or vendor exposes a direct MCP server, Dr.Social connects to it directly. Composio is used only for platforms that don't yet have direct MCP support. The registry is a per-deployment config table; swapping a platform from Composio to a direct MCP server is a config change with no agent-level rewrites.

When an official MCP server for one of the Composio-routed platforms ships (e.g. an official LinkedIn MCP), we update the registry row and the worker starts using it on next deploy. No platform-adapter rewrite, no migration.

Capability matrix (V1) — per platform via MCP

✓ = supported in V1. ~ = Composio scope-dependent (works if the OAuth grant includes the right scopes; some platforms have restricted DM access). ✗ = not in the official API, needs Device channel. n/a = the platform itself doesn't have the operation.

⛔ Channel isolation rule (hard constraint)

-- V1: only MCP is allowed
alter table accounts
  add column channel text not null
  check (channel in ('mcp'));         -- V2 expands: add 'device', then 'browser'

create or replace function lock_channel() returns trigger as $$
begin
  if NEW.channel is distinct from OLD.channel then
    raise exception 'channel is immutable on account %', OLD.id;
  end if;
  return NEW;
end $$ language plpgsql;

create trigger accounts_channel_immutable
  before update on accounts
  for each row execute function lock_channel();

-- worker dispatch (no `required_channel` on jobs; the account row is truth)
job = claim_next_job()
account = load(job.account_id)
backend = load_backend(account.channel)         -- V1: always Composio MCP
backend.execute(job)

8. Identity (V1 minimal set)

V1 needs the absolute minimum to act on existing MCP-channel accounts. Anti-bot stealth, signup automation, 2FA relay, fingerprint pools, proxy fleets — all V2.

9. Content Pipeline

• Briefs come from Analytics (past performance), PersonaAgent (autonomous), the operator (manual), or a talent post request (see §10).
• V1 is multi-modal but vendor-narrow. ContentAgent generates text per platform and drives the MediaPipeline for images + video. Generation is conditioned on the talent's profile (face references via Higgsfield's Soul characters, brand kit via every image/video brief). Pre-uploaded assets are still available — ContentAgent selects them when no new generation is needed, saving cost.
• Assets are persisted to Supabase Storage keyed by content hash; only metadata lives in the Postgres content table. Generated media is cached so an identical brief never regenerates.
• ModerationAgent blocks anything flagged before it reaches the publish queue — for generated images, it also runs a quick NSFW classifier before ever showing them to the operator or talent.
• The PublishQueue is platform-aware: one brief fans out to per-platform variants in one pass (X gets a short body + portrait video; YouTube gets the long-form video + description; LinkedIn gets the article + landscape hero; Reddit gets the subreddit-formatted post; Facebook gets the page-post variant). When V2 adds Device, TikTok and IG-write join the same fan-out at no extra brief cost.
• Voice / narration: Higgsfield's MCP exposes audio capabilities alongside image/video — V1 uses what's available there. If a talent needs higher-quality voice cloning, ElevenLabs joins as a V2 supplement.

10. Post Request Pipeline

Content reaches the approval queue from two distinct sources — both treated equally downstream:

• AI-initiated — ContentAgent invents content from scratch using the talent's profile, goals, content pillars, and recent engagement. This is the "what to post next" path described in §9.
• Talent post requests — the talent explicitly asks for a post: a prompt + a target-platform selection (any one or more of their V1 accounts), plus optional media attachments. This section describes that path.

Post requests matter because most talents have specific things they want said or shown that the AI won't dream up on its own — a launch, a reaction, a behind-the-scenes moment. Media is optional: a request can be just a prompt + platforms, just media + platforms, or both.

What a post request carries

• Target platforms (required) — one or more of the talent's active accounts. The picker enables every V1-active handle (LinkedIn, X, YouTube, Facebook, Reddit, IG-read where the operation is a read/comment); TikTok and IG-write chips are visible but disabled with a "V2" pill, so talents can see what's coming.
• Prompt (optional) — a sentence or paragraph saying what the post is about. Empty prompt = the AI picks a topic from the talent's content pillars.
• Attached media (optional) — photos, video, voice memos. If present, the system edits them to fit each platform; if absent, content is generated from scratch.
• Schedule hint (optional) — preferred publish time or "ASAP". Defaults to the talent's posting cadence per account.

Two ingress paths (both V1)

Pipeline stages

What the pipeline produces

• One request → one row per selected platform. In V1 a request can already fan out across LinkedIn + X + YouTube + Facebook + Reddit in one shot — the talent's UI grouping ("post idea with stacked variants") handles that case. When V2 §1 lands, TikTok and IG-write join the fan-out at no extra brief cost.
• Per-platform approval. The talent can approve each variant independently. PostAgent only publishes approved rows.
• Mixed in with AI-initiated content. The approval queue doesn't segregate by origin; AI-initiated and request-derived ideas sit side by side, each tagged with provenance.
• Voice cloning is opt-in per talent. If the talent has agreed and uploaded reference audio (managed under Brand & voice in /me), transcribed voice memos can return as polished narration in their voice.
• Rejection learning loop. When a talent rejects a variant with a reason, the text is appended to that talent's style guide and used to filter future drafts.
• Operator visibility. Operators see every request a talent has sent but cannot publish without the talent's approval (unless the talent has explicitly opted into operator-override mode in their preferences).

Schema additions (V1 sketch)

post_requests          (id, tenant_id, talent_id,
                        source CHECK in ('browser', 'email'),
                        prompt_text NULL,                  -- empty = let AI pick from pillars
                        target_account_ids[],              -- V1: any V1 platform; TT/IG-write disabled in picker
                        schedule_hint NULL,
                        sender_email NULL,                 -- populated for source='email'
                        gmail_message_id NULL UNIQUE,      -- populated for source='email'; dedup key
                        status in ('received','analyzing','drafting','complete','failed'),
                        created_at, processed_at)

post_request_attachments (id, post_request_id, storage_path, mime, bytes, duration_s,
                          analysis_json NULL,              -- scenes, faces, hooks, OCR …
                          transcript_text NULL)
                          -- zero rows if the request had no media

content_queue.origin            enum: 'ai_initiated' | 'request_browser' | 'request_email'
content_queue.post_request_id   NULL unless origin is 'request_*'
content_queue.rejection_reason  captured at owner rejection — fed into talent style guide

Talent slug rules

• Each talent has a globally unique slug column (e.g. aurora-lee). The catch-all email forwarding model means slugs collide across tenants, so uniqueness is enforced tenant-globally, not tenant-scoped, for this one column.
• Slug is lowercase ASCII, hyphens allowed, 3–32 chars, no leading/trailing hyphen. Anything else is rejected at create time.
• Format: <slug>+post@dr-social.app for post requests. Reserve +post, +settings, +inbox as future intents — the IMAP parser refuses unknown suffixes for now.

10.b Talent Asset Auto-Fetch (onboarding UX)

Asking a brand-new talent to "upload 10–30 photos of yourself plus voice samples and a brand kit" is the boring chore that kills onboarding. Most talents have years of media already on their connected social accounts — Dr.Social's V1 onboarding flow turns that into the path of least resistance by letting talents hand over their social handles and having agents fetch, score, and curate the best photos autonomously. The talent reviews a shortlist; they don't have to dig through their camera roll.

Consent model — clean by construction

The talent connects their social accounts during onboarding via the same Composio OAuth flow Dr.Social already uses for publishing. The OAuth grant gives Dr.Social authorized API access to that talent's own posts — no scraping, no third-party data, no consent ambiguity. Then a single explicit toggle in /me → Brand & voice:

Pipeline

What the service does NOT do

• Never scrapes — every fetch is an authorized API call through Composio, against the talent's own posts. If Composio doesn't have a scope to read the talent's own media on a given platform, that platform is skipped, not scraped.
• Never uses unapproved assets — until the talent has clicked Approve on a row, that asset is invisible to ContentAgent and to Higgsfield Soul training. The review pile is the gate.
• Never auto-trains — fetching populates the library; training the Soul character is a separate explicit step the talent triggers from /me → Brand & voice.
• Never re-fetches what the talent rejected — rejected source_post_ids land on a deny-list per talent; the service skips them on subsequent runs.

Continuous mode

Once initial onboarding is done, the talent can leave auto-fetch on. A weekly cron run re-pulls the most recent N posts and adds anything new to the review pile. New posts are never auto-approved — the talent always curates. This keeps the asset library fresh without surprise content moving into training pools behind the talent's back.

Schema additions (V1)

-- talent_assets gains provenance + curation fields
talent_assets:
  ADD COLUMN source           CHECK in ('uploaded','auto_fetched_instagram','auto_fetched_linkedin',
                                       'auto_fetched_x','auto_fetched_youtube','auto_fetched_facebook',
                                       'auto_fetched_reddit') DEFAULT 'uploaded'
  ADD COLUMN source_post_id   TEXT NULL                  -- platform-side post id, for dedupe
  ADD COLUMN fetched_at       TIMESTAMPTZ NULL
  ADD COLUMN review_status    CHECK in ('approved','pending_review','rejected') DEFAULT 'approved'
  ADD COLUMN rejection_reason TEXT NULL
  ADD COLUMN face_score       REAL NULL                  -- 0..1, populated by scorer
  ADD COLUMN sharpness_score  REAL NULL                  -- Laplacian variance, normalized

talent_asset_denylist        (id, talent_id, platform, source_post_id, denied_at, reason)
                             -- rows the talent explicitly rejected; AssetFetcher skips these

Higgsfield training trigger

The talent's /me → Brand & voice panel shows a "Train my Soul character" button. It enables once ≥5 approved talent_assets[kind='face'] exist. Clicking the button hands those approved photos to Higgsfield's MCP server (train_soul_character tool call). The resulting Soul ID is stored on the talent profile and used by every subsequent image/video generation. Re-training is also a button — fires when the talent adds new approved face photos and wants the Soul model refreshed.

11. Data Model (V1)

~9 tables. Every tenant-scoped table carries tenant_id NOT NULL and is gated by an RLS policy. Composite FKs (tenant_id, id) on every cross-table reference make the database refuse cross-tenant attachments.

Tenancy & identity

tenants                (id, name, plan, status,
                        default_tick_interval_seconds,
                        created_at)
                       -- one row per agency. Per-talent override → V2 §9

tenant_users           (id, tenant_id, supabase_user_id,
                        role CHECK in ('owner','editor','viewer'))

talents                (id, tenant_id, slug UNIQUE,
                        display_name, real_name,
                        bio_short, bio_long, timezone, language, status,
                        owner_user_id,                       -- the real human who must approve
                        primary_email, contact_emails[], phone,
                        created_at)

talent_profile         (talent_id PK,
                        personality_md, stories_md,
                        goals_json,
                        face_ref_urls[], voice_clone_ref NULL,
                        brand_kit_json, style_guide_md,
                        content_pillars[], hashtag_preferences[], do_not_say[],
                        updated_at)
                       -- 1:1 with talents; split out only for size

talent_assets          (id, talent_id, kind in ('face','voice','logo','wardrobe','bgm',
                                                'picture','video','document'),
                        storage_url, hash, metadata_json, created_at)

Accounts & channel-bound identity

accounts               (id, tenant_id, talent_id, platform, handle, status,
                        channel CHECK (channel in ('mcp')) IMMUTABLE,
                        vault_ref,                          -- OAuth refresh token (Composio)
                        posting_schedule_json,
                        created_at)
                       -- one row per (platform, talent, channel)
                       -- V1: every row has channel='mcp';
                       --     platform ∈ ('linkedin','x','youtube','facebook','reddit','instagram')
                       --     (instagram in V1 is read-only via Graph API).
                       -- V2 §1 adds channel='device' for full-IG/TT; V2 §2 adds 'browser'.

Content, queue, requests

content                (id, tenant_id, talent_id, hash, type, asset_url,
                        caption, hashtags, generated_by, moderated, created_at)

content_queue          (id, tenant_id, talent_id, account_id, content_id,
                        origin enum ('ai_initiated','request_browser','request_email'),
                        post_request_id NULL,
                        scheduled_for,
                        state CHECK in
                          ('draft','awaiting_owner_approval','approved','rejected',
                           'queued','published','failed'),
                        approved_by_user_id, approved_at,
                        rejected_reason,
                        created_at, updated_at)
                       -- per-talent publish queue shown on /me

post_requests          (id, tenant_id, talent_id,
                        source CHECK in ('browser', 'email'),
                        prompt_text NULL,
                        target_account_ids[],
                        schedule_hint NULL,
                        sender_email NULL,
                        gmail_message_id NULL UNIQUE,
                        status in ('received','analyzing','drafting','complete','failed'),
                        created_at, processed_at)

post_request_attachments (id, post_request_id, storage_path, mime, bytes, duration_s,
                          analysis_json NULL, transcript_text NULL)

Inbox & activity

threads                (id, tenant_id, account_id, peer_handle, last_message_at)
                       -- V2 §7 adds audience_identity_id (cross-platform identity resolution)

messages               (id, tenant_id, thread_id, direction, body, media_urls,
                        classified_as, status, created_at)

jobs                   (id, tenant_id, account_id, kind, payload_json, status, run_after)
                       -- no required_channel column; account.channel is the source of truth

events                 (id, tenant_id, ts, kind, account_id, payload_json)
                       -- audit + activity stream

Invariants enforced in Postgres: (1) accounts.channel is immutable (trigger blocks UPDATE). (2) tenant_id consistency — every FK across tables uses composite (tenant_id, id), so the database refuses to attach an account in tenant A to a talent in tenant B. (3) RLS policies on every tenant-scoped table. (4) talents.slug is globally unique (cross-tenant) because of the catch-all email model.

12. Dashboards (operator + talent self-service)

Two server-rendered web UIs, two different audiences, one shared backend. Both are tenant-scoped — Supabase RLS enforces tenant isolation on every query. Python templates + htmx for partials; polling at ~5s for "live" panels. (React + Vite frontend → V2 §11. Supabase Realtime → V2 §10.)

• 13.a · Operator dashboard — multi-talent supervision view for agency staff. Mockup: dashboard/_layout.html.
• 13.b · Talent self-service portal — single-talent workspace for the human represented by the persona. Mockup: dashboard/me.html.

13.a — Operator dashboard (V1: 6 pages)

Top-level navigation pivots around talents, not accounts. Agency staff see all talents under their tenant, run overrides, supervise inboxes, and watch system health. V1 acts on every MCP-channel account (LinkedIn, X, YouTube, Facebook, Reddit, IG-read); TikTok and IG-write handles appear as profile-level placeholders waiting on V2 §1.

13.b — Talent self-service portal (/me)

A standalone single-page workspace for the talent themselves. Scoped to one talent — the one whose owner_user_id matches the logged-in Supabase Auth user. Different chrome from the operator dashboard (warmer accent, no tenant switcher, no cross-talent navigation). Mockup: dashboard/me.html.

13. Workflows & Scheduling

Scheduling lives inside Supabase via pg_cron. A row in a jobs table is inserted on every tick; the worker process polls jobs WHERE status='pending' using SELECT … FOR UPDATE SKIP LOCKED — a clean Postgres-native queue with no Redis or Celery.

Tick cadence is tenant-level in V1

V1 has a single cadence per tenant — tenants.default_tick_interval_seconds — driving every talent in that tenant. The Workflow handler iterates the tenant's active talents on each tick and fans out per talent. Per-talent override and dynamic adjustment (warm-up, blackouts, burn back-off) → V2 §9.

• Baseline wake-up: pg_cron inserts a tick job at the tenant's configured interval → Workflow picks it up and fans out.
• Posting cadence: per-account schedule stored in accounts.posting_schedule_json. The tick checks "is it time?" and enqueues a publish job — but only for items already approved in content_queue.
• Inbox polling: per-account interval. Composio webhooks where supported skip polling.
• Live dashboard fan-out (V1): dashboard polls at ~5s. Real-time subscriptions → V2 §10.

-- pg_cron entry — tenant cadence configurable, not hard-coded
select cron.schedule(
  'drsocial-baseline-tick',
  '* * * * *',                                         -- once per minute baseline
  $$ insert into jobs (kind, payload) values ('tick', '{}') $$
);

-- Workflow handler (per tick, per tenant)
for tenant in tenants.active():
    if not tenant.is_tick_due(now):
        continue
    for talent in tenant.active_talents():
        fan_out(talent, now)

-- Atomic job pick
select id, kind, payload
from jobs
where status = 'pending' and run_after <= now()
order by run_after
limit 1
for update skip locked;

14. Tech Stack

One Railway service, one managed backend (Supabase), one external LLM provider (abfs.tech router), plus media-model vendors and Composio for the MCP channel. That's the whole infrastructure for V1.

What's used (V1)

What's deliberately NOT used (V1)

• ❌ Device hub / Appium · ❌ Browser channel · ❌ Fingerprints · ❌ iproxy · ❌ Redis · ❌ Celery · ❌ RabbitMQ · ❌ Vaultwarden · ❌ S3 / GCS / Drive · ❌ Separate websocket server · ❌ Kubernetes · ❌ Docker Compose stack with N services · ❌ Node toolchain · ❌ React / Vue / Svelte · ❌ Google ADK A2A framework (pick when needed)

14.b Deployment — Railway.app

• One service, one Dockerfile, one Procfile-style start command.
• No databases on Railway. No volumes on Railway. Restart-safe by design — all state in Supabase.
• Cost target: $5–20/mo Railway + Supabase free tier baseline. abfs.tech LLM usage scales with talent count; Composio free tier covers V1 platform volumes at launch. Higgsfield is pay-per-call on its own plan — budgets are per-tenant in the dashboard and ContentAgent throttles when limits get close.

V1 environment variables

# Auto-set by Railway
PORT
RAILWAY_ENVIRONMENT_NAME

# Supabase (production — the only environment)
SUPABASE_PROD_URL
SUPABASE_PROD_SERVICE_KEY
SUPABASE_PROD_ANON_KEY
SUPABASE_PROD_DB_PASS             # direct Postgres pool (worker job queue)

# LLM provider (abfs.tech router)
ABFS_LLM_API_KEY                  # bearer for https://www.abfs.tech/v1/

# MCP execution channel
# Rule: direct MCP first, Composio fallback (see §7 MCP server registry)

# Direct MCP — Higgsfield (image + video gen, Soul characters)
# No API key — OAuth at first connect, refresh token vaulted.
HIGGSFIELD_MCP_URL=https://mcp.higgsfield.ai/mcp

# Composio MCP — fallback for LinkedIn, X, YouTube, Facebook, Reddit, IG-read
COMPOSIO_API_KEY

# Email post-request intake (Gmail IMAP poll, V1 MVP shape)
GMAIL_INTAKE_USER                 # e.g. easytoremind123@gmail.com
GMAIL_INTAKE_APP_PASSWORD         # Gmail App Password (requires 2FA on the account)

Live environments

One Railway environment — production — runs the FastAPI app from src/drsocial/main.py: api + worker + ticker in one process. The worker only spins up when Supabase env vars are set, so a freshly-cloned tree still serves the architecture docs + mockups without any credentials. There is deliberately no dev/staging/preview environment: the Higgsfield OAuth chain is a single-use rotating token owned by prod, and any second running copy of the app would steal rotations and kill prod media auth (Railway PR environments are disabled for this reason).

15. Repo Layout

V1 implementation

Dr.Social/
├── src/drsocial/
│   ├── agents/                  # the 4 LLM agents — each thin, all call llm_router
│   │   ├── persona.py           # persona_decide_*  — stateless functions
│   │   ├── content.py           # content_generate
│   │   ├── inbox.py             # inbox_fetch + classify + reply-draft
│   │   └── moderation.py        # moderation_approve, moderation_approve_inbound
│   ├── services/                # plain Python — no agent ceremony
│   │   ├── workflow.py          # ticker — enqueues per-account jobs
│   │   ├── ai_initiated.py      # one AI-initiated post (persona→content→mod→media→queue)
│   │   ├── request_agent.py     # post_request → content_queue (awaiting approval)
│   │   ├── post_publisher.py    # publishes approved content via platform adapter
│   │   ├── inbox_runner.py      # polls one account's inbox, classifies, drafts replies
│   │   ├── asset_fetcher.py     # §10.b — pulls talent's own posts into review pile
│   │   ├── account_importer.py  # Composio OAuth import + health check
│   │   └── analytics.py         # SQL rollups
│   ├── intake/                  # post-request ingress
│   │   ├── browser.py           # /me form handler
│   │   └── gmail_imap.py        # IMAP poller; parses To: → talent_slug; dedup via gmail_message_id
│   ├── platforms/               # adapter layer
│   │   ├── base.py              # SocialPlatform protocol
│   │   ├── _composio_adapter.py # shared base — every Composio-backed platform
│   │   ├── linkedin.py / x.py / youtube.py / facebook.py / reddit.py  # V1 — live, via Composio MCP
│   │   ├── instagram.py         # V1 read-only; write paths raise NotImplementedError (V2 §1)
│   │   ├── tiktok.py            # stub — wired live in V2 §1 (Device)
│   │   └── registry.py          # name → adapter lookup
│   ├── backends/                # execution backends — V1 is MCP-only
│   │   ├── mcp.py               # minimal MCP JSON-RPC client
│   │   └── registry.py          # platform→target map (direct MCP first, Composio fallback)
│   ├── media/                   # MediaPipeline — generation + caching
│   │   ├── pipeline.py          # routes briefs to higgsfield
│   │   ├── higgsfield.py        # video + image (Soul character) direct MCP client
│   │   └── ffmpeg.py            # cuts, aspect, captions (subprocess wrapper)
│   ├── llm_router.py            # thin client for https://www.abfs.tech/v1/
│   ├── supabase_client.py       # service/user clients + asyncpg pool for SKIP LOCKED
│   ├── jobs.py                  # job queue helpers (FOR UPDATE SKIP LOCKED)
│   ├── worker.py                # job dispatcher + tick driver
│   ├── api.py                   # FastAPI — serves dashboard + /me + /api endpoints
│   ├── logging_setup.py
│   ├── settings.py
│   └── main.py                  # entrypoint: runs api + worker + ticker in one asyncio loop
├── dashboard/                   # htmx + Jinja templates, served by api.py
├── supabase/
│   ├── migrations/              # plain .sql files
│   └── seed.sql
├── tests/
├── Dockerfile                   # single image — runs api + worker
├── railway.json                 # single-service Railway config
└── pyproject.toml