SPARko

AI-powered digital catalog assistant for SPAR

SPARko turns a printed promotional leaflet into an interactive shopping experience. Ask in plain Slovenian, get verified prices, build your own catalog and jump straight from the conversation to the exact product in the original leaflet.

---

What is SPARko?

SPARko is a mobile-first prototype of a conversational shopping assistant built on top of two real promotional catalogs: SPAR 41/26 (36 pages) and INTERSPAR 14/26 (8 pages), with 164 verified products, both valid 7.–13. 10. 2026.

Instead of flipping through 44 pages of PDFs, shoppers talk to Sparko: they ask what something costs, what's discounted, what to cook, or what fits a budget. Every answer is backed by structured catalog data, every product can be saved to a personal Moj katalog, and every product links back to its exact spot in the original leaflet.

Why SPARko is different

This is not a chatbot placed next to a PDF. The assistant, the structured catalog data and the visual leaflet are wired together.

Ask: "Koliko stane Nutella?"

→ Sparko answers with a verified product card: SPAR · Ferrero Nutella, 1 kg, 7,19 € (SPAR plus), PDF page 1 → One tap saves it to Moj katalog → "Poglej v SPAR katalogu" opens the original leaflet (SPAR or INTERSPAR) on the right page, with the product visually highlighted

The language model writes the sentence. It never decides the price.

Key features

Natural Slovenian conversation	Free-form questions with contextual follow-ups and suggested next questions
Verified catalog pricing	Prices, package sizes, discounts and validity dates come from the catalog data, not from the model
Two catalogs, one app	SPAR 41/26 and INTERSPAR 14/26; every product, row and card carries a SPAR / INTERSPAR label
Home (Domov)	Full (uncropped) catalog cover cards, a Katalogi / Izdelki toggle (Izdelki opens on VSI, then Zajtrk, Pekovsko pecivo, Večerja, Osnovna živila, Mlečni izdelki …), quick actions (Kaj je najbolj znižano, Poglej izdelke po kategoriji → category sheet, Kaj je novega v katalogu, Kje je najbližji SPAR). Top list and bottom rail share one state; the middle section never moves
Current vs. upcoming discounts	"Kaj je najbolj znižano?" shows only currently valid discounts. Timing questions ("Kdaj bo izdelek najbolj znižan?" → "Za kateri izdelek …?", "Kdaj bo skuta v akciji?") show Znižano ta teden plus the upcoming week; every simulated future offer is marked Demo napoved
Moj katalog	Compact list of saved products (removal mode behind the trash icon), Pokaži na letaku, Deli seznam and a green Priporočila zate band with explained recommendations
Leaflet navigation	Jump from any product to its exact location in the original SPAR or INTERSPAR leaflet (/letak?katalog=…)
Product highlighting	164 verified products are tappable on the leaflet pages (incl. the whole SPAR cover: Svinjska rebra, Radler …); save/remove there too
Recipes & budget ideas	Verified recipes built from leaflet products and budget-aware shopping suggestions
Typo & morphology tolerance	Handles Slovenian inflection and misspellings (skuto, skute, skta …)
Persistent state	Saved products and conversations survive a page reload
Responsive, mobile-first UI	Designed for phones first, works on desktop
Live AI + limited fallback	If the model is unavailable, search, product cards, saving, recipes and the leaflet keep working

AI + verified catalog data

SPARko separates conversational AI from trusted catalog facts.

• The model (Anthropic Claude, server-side only) interprets the question and writes a short natural-language reply.
• Prices, package sizes, discounts, dates, totals and catalog pages are inserted from src/data/catalog.json, never generated.
• Model output is validated against a schema; it may only reference product IDs that the deterministic search actually retrieved.
• Responses that try to invent a price or falsely claim a product was saved are rejected, and SPARko falls back to a clearly labelled limited mode answer.
• Saving, removing and navigating are application actions; clicking a product never needs the model.

