Dr.Social V2 ROADMAP

1. Device execution channel — GADS hub integration

The first V2 unlock. With this we get TikTok and Instagram-write back in scope — the two surfaces where the official APIs are too thin for agency-grade use and a real device is the only reliable path. (V1 already drives LinkedIn, X, YouTube, Facebook, Reddit, and Instagram-read via MCP — those don't need this unlock.) The moment GADS is connected, every Device-channel adapter the architecture already specifies starts working.

What GADS is

GADS is an open-source self-hosted device farm (Go + MongoDB) that exposes per-device Appium endpoints via a central Hub, with Providers running on hosts attached to physical iOS/Android devices. Anderson runs an instance on his Mac with a USB hub of devices; our snapshot of the upstream lives at UnlimitedWealthEmperor/Dr.Iphones. Dr.Social is a client of his Hub.

Authentication

GADS uses OAuth2 client credentials passed as an Appium capability — not a bearer header. The flow:

1. Anderson opens the Hub admin UI → Client Credentials → Create New Credential → names it Dr.Social V1 dev.
2. The Hub returns a client_id + client_secret. The secret is shown once; Anderson copies and shares it with us out-of-band (Signal / 1Password share, not chat).
3. We store the secret in Supabase Vault and reference it in backends/gads.py.
4. Every Appium session opens the URL http(s)://<hub>/device/<udid>/appium with "gads:clientSecret": "<secret>" as a capability.

What Dr.Social adds

New env vars when this lands

GADS_HUB_URL            # https://<anderson-hub> — public HTTPS endpoint
GADS_CLIENT_ID          # gads_1704123456_abc12345 (or per his prefix)
GADS_CLIENT_SECRET      # shown once at credential creation — stored in Vault + env

What we need from Anderson before this lands

1. Public HTTPS URL for the Hub. Cloudflare Tunnel is the easiest path — no static IP, no firewall changes. Free.
2. A Dr.Social V1 dev client credential. Generated in the Hub admin panel, secret shared securely once.
3. UDID inventory. Which devices are available to us, OS + model, current state (live / busy elsewhere). Pulls from GET /api/devices.

2. Browser execution channel

Playwright-driven Chromium per account, with per-account stable fingerprints and a dedicated mobile-carrier proxy. The full anti-correlation stack — only worth building when the Device + MCP combination genuinely runs out of headroom.

Schema additions when re-enabled

fingerprints           (id, account_id, spec_json, created_at, burned_at)
iproxy_connections     (id, iproxy_external_id, api_key_vault_ref, carrier, country,
                        bound_account_id, state, current_ip, last_rotated_at,
                        unique_ip_window_days, created_at, retired_at)
                       -- state ∈ {free, bound, cooling_off, retired}
sessions               (id, account_id, channel, started_at, ended_at, outcome)
ip_rotations           (id, iproxy_connection_id, rotated_at, old_ip, new_ip, reason)

The accounts.channel CHECK constraint expands to include 'browser'.

3. iproxy.online proxy infrastructure

We operate our own production-grade mobile proxy business through iproxy.online — a fleet of real Android devices, each producing a real mobile-carrier IP. Gold-tier proxy signal for social platforms.

ProxyAgent API surface

class ProxyAgent:
    async def provision(self, account_id: str) -> IproxyConnection:
        """At account enrollment (browser channel only). Reserves a free connection,
        stores its API key in Vault, sets ip_change_wait_unique=True, returns binding."""
    async def current_ip(self, account_id: str) -> str: ...
    async def rotate(self, account_id: str, reason: str) -> str: ...
    async def health(self, account_id: str) -> ConnectionHealth: ...
    async def release(self, account_id: str) -> None:
        """On account retirement — returns connection to pool after cool-off + IP-history purge."""

4. Fingerprint pool

Per-account stable, realistic browser fingerprints. Mimics AdsPower / Multilogin behavior. Same fingerprint reused across every Browser-backend session for that account — never randomized per login.

• WebGL vendor/renderer, canvas hash, audio hash
• UA, platform, languages, timezone, locale, geolocation
• Screen size, DPR, color depth
• Fonts, plugins, hardware concurrency, deviceMemory
• Bound to the account's proxy → consistent geo

FingerprintAgent owns the pool: mints stable per-account browser fingerprints, rotates only on confirmed burn signal (not on every login — that defeats the point).

5. Burn detection & rotation

Each adapter operation reports outcome: ok / soft-block / hard-block / shadowban-suspected. FingerprintAgent + ProxyAgent react:

• Soft block — back off activity rate on that account; do not rotate yet (rotation is itself a trust signal).
• Hard block — quarantine fingerprint, rotate proxy, downgrade account to read-only until operator review.
• Shadowban suspected — same as hard block, plus flag the account for AnalyticsAgent to monitor reach decay.

6. Account signup automation & 2FA relay

Account signup is the highest-risk flow on every platform — signup detection is where anti-bot teams invest hardest. Until a customer specifically asks for "make me 5 new TikTok accounts," V1 treats accounts as imported, not created. V2 brings back AccountAgent as a signup driver and the 2FA-relay wiring it needs.

AccountAgent (signup-driver mode)

Creates and warms up accounts. Picks an execution backend, requests a fingerprint, drives signup flow, stores credentials, ramps activity over a warm-up curve.

2FA Relay

When a login prompts for 2FA, the Telegram bot pings the operator (or a connected Dr.Emails IMAP-worker for email codes). The agent waits, the operator (or Dr.Emails) submits, the flow resumes.

7. Audience identity resolution

Real followers don't have a single handle — they exist as @aurora_fan_tt on TikTok, @aurorafan on Instagram, and Sarah K. on LinkedIn. Dr.Social V2 treats each per-platform handle as a separate audience_identity and probabilistically links them to one audience_member.

How identities get linked

Schema additions when re-enabled

audience_members       (id, tenant_id, display_name_guess, avatar_hash, notes,
                        merge_status CHECK in ('auto','operator_confirmed','operator_split'),
                        created_at, last_seen_at)
audience_identities    (id, tenant_id, audience_member_id, platform, external_handle,
                        external_user_id, display_name, avatar_url, bio,
                        confidence float, first_seen_at, last_seen_at,
                        UNIQUE (tenant_id, platform, external_user_id))
audience_interactions  (id, tenant_id, audience_identity_id, account_id,
                        kind in ('dm','comment','reply','mention','follow','like','share'),
                        ref_id, ts, payload_json)
identity_link_signals  (id, tenant_id, audience_identity_id, signal_kind, signal_value,
                        weight float, observed_at)
threads                (id, tenant_id, account_id, audience_identity_id, last_message_at)
                       -- V1 threads reference accounts directly; V2 adds audience_identity_id

8. Email post-request path — graduate to dedicated inbound infra

V1 already ships an email post-request path — see V1 §10. It's wired through Cloudflare Email Routing catch-all on dr-social.app → one operator Gmail inbox → IMAP poll every 30s. This is enough for MVP volumes and adds zero email-vendor cost.

V2 graduates that path to dedicated inbound infrastructure when one of these triggers fires:

Schema additions when this V2 graduation lands

talent_request_senders (id, talent_id, email, verified_at, last_used_at)
                       -- only emails from this allowlist may submit to the intake address

-- The post_requests.source enum doesn't change (already accepts 'email' in V1);
-- only the *ingestion path* moves from Gmail-IMAP to SES/Postmark webhook.

9. Per-talent tick cadence

V1 has a single tenants.default_tick_interval_seconds that drives every talent in the tenant. V2 adds per-talent override and dynamic adjustment.

-- Adds to talents table:
talents.tick_interval_seconds INT NULL   -- NULL = use tenant default
talents.last_ticked_at TIMESTAMPTZ NULL

-- Worker side: resolve the per-talent effective cadence
select p.id,
       coalesce(p.tick_interval_seconds,
                t.default_tick_interval_seconds,
                :system_default_tick_seconds) as effective_tick_seconds,
       p.last_ticked_at
from talents p
join tenants t on t.id = p.tenant_id
where p.status = 'active'
  and (p.last_ticked_at is null
       or now() - p.last_ticked_at >= make_interval(secs => …));

PersonaAgent can adjust tick_interval_seconds dynamically (warm-up phase, blackout windows, burn-signal back-off). The "Tick interval" field in /me.html Preferences becomes editable.

10. Supabase Realtime fan-out

V1 dashboard polls every 5s via htmx hx-trigger="every 5s". V2 swaps to Supabase Realtime subscriptions on events, posts, messages, and content_queue.

• Dashboard subscribes to Realtime channels — push, not pull.
• Auth-token plumbing: short-lived JWT minted for each operator session.
• Frontend acquires a real Supabase client (or a thin SSE bridge if we stay on htmx).
• No separate websocket service to operate — Supabase handles it.

11. React + Vite frontend

V1 dashboard is server-rendered HTML with htmx for partials. Simple to develop, simple to deploy, no Node toolchain. V2 introduces React + Vite when richness demands it — but the URL space stays identical so adopting is incremental.

• React + Vite build, output to src/drsocial/static/
• FastAPI serves the SPA at /dashboard/ + the talent portal at /me.
• Realtime via Supabase JS client (depends on §10).
• Adds: Node toolchain in CI, npm install step, frontend type checking.

12. Operator dashboard expansion

V1 has 5 operator pages: Overview, Talents, Accounts, Queue, Inbox, Settings. The pages below land back when their underlying feature does:

13. Split api / worker into two services

V1 runs api + worker as asyncio tasks inside one Railway service — cheaper, simpler ops, one restart loop. When that becomes a contention bottleneck, split into two services with separate Dockerfiles. Same code, just a different entrypoint per service.

-- V2 deployment shape
service: api      Dockerfile.api      $PORT public      runs FastAPI + serves dashboard
service: worker   Dockerfile.worker   no public port    runs the asyncio job loop
                                                        scale independently

14. Media Generation Stack partial in V1