Porting map
What came from brightbean-studio and adwords-adsense, and what was dropped.
docs/PORTING.md
Where each capability in Verjson Marketing Studio comes from, and what is actually being carried across. The two source apps stay in the repo as read-only references while porting is in progress; they are not built, deployed, or imported from.
| Source | What it is | Stack | Role here |
|---|---|---|---|
requirements.txt | The brief | — | The authority. Where a source app disagrees with it, the brief wins. |
archive/brightbean-studio/ | A social-media management platform | Django 5 · HTMX · Alpine · Postgres | The organic/social half: composer, calendar, approvals, publisher, inbox, analytics, media, notifications, client portal, agent API + MCP |
archive/adwords-adsense/ | A Google Ads autopilot | Next.js 16 · Prisma · NextAuth · Neon | The paid half: Ads integration, campaign wizard, asset pipeline, conversion tracking, GA4, optimisation engine |
archive/brightbean-studio-app/ | An earlier Next.js scaffold of the same idea | Next.js 16 | Superseded — this repo is its successor. Nothing to port. |
What "porting" means here
Neither source is copied file-for-file. brightbean is Python and Django-shaped: its ORM models,
class-based views, template partials and django-background-tasks jobs have no TypeScript
equivalent to lift. What carries across is the design — the data model, the state machines, the
provider interface, the job cadences, the security posture — re-expressed in this stack.
adwords-adsense is already Next.js + Prisma, so its src/lib/** is genuinely reusable: the Google
Ads client, the sharp asset pipeline, and the crypto helpers move with light edits, but into
apps/api rather than into route handlers, since this repo's backend is a separate service.
| Kind of thing | brightbean (Django) | adwords-adsense (Next.js) |
|---|---|---|
| Data model | Re-expressed as Prisma models — direct translation | Merge into the same schema |
| Business logic | Rewritten in TS from services.py / engine.py | Port src/lib/** with edits |
| HTTP layer | Rewritten as Hono routes | Rewritten — route handlers → Hono |
| Templates / UI | Rebuilt in React against this design system | Components reusable; both are Tailwind + shadcn-shaped |
| Background jobs | Cadences kept, runtime replaced | Vercel cron → worker process |
| Provider adapters | Interface kept verbatim, implementations rewritten | Google Ads client ports largely intact |
Feature provenance
| Feature | From | Notes on the port |
|---|---|---|
| F-002 Auth | BB apps/accounts | Django-allauth → jose + bcrypt. 2FA and social login deferred. |
| F-003 Organizations | BB apps/organizations | Model translates directly. |
| F-004 Workspaces | BB apps/workspaces | Kept — a workspace is the brand/client scope below an org. |
| F-005 RBAC | BB apps/members | Roles extended with agency and client for the hired-agency case. |
| F-006 Agency logins | REQ only | Not present in either source. New: project-scoped external users. |
| F-007 Client portal | BB apps/client_portal | Magic-link pattern kept (32-byte token, stored as a SHA-256 hash). |
| F-008 Credential vault | BB apps/credentials | AES-256-GCM field encryption, key via HKDF from a env secret. Same design, node:crypto. |
| F-011 Audit log | BB + template | Already live. |
| F-021 Calendar | BB apps/calendar | Model + scheduling semantics kept; drag-to-reschedule rebuilt in React. |
| F-022 AI plan generation | REQ + AA phase 7c | AA's blueprint generator was Gemini-targeted and never shipped (blocked on an API key). Rebuilt on Groq. |
| F-030 Composer | BB apps/composer | Per-channel overrides + live preview. HTMX round-trip preview → client-side render. |
| F-031 AI composer | BB apps/intelligence | BB called a paid external "Intelligence" service with Stripe billing. Dropped — internal tool, so it calls Groq directly. |
| F-032 AI video | REQ only | New. ElevenLabs voice + a render step. |
| F-033 Media library | BB apps/media_library | Pillow/FFmpeg → sharp (+ FFmpeg for video). AA's 5-size ad pipeline folds in here. |
| F-035 Approvals | BB apps/approvals | The state machine ports as-is; it is the single most reusable piece of design in either source. |
| F-037 Publisher | BB apps/publisher/engine.py | Retry + partial-failure semantics kept. |
| F-040–F-047 Channels | BB providers/ | The abstract SocialProvider interface is kept almost verbatim — see ARCHITECTURE.md. |
| F-046 Inbox | BB apps/inbox | Including sentiment.py and the webhook receivers. |
| F-047 Webhooks | BB apps/inbox/webhooks.py | HMAC-SHA256 verification for Meta; PubSubHubbub for YouTube. Polling stays the baseline. |
| F-050 Google Ads | AA src/lib/google-ads, src/lib/ads | The most directly reusable code in either source. |
| F-051 Meta Ads | REQ only | New, built to the same AdsProvider interface. |
| F-052 Benchmarks | REQ | Neither source had benchmarks. New. |
| F-053 Campaign wizard | AA src/app/app/campaigns/new | SEARCH + PMAX flows. |
| F-054 Conversion tracking | AA src/app/app/accounts/[id]/conversion-tracking | Includes the "tracking broken since…" detector. |
| F-055 Ad assets | AA src/lib/assets | sharp pipeline, 5 required sizes. |
| F-056 Optimisation | AA phase 10 (designed, unbuilt) | Built here behind the approval gate — AA's plan was auto-apply by default. |
| F-060–F-063 Analytics | BB apps/analytics | derive.py / metrics.py / freshness.py are the reference. |
| F-064 GA4 | AA src/lib/ga4 | Ports directly. |
| F-070–F-072 Agent API | BB apps/api, apps/api_keys | django-ninja → the same /api/v1. Key hashing + scoping kept. |
| F-071 MCP | BB apps/mcp, apps/oauth_server | Streamable-HTTP transport. BB's full OAuth 2.1 DCR server is deferred — scoped keys first. |
| F-085 GDPR | BB F-8.4 | Export + delete per workspace. |
Deliberately dropped
| Dropped | Why |
|---|---|
BB's Stripe billing / subscription plumbing (apps/intelligence billing models, StudioCheckoutAttempt) | This is an internal tool. Nothing is sold, so nothing is billed. |
| BB's white-label configuration (F-5.2) | One brand. Revisit only if we resell. |
| AA's pre-pay wallet + money-transmitter design | Same reason — and it carried real regulatory exposure (RBI PPI / US money transmitter) that an internal tool has no reason to take on. |
AA's hosted client landing pages (<slug>.adsense.app) | Out of scope per the brief. |
| BB's Heroku / Railway / Render deploy manifests | Our target is Compose locally, Kubernetes in production. |
| BB's HTMX + Alpine frontend | Replaced wholesale by this repo's React design system. |
| AA's NextAuth + Neon serverless driver | Replaced by this repo's JWT auth and a standard Postgres connection. |
Reference sources
The sources live in archive/. Their nested .git directories were
removed so they commit as plain files rather than as gitlinks that clone as empty directories, and
their node_modules are not tracked. They are excluded from the npm workspaces, both tsconfigs and
lint — nothing in archive/ is built or shipped.
Delete them once the port is complete. This map is the record that survives; the code is only the reference.