API keys stay on the server. No AI keys are exposed to the browser.

More detail on the data pipeline: docs/DATA.md · full QA log: planning/QA-REPORT.md

Quality

Check	Result
Data validation	✅ PASS (2 catalogs, 164 products / offers / placements, 44 pages, 3 recipes, 10 mocked future promos)
TypeScript typecheck	✅ PASS
Lint	✅ PASS
Unit tests (Vitest)	✅ 301 / 301
E2E tests (Playwright)	✅ 115 / 115
Production build	✅ PASS
Browser-exposed AI keys	✅ 0

Responsive layout checked at 360 / 390 / 430 px and desktop.

Tech stack

• Next.js 16 (App Router) · React 19 · TypeScript
• Anthropic SDK (Claude) for the conversational layer
• Zod for schema validation of catalog data and model output
• Vitest (unit) · Playwright (E2E) · ESLint
• Deployed on Vercel

Run locally

Requires Node.js ≥ 20.9.

npm ci
npm run dev        # http://localhost:3000

Without any environment variables SPARko runs in limited mode (deterministic search, product cards, Moj katalog, recipes and the leaflet all work). To enable live AI, copy .env.example to .env.local and set:

Variable	Purpose
ANTHROPIC_API_KEY	Server-side key for live AI answers
AI_MODEL	Optional model override (default claude-haiku-4-5)
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN	Persistent rate limiting, required for live AI in production
ALLOW_UNLIMITED_AI	true enables live AI in production without rate limiting (private demos only)

Reviewer access (login)

The whole app (pages, /api/*, leaflet pages and product photos) is behind individual accounts: each reviewer gets a one-time activation link plus a personal username and password, bound to exactly one browser (installation/profile). State (accounts, browser bindings, visit counts) lives in Upstash Redis; sessions last 24 hours. Authentication fails closed: without the store and SPARKO_AUTH_SECRET nobody can sign in.

Required: UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN (or KV_REST_API_URL / KV_REST_API_TOKEN) and SPARKO_AUTH_SECRET (at least 32 random characters). Optional: SPARKO_PUBLIC_URL, SPARKO_STORE_PREFIX.

npm run auth:provision -- create --reviewer <username> --admin <admin> --base-url https://<deployment> --env-file .env.local
npm run auth:provision -- status --env-file .env.local

Generated passwords and links are written only to .secrets/ (git-ignored), never printed. Admin operations live at /skrbnik. Setup, distribution, admin operations and the security limitations are in docs/ACCESS.md.

Other scripts: npm run build, npm run lint, npm run typecheck, npm test, npm run test:e2e, npm run validate:data.

Demo (mocked) data

Everything printed in the two leaflets is verified catalog data. Two things are explicitly mocked for the demo and are labelled as such in the data files:

• Future promos (src/data/future-promos.json, "mock": true): 10 invented promotions for 14.–20. 10. 2026 that feed Znižano naslednji teden. They are not from any leaflet; the current price always comes from the verified offer.
• Demo forecast (src/lib/demoForecast.ts): every verified product can be answered with "Naslednji teden", labelled Demo napoved. Without a structured promo above, no future price or percentage is shown.
• Demo date (src/lib/promoCalendar.ts): when the real date is outside the catalog validity, the demo treats the catalog week (from 7. 10. 2026) as "this week".
• "Novo" flags: 2 products carry a printed NOVO badge (printed_badge); 6 more are demo_editorial picks chosen by the authors and are not claimed by the leaflet.

Details and validator rules: docs/DATA.md.

Project status & disclaimer

SPARko is an independent prototype / showcase implementation, not an official SPAR product. It uses SPAR Slovenija and INTERSPAR leaflets (SPAR 41/26, INTERSPAR 14/26, 7.–13. 10. 2026) as demo data; prices and dates reflect that leaflet, not current in-store prices. SPAR and related brand names belong to their respective owners.