CityPulse takes one master ad and automatically tailors it for every city where it runs.
- You upload your master ad and pick a business category.
- CityPulse computes the Brand DNA (palette, tone, master copy, call to action).
- For each Romanian city it scores how unusual the local situation is compared with that city's own normal: weather, events, holidays and search trends.
- Cities with a high score get a new AI-generated visual and new copy. Medium cities get new copy only. Quiet cities keep the master ad.
- The tailored ad is checked against advertising rules, composed into a finished ad (photo + headline + body + button), and exported as a PNG.
There is also a TikTok feature that turns a product link or photos into short vertical videos.
- How it decides what to generate
- Architecture
- Project structure
- Requirements
- Setup and running
- Environment variables
- API reference
- Using the app
- Troubleshooting
- Data sources and limits
Each city gets a score from 0 to 100 made of signals. Every signal adds "strength" points, and the total decides the action:
| Score | Action | What happens |
|---|---|---|
| 60 and above | GENERATE |
New AI image and new copy |
| 30 to 59 | LIGHT_TOUCH |
New copy only, master image kept |
| below 30 | SKIP |
Master ad kept, nothing generated, $0 |
The thresholds live in backend/services/signals.py (THRESHOLDS) and are mirrored in frontend/src/lib/citypulse/config.ts. Keep both in sync.
Signals are judged against the city's own normal, not against other cities:
| Signal | Source | How it is made relative |
|---|---|---|
| Weather | Open-Meteo forecast | Compared with the same time of year over the last 3 years in the same city (Open-Meteo archive). Normal weather scores 0. Heat, unusual cold and unusually rainy days score by how far they are from that city's normal. Severe storms always count. |
| Search trends | Google Trends (per county) | Only the change versus the city's own recent history counts, not total search volume. |
| Events | data/ro_events.json |
Each event's relevance is compared with that city's usual events, pulled toward the pool of all events (the file is small). |
| Holidays | data/ro_holidays_namedays.json |
Fixed strength for upcoming public holidays. |
If the climate baseline cannot be downloaded, the weather signal falls back to fixed absolute rules.
┌──────────────────────────── Browser (Next.js, port 3000) ────────────────────────────┐
│ Landing → Upload master ad → Dashboard (heatmap + signal feed + Ad Studio) │
│ │
│ lib/citypulse/api.ts talks to the backend (or built-in mock data) │
│ lib/citypulse/render-ad.ts draws the finished ad on a canvas: preview + PNG export │
└──────────────────────────────────────────┬───────────────────────────────────────────┘
│ JSON / multipart over HTTP
┌──────────────────────────────────────────▼───────────────────────────────────────────┐
│ FastAPI backend (port 8000) │
│ │
│ POST /api/brand upload → Brand DNA (palette, tone, master copy, CTA) │
│ POST /api/cities per-city score, signals, action, motif, default copy │
│ POST /api/generate-ad city-specific copy (Gemini, rule-based fallback) │
│ POST /api/generate-ad-image edit/re-imagine the master image (Gemini image model) │
│ POST /api/compliance advertising-rules check + auto-fix │
│ /api/video/*, /api/tiktok/* TikTok video feature │
└───────┬──────────────────┬───────────────────────────┬───────────────────────┬───────┘
│ │ │ │
┌────▼─────┐ ┌─────▼───────┐ ┌──────▼───────┐ ┌──────▼──────┐
│Open-Meteo│ │Google Trends│ │ data/*.json │ │ Gemini API │
│ forecast │ │ (pytrends) │ │ cities, │ │ copy + image│
│ + archive│ │ per county │ │ events, │ └─────────────┘
└──────────┘ └─────────────┘ │ holidays, │
│ ad rules │
└──────────────┘
- Upload →
POST /api/brandreads the image with Pillow, extracts a palette, guesses the tone from the main colour, and returns the master headline, body and CTA for the chosen category. The browser keeps the uploaded image as a local object URL. - Dashboard →
POST /api/citiesbuilds one result per city: weather (forecast + climate baseline), events, holidays and search trends are turned into signals, summed into a score, and mapped to an action and a motif (storm,heat,festival,greeting,plain). - Ad Studio (click a city):
POST /api/generate-adwrites tailored copy with Gemini. Rule-based copy is the fallback.POST /api/generate-ad-image(only when the action isGENERATE) sends the master image plus brand DNA and local signals to Gemini's image model and gets back a re-imagined visual with related elements. The image comes back inline as a base64 data URL and is also cached inbackend/storage/ads/.- If Gemini fails (missing package, quota, refusal), a local Pillow effect (colour tint plus a motif overlay) is used and the UI shows a yellow note with the reason.
POST /api/compliancechecks the copy againstdata/ro_ad_rules.jsonand auto-fixes or blocks claims such as "cel mai bun" or "garantat".
- Compose and export → the browser draws the photo, a dark gradient, the headline, body text and a brand-coloured button on a canvas. The same function renders the on-screen preview and the downloaded PNG (Instagram feed 1080×1080, Instagram story 1080×1920).
- Text is drawn by the app, never by the image model. Image models misspell text, especially Romanian diacritics, so the prompt forbids text and
render-ad.tsadds it. - Graceful fallbacks everywhere. No Gemini key, no Google Trends, or no climate data: the app still runs and tells you what is missing.
- Export is client-side. It works from the preview image, needs no extra request, and also works in mock mode.
- Caching. Weather is cached 15 minutes, climate normals 24 hours, Google Trends 6 hours (also saved to
backend/storage/trends_cache.json), generated images by a hash of image + prompt.
.
├── backend/
│ ├── main.py FastAPI app, CORS, router registration
│ ├── run.py Start script (uvicorn with reload)
│ ├── config.py Settings read from the root .env
│ ├── routes/
│ │ ├── brand.py POST /api/brand
│ │ ├── cities.py POST/GET /api/cities
│ │ ├── ad.py POST /api/generate-ad
│ │ ├── ad_image.py POST /api/generate-ad-image
│ │ ├── compliance.py POST /api/compliance
│ │ ├── export.py POST /api/export (legacy, returns a file name)
│ │ ├── status.py GET /api/status, /api/events/{city}
│ │ ├── video.py, tiktok.py, studio.py TikTok feature
│ ├── services/
│ │ ├── signals.py Scoring: weather, climate baseline, trends, events, copy
│ │ ├── compliance_rules.py Ad-rule checker
│ │ ├── firefly.py, elevenlabs.py, product.py, tiktok.py
│ ├── video/ Video pipeline (script, scenes, render, jobs)
│ └── storage/ Generated files (served at /media), trends cache
├── ml/
│ ├── signals/ Open-Meteo, events, Google Trends helpers
│ ├── agent/decide.py Local-context lookup and Gemini insight agent
│ ├── brand_dna/ Palette, tone, typography helpers
│ └── compliance/ Compliance checking helpers
├── data/ ro_cities, ro_events, ro_holidays_namedays, ro_ad_rules
├── contracts/ JSON shape contracts between frontend and backend
├── frontend/src/ Next.js app
│ ├── app/ Next.js app router (layout, page)
│ ├── components/citypulse/ Landing, upload, dashboard, heatmap, ad-studio, ad-preview
│ └── lib/citypulse/ api.ts, types.ts, config.ts, render-ad.ts, mock-data.ts
├── requirements.txt Python dependencies
├── .env.example Template for the root .env
└── RUN.md Short run notes
- Python 3.10 or newer
- Node.js 18 or newer and npm (or pnpm)
- A Gemini API key for tailored copy and AI images. The app runs without it, using the fallbacks above.
- Billing enabled on the Google project if you want real AI image generation. Image models are usually not part of the free tier, and you will see
429 RESOURCE_EXHAUSTEDwithout it. - About 1 GB of free disk space for the Python environment.
You need two terminals: one for the backend, one for the frontend.
cd path/to/projectIf the folder name contains spaces or parentheses, put the path in quotes.
cp .env.example .envOpen .env in the repo root (next to requirements.txt) and set at least:
GEMINI_API_KEY=your_key_here
No quotes and no spaces around =. See Environment variables for the rest.
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python3 -m pip install -r requirements.txt
python backend/run.pyThe API runs at http://localhost:8000, with interactive docs at http://localhost:8000/docs.
On macOS with Homebrew Python you must use a virtual environment, otherwise pip reports externally-managed-environment.
Lighter install (if disk space is tight). The server does not import scikit-learn or scipy, so this is enough for the image feature:
python3 -m pip install --no-cache-dir fastapi uvicorn python-multipart Pillow python-dotenv httpx google-genai anthropic beautifulsoup4 imageio-ffmpeg
python3 -m pip install --no-cache-dir pytrends # optional: live Google Trends signalEvery time you open a new terminal, run source .venv/bin/activate before python backend/run.py.
cd frontend/src
npm install # or pnpm install
npm run devThe app runs at http://localhost:3000.
The frontend reads the API address from frontend/src/.env.local:
NEXT_PUBLIC_CITYPULSE_API_URL=http://127.0.0.1:8000/api
Set it to an empty string to run on built-in mock data with no backend. In mock mode there is no AI image and no live signals, but the preview and export still work.
http://127.0.0.1:8000/api/healthshould return{"status":"ok"}.http://127.0.0.1:8000/api/statusshould show"gemini": true. If it showsfalse, the key was not loaded: check the file location and restart the backend.- The backend terminal prints a line like
ad image ready: ... (gemini, 240 KB)after every generated image.
All backend variables go in the root .env. The file is read when the backend starts, so restart after changing it.
| Variable | Required | Purpose |
|---|---|---|
GEMINI_API_KEY |
Recommended | Tailored copy and AI image generation |
GEMINI_MODEL |
No | Text model for copy (default set in code) |
GEMINI_IMAGE_MODEL |
No | Image model (default gemini-2.5-flash-image) |
ANTHROPIC_API_KEY, CLAUDE_MODEL |
Video feature | Claude writes the TikTok video scripts |
TICKETMASTER_API_KEY |
No | Has no effect for Romanian cities |
CITYPULSE_LIVE_TRENDS |
No | 1 (default) uses Google Trends, 0 skips it |
CITYPULSE_DEMO_EVENTS |
No | 1 also shows demo events re-dated to the next weekend |
ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID |
Video feature | Voiceover |
FIREFLY_CLIENT_ID, FIREFLY_CLIENT_SECRET |
Video feature | Adobe Firefly 9:16 expand |
TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET, TIKTOK_REDIRECT_URI |
Video feature | TikTok posting |
FRONTEND_URL, CORS_ORIGINS |
No | Extra allowed frontend origins |
PUBLIC_BASE_URL, STORAGE_DIR, REDIS_URL, MAX_PARALLEL_JOBS |
No | Infrastructure options |
Never commit the real .env file.
All routes are under /api and the backend allows localhost:3000 and localhost:5173 by default.
| Method and path | Body | Returns |
|---|---|---|
GET /api/health |
none | {"status":"ok"} |
GET /api/status |
none | Which integrations are live |
GET /api/cities |
none | Every supported city (id, name, county, lat, lon) |
POST /api/cities |
{cities: string[], category} |
One result per city: score, action, signals, reason, motif, headline, body, compliance, cost |
GET /api/events/{city_id} |
none | The city's upcoming events |
POST /api/brand |
multipart: file, category |
Brand DNA: name, swatches, tone, master copy, CTA |
POST /api/generate-ad |
{city, brand} |
Tailored headline, body, motif, reason |
POST /api/generate-ad-image |
multipart: file, city (JSON), brand (JSON), force |
{imageUrl, imageData, source, detail?}. source is gemini, cache, local, fallback or skipped. |
POST /api/compliance |
{city, headline, body, draft, edited?} |
`{status: passed |
POST /api/video/jobs |
multipart: link or images | TikTok video job |
GET /api/video/jobs/{id} |
none | Job status and variants |
Generated images and videos are served from /media.
- Open http://localhost:3000 and start from the landing page.
- Upload your master ad (PNG, JPG or WebP, up to 10 MB) and choose a business category and the cities to cover.
- The dashboard shows a heatmap of Romania with a score for each city, plus a live signal feed. "Simulate event" lets you inject a fake event to see the scores react.
- Click a city. The Ad Studio shows:
- Master tab: your uploaded ad.
- Tailored tab: the composed ad with the new visual and copy.
- "Why this ad" explains which signals caused it. A yellow note appears if the AI image fell back to the local effect.
- The compliance status. Copy that is Held back cannot be exported.
- Use Regenerate for a new image and copy (this is the only action that spends image-generation tokens again), Edit copy to change the text (the rules are re-checked), and Export to save a PNG:
- Instagram feed, 1080 × 1080
- Instagram story, 1080 × 1920
- Post opens the TikTok studio page with your image attached.
| Problem | Cause and fix |
|---|---|
No module named 'google' |
The backend is not running in the environment where google-genai is installed. Activate .venv and run python3 -m pip install google-genai, then restart. |
error: externally-managed-environment |
Homebrew Python. Use a virtual environment (see Setup). |
No space left on device during install |
Free disk space (delete old project copies, empty the Trash, python3 -m pip cache purge) and use the lighter install. |
429 RESOURCE_EXHAUSTED |
The Google project has no quota for image generation. Enable billing for the project. Until then the local effect is used. |
/api/status shows "gemini": false |
The key is not in the root .env, or the backend was not restarted. |
| Image looks like only a tint plus dots | That is the local fallback. Read the yellow note under "Why this ad" for the reason. |
| Tailored image never changes | Only cities with a score of 60 or more (GENERATE) get a new image. Pick a high-score city and press Regenerate. |
| Export button disabled | The copy is Held back by the compliance check. Edit the copy and save. |
| First dashboard load is slow | The backend is downloading each city's seasonal normals and Google Trends data. Both are cached afterwards. |
| No search signal for a city | Google blocked Trends requests. The last real data (up to 7 days old) is reused, otherwise the city simply has no search signal. |
| Frontend cannot reach the API | Check that the backend is running on port 8000 and that NEXT_PUBLIC_CITYPULSE_API_URL is correct. Restart npm run dev after editing .env.local. |
- Weather: Open-Meteo forecast and archive APIs. No key needed.
- Events: a hand-curated list in
data/ro_events.jsonwith source links. Ticketmaster has no events in Romania, so the key has no effect there. - Search interest: Google Trends through
pytrends, queried per county. Cached for 6 hours. - Holidays and name days:
data/ro_holidays_namedays.json. - Advertising rules:
data/ro_ad_rules.json, checked bybackend/services/compliance_rules.py. This is a helper, not legal advice. - Cost model: each action has an estimated cost and time saved (
GENERATE$0.14 and 45 minutes,LIGHT_TOUCH$0.03 and 20 minutes,SKIP$0). These numbers are estimates used for the dashboard stats, not billing data.