Kamra is a source-available grocery intelligence and household shopping-planning project. Its MVP household loop is closed: a household can manage Product Groups, Products, and Stock Batches and use target policies to build and apply a Shopping list. The active Phase 1 roadmap makes Product linking, shop-specific list use, receipt/price evidence, and high-volume admin review one coherent experience.
Live deployment: https://www.kamrapp.hu
- Product lookup across grocery stores
- Offer and price comparison
- Household-oriented shopping support
- Admin and ingestion tooling for maintaining the catalog
- Manual crawl review with accepted-row hiding, source filters, paging, and accept/merge confirmation
- User and anonymous preferences for theme and language
- A lightweight, free-tier-friendly deployment model
Kamra is intentionally independent: it does not promote sellers, sponsored rankings, or advertising-driven results.
src/- Angular frontendsrc/app/i18n/- default English and Hungarian locale resources in nested JSON formatapi/- thin Vercel Function entrypointspackages/kamra-api-server/- shared backend and server logicscripts/- local tools for ingestion, seeding, and validationdocs/- product, architecture, and operations notes
Install dependencies:
npm installCommon commands:
npm run dev
npm run build
npm run test
npm run lint
npm run format:check
npm run typecheckFor a one-origin local application with MongoDB managed by Compose:
Copy-Item .env.docker.example .env
docker compose up --buildOpen http://localhost:4200. The first app start waits for MongoDB, then
seeds the local catalogue, admin account, and demo household. The default local credentials are
shown in .env; sign in as admin@example.test, usera, or userb with the configured seed
password. Mongo data is kept in the kamra-mongo-data named volume, so restarting Compose does not
reseed or delete the household.
Stop the services while preserving local data with docker compose down. To deliberately recreate
the disposable database, use docker compose down -v and start Compose again. The Compose MongoDB
service has no authentication and is local-only; never expose it or reuse its defaults in a hosted
environment. Detailed container and deployment guidance is in docs/tech-ops.md.
Useful configured checks:
npm run smoke:catalog
npm run smoke:transactions
npm run seedThe smoke commands require a configured disposable MongoDB environment. They complement the automated specs and the deferred Phase 1 manual acceptance.
- Seed the approved development/demo database and sign in as
usera. - Open Home and inspect the Product Group → Product → Stock Batch hierarchy.
- Create or adjust a target policy, generate a need, choose an active Shop Market, and start a Shopping Trip.
- Resolve or skip matches, record actual bought quantities and dates, add any unplanned purchase, then finalize the Trip.
- As an admin, review the resulting Ingestion Submission without rewriting the household's Product or Batch history.
The accepted household scope and transferred checks are recorded in the archived Stage 8–11 MVP closure runbook. The active direction is the Phase 1 usability plan.
The default seed and smoke scripts are intended for disposable or explicitly approved environments. Do not run data-writing maintenance, archive imports, or reseeds against production without the operator checks documented in the archived MVP operations guide. Raw Crawl Snapshots are preserved as evidence; derived catalogue data may be rebuilt after a verified export.
See SECURITY.md for secrets, household data, and vulnerability reporting guidance, and CONTRIBUTING.md for the small-step implementation and validation workflow.
- Product concept
- Architecture direction
- Tech and operations
- Ingestion operations
- Crawler policy
- Phase 1 roadmap
- Archived MVP operations
- Domain language
Kamra is source-available. See LICENSE.md for the full terms.