evara — ai-native marketing & intelligence for f&b

brief about the idea · react client + production api

---

repository map

surface	path	role
web client	frontend/	react dashboard & flows against the api
api	backend/api/	fastify service: ingestion, normalization, llm pipelines, frameworks, jobs, alerts-ready automation

---

problem statement

pain	what operators experience	why it hurts
platform dependence	most discovery happens on google maps, instagram, and aggregators like zomato / swiggy — but there is no shared playbook per channel	spend rises while message stays generic
competitor opacity	nearby brands look “busier” or better rated; why is unclear	copying the wrong tactic burns margin
data overload, zero motion	reviews, ratings, and social chatter exist in fragments	almost impossible to turn raw text into next week’s actions
manual marketing	promos, captions, and campaigns are inconsistent and guess-based	teams react late; winners compound small advantages daily

consequences (industry narrative)

signal	typical interpretation (not a guarantee for any one venue)
revenue leakage	operators under-optimize discovery and repeat purchase — decks often cite ~30–40% “left on the table” when positioning and ops are misaligned
survival curve	high early churn in food — narratives often cite ~60% of restaurants struggling in the first ~3 years without disciplined marketing + ops feedback loops

use these figures in pitches as directional industry framing, not as promises baked into the software.

---

who is it for?

persona	situation	what they need
independent owners & cloud kitchens	uneven visibility; lean marketing headcount	repeatable digital rhythm without hiring a full analytics team
multi-outlet brands & growing chains	every location has its own reviews and competitors	structured competitor and sentiment intelligence that scales
marketing teams & food / beverage agencies	too many tabs, too few defensible insights	automated campaign scaffolding and data-backed proof for clients

---

main outcomes for the user (what “good” looks like)

outcome	mechanism (product)	deck-style uplift (directional)
sharper competitive positioning	hyperlocal benchmarking + framework outputs (where data exists)	decks often target ~2–3× clarity vs guessing from screenshots alone
revenue & margin discipline	tie fixes to themes in reviews + prioritized recommendations	literature commonly cites ~5–40% upside bands when positioning and retention improve — your mileage varies
marketing efficiency	fewer one-off brainstorms; more prompts grounded in customer language	less time per campaign cycle
social traction	captions, ideas, and automations derived from trend + sentiment signals	teams often aim for up to ~2× engagement lift when content matches proven themes
less manual grind	pipelines + queues handle heavy fetch and nlp	planners focus on approval, not copy-paste
better acquisition	messaging aligned to high-intent complaints and praise	fewer wasted promos

---

our solution (what feels new or better)

pillar	what evara does	why it beats “another dashboard”
framework-driven intelligence	turns reviews + social signals into swot, pestel, bcg matrix, and 4ps (marketing mix) via dedicated routes and workers — not only charts	leadership gets strategy language, not only star averages
hyperlocal competitor lens	compares you to nearby competitive reality (where scrape + profile data support it)	benchmarks match who actually steals your walk-ins
end-to-end decision support	moves from signal → insight → recommendations → optional automation (e.g. instagram-oriented flows)	fewer dead-end reports
execution-ready marketing	surfaces content ideas, captions, hashtags, and weekly-style plans driven by live context	marketing ships, not just reads
action over noise	prioritizes short, owned recommendations (menu, pricing, delivery, service)	dense pdf syndrome goes away

---

unique selling points (usps)

product & ai

id	usp	implemented / anchored in repo
p1	multi-source aggregation — google, zomato, swiggy, instagram, reddit (canonical Platform types + apify normalisation)	backend/api/src/types, services/apify/*, scraping routes
p2	llm-backed nlp layer — sentiment, topics, trend-style extraction, structured json contracts	services/ai/*, callGeminiJSON in config/gemini.ts
p3	hyperlocal competitor benchmarking — compare performance vs proximate competitors when data allows	competitor + analytics handlers (extend per your geo rules)
p4	recommendation & decision engine	services/ai/recommendationEngine.ts, recommendations routes
p5	confidence scoring — blends sample size, recency, and model certainty	services/ai/confidenceScoring.ts
p6	evidence-first frameworks — swot / pestel / bcg / 4ps prompts ask for mentions and confidence, not vibes	services/ai/frameworkEngine.ts, routes/frameworks/*
p7	monitoring & alert hooks	sentiment spikes, rating drops, competitor moves — wire to your notification channel; workers + ws patterns exist for long jobs

engineering trust

id	usp	why teams bet on it
e1	zod-validated env	bad deploys fail loud
e2	redis + bullmq	user clicks stay fast; heavy work is async
e3	budget caps (MAX_SCRAPE_BUDGET_USD, AI_MONTHLY_BUDGET_USD)	cost discipline by design
e4	structured logging	ops can trace failures

---

user flow (end-to-end)

stage	actor / system	what happens
1 — capture	owner / system	restaurant name, location, links, category (and optional keywords, e.g. reddit)
2 — validate	api	system validation → extract stable ids → persist profile
3 — ingest	apify + integrations	pull zomato, google maps, instagram, reddit (and swiggy where configured) into a single normalized store
4 — refine	workers / agents (logical)	dedupe, spam filtering, canonical review rows
5 — analyze	gemini pipelines	sentiment, topics (food, service, delivery, price…), trend hints, competitor gaps
6 — strategize	framework engine	swot, pestel, bcg, 4ps outputs cached per restaurant
7 — recommend	recommendation layer	ranked actions (menu, pricing, delivery, service…)
8 — execute	automation + client	instagram content packs, weekly plans, optional simli video agent flows
9 — observe	dashboard (frontend/)	heatmaps, competitor panels, trend charts
10 — alert	(your channel)	spikes / drops trigger playbooks

---

impact metrics (what investors & operators track)

treat the numeric bands as north-star ranges from typical food / beverage + growth literature and your pitch deck — not automated guarantees from this codebase.

lever	indicative range	how evara supports measurement
customer acquisition	40–60% uplift narratives in strong ai-marketing case studies	tie campaigns back to tracked links + promo codes in your ops
revenue / positioning	25–40% bands appear in positioning case studies	before/after same-store metrics
marketing efficiency	30–50% less effort when automation covers drafts	time logs per campaign
social engagement	~2× on reach / likes / shares when creative matches extracted topics	native analytics + our content hooks
ratings & sentiment	20–30% improvement stories after sustained fixes	rolling review scrape + sentiment dashboards
competitive rank	track local rank vs chosen peer set	competitor analytics routes

---

tech stack (truthful to this repo)

layer	technology
frontend	react, typescript, vite, tailwind — frontend/
api	node.js, fastify, typescript — backend/api/
database	postgresql via supabase
queues / cache	redis, bullmq
scraping	apify actors + normalisers
ai	google gemini (gemini-2.5-flash, text-embedding-004) — server-side @google/generative-ai

your architecture diagrams may show langchain / openai / claude; this branch’s api path is gemini-first with room to add more providers behind the same route patterns.

---

quick start

step	command	prerequisite
api	cd backend/api && npm install && npm run dev	.env from .env.example — supabase, redis, GEMINI_API_KEY, optional apify / instagram
client	cd frontend && npm install && npm run dev	node 18+; point env at your api base url

---

license

package	pointer
frontend/	frontend/package.json, frontend/README.md
backend/api/	backend/api/package.json

---

we don’t just analyze restaurants — we help them grow smarter, faster, and more profitably.