SpesaFast help

1 What is SpesaFast

SpesaFast is an Android app built to speed up grocery shopping. It works in three steps: you keep your shopping lists, you draw the map of one or more supermarkets with the shelves and product categories they hold, and when you go shopping the app computes an ordered route that visits every needed shelf once, in the shortest order.

Products added to a list are automatically classified into the right category (e.g. "Dairy", "Produce") by a built-in dictionary that learns from your corrections; optionally, this dictionary can be backed up by an AI engine for products it doesn't recognize (see section 4).

All data — lists, supermarkets, categories — stays saved on your phone. An optional Google Drive backup lets you keep or move it to another device (see the privacy policy).

2 The app's sections

The app is organized into five tabs at the bottom:

2.1 🛒 Shopping

The home screen. You pick the list and the supermarket to use, then tap "Start shopping" to begin the route. During the trip, a mini-map at the top shows where you are and which shelf to reach next; products are checked off as "picked" one by one. If a trip is already in progress, this tab shows a banner to resume or finish it; the tab's icon changes to flag it.

If a product ended up in the wrong category (and therefore the wrong shelf), you can fix it on the spot by tapping the 🏷 button on its row: this opens the category picker, and the route is recalculated when you go back. This correction only applies to the current trip and doesn't change the classification dictionary.

2.2 📋 Lists

The list of shopping lists. You create a list, give it a name, and add products: as you type a name, the app suggests products already used in the past and assigns them to the right category automatically. From here you can also start a shopping trip directly for a given list.

Besides typing products one by one, two shortcuts are available inside a list:

• 🎤 Dictation: speak the list of products out loud (e.g. "milk, bread, tomatoes") and the app recognizes them individually.
• 📷 Import from photo: take a photo or choose an existing image (e.g. a handwritten list or one photographed on a piece of paper), and the app reads its text to extract the products.

In both cases the recognized products are shown in a review list, where you can deselect the ones you don't want before confirming: nothing is added automatically without confirmation. Both features require at least one AI engine (section 4) to be configured, since it's needed to interpret the spoken phrase or the text read from the photo.

If a product's category isn't right, you can change it by tapping ⋮ on its row → Category: on the screen that opens, if an AI engine is configured, a ✨ Suggest an alternative button also appears, which asks the engine for a different category that fits the product (you can tap it again for more suggestions). Unlike the correction made during a shopping trip (section 2.1), a choice made here is also learned as a rule in the dictionary, so next time the product will be classified correctly right away.

2.3 🏬 Supermarkets

The list of saved supermarkets. Tapping a supermarket opens its page with three buttons: Edit (name and address), Shelves (the list of shelves and the categories they hold) and Map (the physical layout of the shelves on the store's floor plan). The full walkthrough is in section 3.

2.4 🏷️ Categories

The tree of product categories used by the app (e.g. the "Dairy" macro-category with sub-categories like "Milk", "Cheese", etc.). You can create new categories, rename them, and change their icon or color. These are the same categories you assign to a supermarket's shelves.

2.5 🛠️ Tools

A settings and tools page, split into blocks:

• Backup and tools: export/import all your data to a file (to keep it or move it manually) and browse the classification dictionary.
• Google Drive backup: optional sign-in with a Google account to save and restore a full backup (see the privacy policy).
• Language and theme: Italian/English and light/dark/automatic.
• AI classification: where you optionally connect the AI engines used to help classify products the built-in dictionary doesn't recognize (see section 4).

3 Setting up a supermarket with its shelves

To get a useful route, a supermarket only needs to be set up once: you create it, define its shelves with the categories they hold, then (optional but recommended) arrange them on the map.

3.1 Create the supermarket

In the Supermarkets tab, tap the ＋ button at the bottom and give the store a name (e.g. "Main Street Supermarket"). Address and notes are optional and can be added later from "Edit".

3.2 Add shelves and assign categories

Open the supermarket and tap Shelves. Use ＋ to add a shelf (e.g. "Dairy", "Frozen", "Checkout"): the name is free text, it only needs to help you recognize it on the map.

For each shelf, tap its categories: choose one or more product categories from those defined in the Categories tab (e.g. the "Dairy" shelf will hold the categories "Milk", "Cheese", "Yogurt"). When a product from one of those categories is on a list, the app will know it's on that shelf.

A shelf can also hold different categories on each of its four sides (Top/Right/Bottom/Left), useful for a double-sided shelf accessible from different aisles; for most cases it's enough to assign categories to the "Whole" side.

3.3 Arrange the shelves on the map

From the supermarket's page, tap Map. It opens read-only, to avoid accidentally moving something while you're just looking at it: tap 🔒 Edit at the top to turn editing on (a Close button turns it off again).

In edit mode, you see a grid representing the store's floor plan: tapping an empty cell places an unplaced shelf there (or use "Auto-arrange" to place them all automatically as a starting point). Tapping an already-placed shelf shows the commands to move, resize or edit it (rename it, change its categories, remove it from the map). The 🔍−/🔍+ buttons control zoom (also available read-only); Col±/Row± change the grid size.

For the app to compute a realistic route, also place the two special markers using the 🚪 (entrance) and 💳 (checkout) buttons — once is enough, in the correct position relative to the shelves.

The map is optional: without it the app still proposes an order to visit the shelves, it just won't draw a step-by-step route on the floor plan.

3.4 Check the result

To check everything is set up correctly, go to the Shopping tab, pick a test list and the supermarket you just configured, then start the trip: the mini-map at the top should show a route connecting the right shelves in the right order.

4 Connecting an AI engine (optional)

The app's built-in dictionary recognizes most common products on its own and learns from corrections. For products it doesn't recognize, you can connect — free of charge — one or more external AI engines that suggest the right category. This isn't required to use the app: it's an extra aid.

They're configured from the Tools → AI classification tab, by entering an "API key" (a string of characters that identifies your account with the service) in the relevant field and tapping Save. The Test button immediately checks that the key works. If more than one engine is configured, the app tries them in the order Aigway → Gemini → Groq, moving to the next one only if the previous one is unavailable or finds no category.

4.1 Generate a Gemini (Google AI) API key

1. Open aistudio.google.com/app/apikey from your phone's or computer's browser.
2. Sign in with a Google account (the same one or a different one — it's not tied to the account used for the Drive backup).
3. Tap Create API key, choosing or creating a project if asked.
4. Copy the generated key (a string starting with AIza…).
5. In SpesaFast: Tools → AI classification → Gemini → API key, paste it and tap Save, then Test to verify.

Gemini's free tier has a daily request limit more than enough for personal use of the app, and it doesn't require a credit card.

4.2 Generate a Groq API key

1. Open console.groq.com in your browser and create a free account (or sign in with an existing Google/GitHub account).
2. In the side menu, open API Keys.
3. Tap Create API Key, give the key any name you like (e.g. "SpesaFast") and confirm it.
4. Copy the key shown right away: Groq only displays it in full once.
5. In SpesaFast: Tools → AI classification → Groq → API key, paste it and tap Save, then Test to verify.

Groq's free tier doesn't require a credit card and allows a number of daily requests more than enough for personal use of the app.