Clientsflow Studio — Handoff Guide

From Matyas → Dani  |  Repo: matt-clientsflow/clientsflow-studio (private)  |  Date: 2026-06-18

1. What is this app

A Modal-hosted sales-prep tool. Feed it a prospect's website URL, it returns: deep-scraped site analysis, SEO keyword research + DataForSEO volumes, competitor analysis, and a fully generated new website HTML — all via Gemini 3.1 Pro. Output goes into a reviewer workflow and Notion CRM. Hungarian UI, English code.

2. Branch map

3. What Matyas built on v3.1

All commits are already pushed. These are the major features added on top of v3.0:

• Deep recursive scraper — crawls up to 60 pages (depth 4) including fragment-only nav links, seeds from sitemap.xml. Navbar rebuilt from grouped header links. ~2× faster than before.
• DataForSEO as default volume source — replaces Google Ads volumes (Ads OAuth expired). Global toggle in a Setting table to switch back. Keyword checkbox selection exports final-keywords.csv for downstream steps.
• Editable logo + background removal — click to override URL, hover to trigger Gemini gemini-2.5-flash-image bg removal. Note: the model returns an opaque result on solid-bg logos — code falls back to a corner-matte. A real segmenter (rembg) is the future upgrade.
• Generate split into 4a + 4b cards — 4a = generate with selectable system prompt (empty default, RULE_BANK named version), 4b = prompt-driven refine pass. Both have Load-into-reviewer + Regenerate buttons.
• Live HUF CPC — app/clients/fx.py fetches a live USD→HUF rate so DataForSEO CPC is correctly in HUF (the flat 365 rate overstated CPC by ~20%).
• Always-on status bar — #labStatus shows what's running at all times; poll interval 5s→3s.
• Logo bg-removal real-alpha gate — the endpoint checks for genuine alpha pixels before accepting the model's output; prevents a painted checkerboard being served as a transparent PNG.

Full test suite: 148 green / 1 skipped. Live at matyas--clientsflow-studio-v31-web.modal.run.

4. How to pull safely (your branches are safe)

git fetch never touches your local branches — it only updates the remote-tracking refs. Do it first, then inspect before merging anything.

1. Clone (first time) or fetch (if already cloned)

   # First time:
   git clone https://github.com/matt-clientsflow/clientsflow-studio.git
   cd clientsflow-studio
   
   # Already cloned:
   git fetch --all       # downloads everything — safe, no local changes

2. Confirm your branches are intact

   git branch -a         # list all local + remote branches
   git log origin/dani/work-2026-06-16 --oneline -5    # your latest commits

   Your dani/ branches will appear under remotes/origin/dani/… — untouched.
3. Check out v3.1 (Matyas's latest) to review it

   git checkout v3.1     # or: git switch v3.1

   This is the branch you'll likely base production on.
4. Set up the Python environment

   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt

   You'll also need the Modal CLI: pip install modal and modal token new (ask Matyas for credentials).
5. Run the test suite to verify your baseline

   python3 -m pytest -q   # should be 148 passed / 1 skipped on v3.1

5. Merging strategy (recommended)

You're in charge of the merge. Suggested approach:

1. Create a new production branch off v3.1 — this is your integration target.
   git checkout -b production v3.1
2. Review your dani/work-2026-06-16 commits against v3.1:
   git log v3.1..origin/dani/work-2026-06-16 --oneline
3. Merge (or cherry-pick specific commits) from your branches:
   git merge --no-ff origin/dani/work-2026-06-16
4. Resolve any conflicts, run pytest again, then push:
   git push origin production

6. Deploying to Modal

The app deploys as a named Modal app. The name is set inside modal_app.py — check it matches the slot you want to occupy.

# Deploy from the v3.1 branch (or your merged branch):
python3 -m modal deploy modal_app.py

# Live URL (v31 slot):
# https://matyas--clientsflow-studio-v31-web.modal.run/

The workspace is on the Modal Starter plan — max 8 web functions. Check modal app list and free a slot if needed before deploying a new app name.

7. Secrets / credentials

All API keys live in a Modal secret called studio-secrets (in the matyas workspace). You'll need Matyas to either share the secret or invite you to the workspace. Never commit secrets to the repo.

Key env vars the app expects: GEMINI_API_KEY, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET, ADMIN_PASSWORD, STUDIO_BASE_URL, STUDIO_WEBHOOK_SECRET, MISSIVE_API_KEY, NOTION_TOKEN, DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD.