Groville

An AI growth agent for Nigerian SMEs. Groville reads a business's website (and Google Search Console), finds the single biggest customer/search gap, drafts the campaign to fix it, and — once the owner approves — runs it and measures what it earned.

Built by The ALPHAs for the NACOS National BuildX hackathon.

The one rule that defines the product (the "honesty boundary"): Groville only ever drafts. The owner reviews and approves. Nothing is ever published or sent automatically, and the Results screen only ever reports what was actually measured — never an invented number.

---

1. What is this repo?

This is the combined (monorepo) for the whole app — both halves live here:

fullnacos_/
├── frontend/   # The dashboard the business owner uses (Next.js)
└── backend/    # The "brain": API + background workers (Flask)

• frontend/ — what the user sees and clicks. Next.js app.
• backend/ — does the real work: stores data, calls the AI, analyses the website, runs approved actions, measures results.

Note on naming: some backend files/README say "Blom" — that's an older name. The product is Groville. Same app.

---

2. How it works (the loop)

Sign up  →  Onboarding (add your website)  →  Groville ANALYSES the site
        →  OPPORTUNITIES (the biggest gaps, ranked)
        →  CAMPAIGN DRAFT (Groville writes the fix)
        →  You REVIEW & APPROVE
        →  Groville EXECUTES the approved action
        →  RESULTS (what it earned) + what it learned

Under the hood:

[ Browser ]  --cookie auth-->  [ Frontend: Next.js :3000 ]
                                      |  (fetch, credentials: 'include')
                                      v
                               [ Backend: Flask :5000 ]
                                /        |            \
                        Firestore   Redis + Celery     Groq LLM
                        (database)  (async jobs:       (text drafts +
                                     analyze /          vision scoring)
                                     execute /
                                     GTM run)
                                         |
                                   Playwright Chromium
                                   (PixelRAG: screenshots
                                    → WebP tiles for GTM)

Alongside the main loop, GTM / PixelRAG (section 5) runs as its own on-demand async job: it screenshots your site + competitors, scores your go-to-market, and drafts a recommendation — and the gaps it finds feed straight back into your Opportunities board.

---

3. Tech stack

Frontend — Next.js 16 (App Router) · TypeScript · Tailwind CSS · shadcn/ui · Framer Motion Backend — Flask · Firebase / Firestore (database) · Redis + Celery (background jobs) · Groq (LLM) Visual GTM (PixelRAG) — headless Playwright Chromium (full-page screenshots + vertical tiling → WebP) · Groq Vision LLM (multimodal scoring of your site vs competitors) Auth — Flask session cookie (the frontend calls the API with credentials: 'include')

---

4. The MVP — what works today

The full demo loop runs end to end on real data:

• ✅ Email/password sign up + login (Flask session cookie)
• ✅ Onboarding → create a business from a website
• ✅ Analyze the website (async, via Celery + Groq)
• ✅ Opportunities — real, ranked customer/search gaps
  • Recovery + re-run: if a user lands on the dashboard without an audit (e.g. they skipped onboarding), they can add a website and run the audit right there (a modal, no need to redo onboarding), or re-run the audit any time from the board. While a run works, the page shows a real in-dashboard "Analysing → Reading your site" state (not a generic loader), and a re-run keeps existing results on screen until the fresh ones arrive.
• ✅ Campaign draft → approve → execute → measure
• ✅ Results — real measurements + learnings
• ✅ Connections — Website (read), Google Search Console (read), GitHub (OAuth)
• ✅ GTM / PixelRAG (newly added — see section 5) — a visual go-to-market audit: Groville screenshots your site and up to two competitors, scores your go-to-market across 4 pillars, names the blind spots, and drafts a recommendation dossier you review. The gaps it finds also flow into your normal Opportunities board.
• ✅ Payments — BMONI sandbox (simulate payment completes the demo)
• ✅ Product tour for first-time users on the Opportunities page

What is simulated (by design, and it's honest about it): Most action executions run in dry-run mode — they do not make a real external change. A completed execution writes one honest signal (execution_success) that shows up on Results. Groville deliberately does not fabricate rich metrics (rankings, clicks, etc.) it can't truly measure — that's the honesty boundary in action.

Not in the MVP (future work):

• Instagram publishing (needs Meta app review — not possible in the hackathon window)
• Real per-channel measurement (beyond the dry-run success signal)

---

5. GTM / PixelRAG — the visual go-to-market audit

This is the newest capability in the app. Everything below is live and merged (backend first, then the frontend surface in PR #20).

What it is

A vision-model audit of your go-to-market surface. Instead of only reading your HTML, Groville looks at your site the way a visitor does — it takes real screenshots, compares them against competitors' screenshots, and scores how clearly you sell. PixelRAG is the screenshot-and-tile engine; the GTM engine is the vision analysis on top of it.

Where to see it

A new GTM item in the dashboard sidebar (between Opportunities and Campaigns), route /gtm. Press Run GTM analysis (enabled once your business has a website), watch the ~90-second progress state, then read the result.

How it works (the pipeline)

POST /api/gtm/run  (202 + run_id)                         [routes/gtm_routes.py]
        │  Celery task: run_gtm_analysis                  [task.py]
        ▼
1. PixelRAG renders + tiles YOUR site        render_and_tile_page  [services/pixelrag_service.py]
2. Discover up to 2 competitors (from GSC)   discover_competitors  [services/gtm_discovery_service.py]
3. PixelRAG renders + tiles each competitor
4. Vision LLM scores you vs them (4 pillars) analyze_gtm_tiles     [agent/gtm_engine.py]
5. The gaps it finds are written as normal OPPORTUNITIES  create_opportunity
6. An executive Markdown DOSSIER is drafted + saved       [services/gtm_dossier_service.py]
7. Run marked `completed`; frontend polls GET /api/gtm/runs/<id> every 15s until done

The 4 GTM pillars (each scored 0–100, plus an overall): above the fold, pricing clarity, social proof, CRO friction.

GTM / PixelRAG "sync" — how it ties into the rest of the app

The important integration point: GTM is not a silo. The opportunities the vision model finds are persisted through the same create_opportunity service the rest of the app uses, so a GTM run also populates your normal Opportunities board (the run records how many it created in opportunities_created_count). The screenshot tiles PixelRAG produces are written under backend/static/tiles/<business_id>/<run_id>/… and the frontend loads them through the existing /api/backend/* rewrite proxy (same first-party-cookie path every other API call uses) — no new auth surface. This alignment of the tile manifest shape, the opportunity store, and the dossier is what the recent "gtm-pixelrag-sync" work locked in.

The data a run returns (what the UI renders)

gtm_scores (the 5 gauges) · blind_spots[] · user_manifest.tiles[] (your site capture) · competitors_analyzed[] (each with domain, url, and manifest.tiles) · dossier_path · opportunities_created_count.

Note: the vision model does reason about competitor strengths/weaknesses internally, but those are not persisted on the run document in this phase — only domain, url, and tiles are. The frontend therefore does not render strength/weakness lists, and the dossier does not depend on them.

Honesty boundary (unchanged, and it matters here)

The dossier is a draft recommendation you read and act on. The UI labels it "Groville's draft recommendation — review before acting." It is never presented as sent, published, or auto-executed. Groville drafts; you approve.

⏱️ Model & capture timeouts (and what "timeout of models" means here)

Two different kinds of timeout matter, plus one model-lifecycle risk:

Where	Setting	Default
PixelRAG page navigation	timeout_ms (Playwright goto, falls back networkidle → domcontentloaded)	15 s
PixelRAG per-tile screenshot	screenshot_timeout_ms	20 s
Frontend per-request fetch (apiFetch + dossier fetch)	AbortController	60 s
Frontend poll cadence / ceiling	every 15 s, up to 40 ticks (~10 min) before giving up
Vision LLM request	Groq default request timeout (not overridden in code)	Groq default

"Timeout of models" / model decommission risk: the vision model id is GROQ_VISION_MODEL (default qwen/qwen3.8-27b). Groq rotates and retires models — the previous default (llama-3.2-11b-vision-preview) was decommissioned, which breaks a run with a model-not-found error until the env var is pointed at a current multimodal model. If GTM runs start failing at the vision step, check this first. (The text LLM used elsewhere is GROQ_MODEL.)

⚠️ Risks & known limitations (read before demoing GTM)

• Tiles are transient. They live on Render's ephemeral disk, which is wiped on every redeploy and is not shared across instances. An older run's screenshots can simply be gone. The UI treats this as best-effort: a broken image is hidden on error, and a run with no tiles shows "Visual capture unavailable for this run" instead of a broken layout. Treat tiles as best-effort, never as durable storage.
• Soft-fail still reports completed. If the browser OOMs, a screenshot times out, or the vision model hiccups, the pipeline keeps going and the run completes with empty tiles and/or flat 50 scores (the clamp default). This is intentional (a run shouldn't hard-crash the loop) — but it means a "completed" run can be visually empty. The UI degrades gracefully; just re-run for a clean capture.
• Render free tier is memory-constrained. Chromium launches with memory-safe flags (--disable-dev-shm-usage — the key OOM fix — plus --no-sandbox, --disable-gpu) and pages are closed/cleaned between captures. Heavy pages were the main source of screenshot timeouts; that's mitigated but not eliminated on the free tier.
• Competitor discovery depends on GSC seed queries. If Search Console isn't connected / has no queries, competitor discovery is weaker, so the comparison is less useful.
• Vision scoring is probabilistic. Scores and blind spots are a model's read of screenshots, not ground truth — present them as guidance, not fact.
• The full completed result view was not exercised end-to-end against a live backend during the frontend build (it was type-checked, linted, built, and verified for its non-ready/empty states). Eyeball a real completed run on a connected deploy before relying on it in a demo.

---

6. Prerequisites (install these once)

• Node.js 20+ and npm
• Python 3.11+ and pip
• Redis running locally on localhost:6379
  • On Windows, use Memurai (a Redis-compatible service)
• A Firebase project + service account JSON (the database is Firestore) — get the JSON file from Felix
• A Groq API key
• A GitHub OAuth app (only needed for the GitHub connection)
• A BMONI sandbox key (only needed for payments) — ask William

---

7. Environment variables — READ THIS CAREFULLY

Secrets are NOT in this repo (they're gitignored). Every teammate creates their own. There are two env files, one per app.

🔑 The golden rule: use localhost EVERYWHERE, not 127.0.0.1

The login uses a session cookie. If the frontend talks to 127.0.0.1:5000 but you open the app at localhost:3000 (or vice-versa), the browser treats them as different sites and drops the cookie → you get logged out / 401 right after login. Keep it localhost on both sides, and in the GitHub callback URL too.

7a. Backend — create backend/.env

There is no example file for the backend, so create backend/.env yourself with these keys:

Variable	What it is
SECRET_KEY	Signs the Flask session cookie. Any long random string.
FIREBASE_CREDENTIALS	Absolute path to your Firebase service account JSON file (get it from Felix).
GROQ_API_KEY	Your Groq LLM API key.
GROQ_MODEL	The text model id, e.g. openai/gpt-oss-20b.
GROQ_VISION_MODEL	The vision model id for GTM / PixelRAG (default qwen/qwen3.8-27b). Point it at a current multimodal model — Groq retires these (see section 5 "Model & capture timeouts").
TOKEN_ENCRYPTION_KEY	Encrypts stored OAuth tokens (a Fernet key).
GITHUB_CLIENT_ID	From your GitHub OAuth App.
GITHUB_CLIENT_SECRET	From your GitHub OAuth App.
GITHUB_REDIRECT_URI	http://localhost:5000/api/connections/github/callback — must exactly match the callback URL set on your OAuth app.
FRONTEND_URL	http://localhost:3000 — where the GitHub callback sends the user back to.
DEBUG	True locally (keeps the cookie non-Secure so it works over plain http).
INSTAGRAM_*	Optional — only for the Instagram connection; not needed for the core demo.

GitHub tip: use an OAuth App (not a GitHub App). OAuth App tokens don't expire and match the code's scope=repo flow. A GitHub App's user tokens expire after 8 hours and cause a "Try again" / 401 on the Connections screen.

7b. Frontend — create frontend/.env

Copy frontend/env.example → frontend/.env and fill it in. (Next.js also reads .env.local if you prefer that name — either works; it's gitignored the same way.) Key values:

Variable	What it is
NEXT_PUBLIC_API_BASE	http://localhost:5000 — the Flask backend. Use localhost (see the golden rule). Leave blank to run the offline "Ada" demo with no real backend.
BMONI_API_KEY	BMONI sandbox payments key. Ask William — never commit it.
BMONI_BASE_URL	https://embedded-dev.bmoni.com (sandbox only).
DEMO_FALLBACK_ACCOUNT	true — shows a labelled placeholder account if BMONI can't issue a real one, so the demo still runs.
CRON_SECRET, BMONI_MERCHANT_PHONE, APP_PUBLIC_URL, NEXT_PUBLIC_SUPABASE_*	Optional — see the comments inside env.example.

⚠️ Never commit .env, .env.local, or the Firebase service account JSON. If you ever paste a key into a chat or a public place, rotate it.

---

8. Running it locally

You'll use up to 4 terminals. Quick guide:

• Just testing login/signup? You only need Flask + Frontend (terminals 4 and 5).
• Testing analyze / approve / execute / results? You need all four (Redis, Celery, Flask, Frontend).

Step 1 — Backend setup

cd backend
python -m venv venv

# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate

pip install -r requirements.txt

Then create backend/.env (section 7a) and make sure FIREBASE_CREDENTIALS points at your real service account JSON.

Step 2 — Redis (terminal 1)

Start Redis (Windows: start Memurai). It must be reachable at localhost:6379.

Step 3 — Celery worker (terminal 2, venv active)

celery -A task worker --loglevel=info --pool=solo

--pool=solo is REQUIRED on Windows — without it Celery crashes with WinError 5.

Step 4 — Flask API (terminal 3, venv active)

python app.py

Runs on http://localhost:5000.

Step 5 — Frontend (terminal 4)

cd frontend
npm install        # required after every pull (deps like framer-motion)
npm run dev

Open http://localhost:3000. 🎉

---

9. Backend API — quick reference

All under cookie auth (credentials: 'include'). Business routes are under /api/business/<id>.

Area	Endpoints
Auth	POST /api/auth/register · login · logout · GET /api/auth/me
Business	POST /api/business · PATCH/DELETE /api/business/<id>
Analyze (async)	POST .../analyze → then poll GET .../runs/latest
Opportunities	GET .../opportunities
Actions	GET .../actions · POST .../actions/<id>/approve · .../reject
Execution	GET .../executions/<id> (poll: queued → running → completed/failed)
Results	GET .../measurements · GET .../learnings
Connections	GitHub: /api/connections/github/connect · callback · repositories; Search Console: /api/connections/search-console/*; Instagram: /api/connections/instagram/*
GTM / PixelRAG (async)	POST /api/gtm/run (→ run_id) · GET /api/gtm/runs?business_id= · GET /api/gtm/runs/<id>?business_id= (poll) · GET /api/gtm/runs/<id>/dossier?business_id= (text/markdown)

---

10. Troubleshooting

Symptom	Fix
Logged out / 401 right after login	You're mixing localhost and 127.0.0.1. Use localhost everywhere (API base, browser URL, GitHub callback).
Celery: WinError 5	Start the worker with --pool=solo.
GitHub connection shows "Try again" / 401	The OAuth token expired or the callback URL doesn't match. Use an OAuth App, set both the app's callback and GITHUB_REDIRECT_URI to http://localhost:5000/api/connections/github/callback, restart Flask, and reconnect.
"No connector available for action type: X"	Make sure the backend is on the latest main (the connector fallback is merged).
Analyze crashes: "Opportunity response must be a JSON object"	The small LLM occasionally returns malformed JSON. Just re-run analyze.
GTM run fails at the vision step (model-not-found)	The vision model was retired by Groq. Set GROQ_VISION_MODEL to a current multimodal model and restart (see section 5).
GTM run shows "Visual capture unavailable" / flat 50 scores	A soft-fail (Chromium OOM, screenshot timeout, or vision hiccup) — the run still completes. Re-run for a clean capture. Old runs may also have lost their tiles on a Render redeploy (ephemeral disk).
GTM screenshots keep timing out on big sites	Heavy pages on Render's free tier. Mitigated by memory-safe Chromium flags + WebP tiling, but not eliminated; re-run, or try on a non-free instance.
Instagram won't publish	Expected — publishing needs Meta app review; not in the MVP.

---

11. Contributing

• Branch off the latest main → open a PR → squash-merge → delete the branch.
• Never commit .env, .env.local, or the Firebase service account JSON.
• Run npm run lint and npm run build (frontend) before opening a PR.

---

The ALPHAs · NACOS National BuildX