Carroll Street Café · POS User Guide

Getting Started

First Sale in 5 Steps

Brand new? Follow these steps to go from zero to your first completed sale in under 2 minutes.

1

Open the POS

Type your POS web link into any browser on a phone, tablet, or computer. The PIN screen appears.

2

Enter your PIN

Type the access PIN from your manager and tap Open POS. The default PIN is 1234 — managers should change this before going live.

3

Tap your name

In the dark bar at the top, tap your name (Cashier 1, 2, etc.) so sales are recorded against you.

4

Add items from the Menu tab

Scroll through categories and tap + Add on each item. Items with sizes will ask Small or Large.

5

Confirm and charge

Tap the cart bar at the bottom → View Order → Confirm Sale → 💳 Charge Card Reader (or Mark as Paid (Manual) if no reader is connected).

💡

No card reader yet?

Use Mark as Paid (Manual) — the sale is still saved and appears in reports. Connect the reader later when it's set up.

Web POS

Signing In

The POS uses a shared PIN — no individual accounts needed. Anyone with the PIN can open the till.

What you'll see when you open the POS

☕

Carroll Street Café

Enter your access PIN to open the POS

● ● ● ●

Open POS

No PIN? Contact your manager.

1

Type the PIN

Tap the input field and type the numeric PIN. The digits are hidden for privacy.

2

Tap Open POS (or press Enter)

Wrong PIN? A red error message appears for 3 seconds then clears — just try again.

3

Select your name from the staff bar

The dark bar shows up to 4 cashier names. Tap yours — it turns white to confirm selection. You can switch names between orders at any time.

🔑

Managers: change the PIN before going live

Go to Manage → Change Access PIN. Set something only staff know. The old default 1234 is too easy to guess.

Web POS

Building an Order

The Menu tab shows every available item grouped by category. Adding items is fast — a few taps builds a complete order.

Menu tab — live view

Carroll Street Café

Medgar Evers College · POS System

10:42 AM 🟢

Staff: Maria James Tanya

Menu

Order 2

Reports

Manage

Hot Drinks

☕

Latte

$4.50 / $5.50

☕

Matcha Latte

$5.25 / $6.25

2 items

$9.75

1

Scroll through categories

Items are organised by category — Hot Drinks, Iced Drinks, Herbal Teas, Fresh Juices, Smoothies, Breakfast & Light Bites, Wraps & Sandwiches, Bowls. Scroll down to see all.

2

Tap "+ Add" on an item

Single-price items (like a Muffin) are added instantly. Items showing two prices (e.g. $4.50 / $5.50) will pop up a Small / Large picker — tap your choice.

3

Watch the cart bar at the bottom

Every addition updates the running total and item count live. A toast notification ("Latte added") confirms each tap.

4

Tap "View Order" to review

See all cart items. Use − and + buttons to adjust quantities. Reducing an item to zero removes it. Add an optional order note (table number, customer name, special request).

💡

Order note field

On the Order tab there's a note field at the top. Use it for: "Table 4", "No ice", "Extra hot", or a customer name for pick-up orders.

Web POS

Taking Payment

Once you've reviewed the order, completing the sale is two taps.

1

Tap "Confirm Sale"

On the Order tab, tap the dark Confirm Sale button. A full-screen payment panel slides up showing the total in large text and every item listed.

2

Charge via card reader or mark manual

Reader connected 💚 green dot: tap 💳 Charge Card Reader — the reader activates immediately.

No reader grey dot: button shows Mark as Paid (Manual) — tap it after you've taken payment on your standalone machine.

3

Wait — don't tap anything

The button cycles: Creating payment… → Present card to reader… → Processing… The customer taps/inserts their card on the reader. The POS handles everything automatically.

4

✅ Sale complete

A green success screen appears. Offer to print a receipt or tap Done — No Invoice to start the next order.

⚠️

If the card reader shows an error

No charge was made — it's safe. The payment is automatically cancelled. You can retry straight away, or use a standalone card machine and tap Mark as Paid (Manual) to still record the sale.

Web POS

Printing Receipts

After every completed sale you're offered the option to print a receipt. You can skip it if the customer doesn't need one.

1

Invoice screen appears automatically

You'll see ✅ Sale Complete! with the amount and cashier name.

2

Tap "🖨 Print Invoice"

Your device's print dialog opens. Select your receipt printer. The receipt is formatted cleanly — café name, unique receipt number, date, time, items, total, and "Served by" cashier name.

3

Or tap "Done — No Invoice"

Skips printing and goes straight to Reports where you can see the sale logged.

ℹ️

Receipt number format

Each receipt gets a unique reference like CSC-260418-1042 — useful when a customer queries a charge. CSC = Carroll Street Café, then date, then time.

Web POS

Processing Refunds

Mistakes happen. Any sale from today's log can be refunded with a reason attached.

1

Go to the Reports tab → Sale Log

Scroll down to the Sale Log section. Today's transactions are listed newest first.

2

Tap the red "Refund" button on the sale

Each sale card shows a small Refund button on the right of the cashier name line.

3

Enter a reason and confirm

Type a short reason (e.g. "wrong item", "customer changed mind") and tap Confirm Refund. The negative amount is logged immediately and deducted from net revenue.

⚠️

POS refund = record only

This logs the refund in your sales data. You still need to process the actual money return through your Stripe Dashboard or card machine separately.

Reports

Reading Your Reports

The Reports tab gives you a live dashboard of today's performance. It updates automatically whenever a sale comes in from any device — including the Telegram bot.

💰

Net Revenue

Total income after refunds. Gross revenue and refund total shown underneath.

🧾

Sales Count

Completed transactions today. Refund records are excluded.

🛍

Items Sold

Total individual items across all orders — useful for stock and prep planning.

📊

Avg. Sale

Mean transaction value. Below $7? Consider upsell prompts. Above $12? Customers are ordering multiple items.

What else is in the report?

⏰

Time of Day Analysis

Morning / Afternoon / Evening revenue with bar charts. Shows your peak hour and quietest hour so you can staff appropriately.

🏆

Exporting

📄

Export PDF

Tap ⬇ Export PDF — saves the full report to PDF via your browser. Great for end-of-day records or sending to management.

📊

Export CSV

Downloads a spreadsheet with every sale — time, staff, items, total, notes. Open in Excel or Google Sheets for custom analysis.

🗑

Clear today's data — use with extreme caution

The Clear today's data button permanently deletes all sales from today's database. This cannot be undone. Always export a CSV or PDF first.

Management

Menu & Settings

The Manage tab is for managers. It controls the menu, staff names, the PIN, and the card reader connection. Keep this tab away from regular cashiers.

Adding a New Menu Item

1

Fill in the form at the top of the Manage tab

Enter the item name. Then its small price. If it has two sizes, add the large price in the second box.

2

Choose a category

Select from the dropdown — this determines which section of the menu it appears in.

3

Add a description (optional)

A short line shown under the item name, e.g. ingredients or allergen info.

4

Tap "+ Add to Menu"

The item appears on the menu immediately. Note: menu changes are saved to this device only — add on each device separately.

Editing or Hiding Items

Scroll down in Manage to see the full item list. Tap Edit next to any item to change its name or price. You can also choose to hide it — this removes it from the customer-facing menu without deleting it. Ideal for seasonal items or items that are temporarily out of stock.

💡

Restoring a hidden item

Hidden items appear faded in the Manage list. Tap Show next to it to bring it back on the menu instantly.

Updating Staff Names

Scroll to Staff names. Replace "Cashier 1" etc. with real first names. Tap Save names. The staff bar at the top updates immediately and all future sales are recorded under the correct names in reports.

Changing the Access PIN

1

Scroll to "Change Access PIN" in Manage

Type a new PIN — minimum 4 digits, numbers only.

2

Tap Save

The new PIN is saved to the cloud database. Any device that opens the POS fresh will require the new PIN. Share it with staff via a private message — not on a sticky note!

🔒

Already logged-in sessions stay open

Changing the PIN doesn't log out existing sessions. To force a full logout on a device, close the browser tab on that device.

Telegram Bot

Download Telegram

The Telegram bot lets staff take orders from their personal phone without opening the web POS. All sales sync to the same database in real time. Step one: get the Telegram app.

Windows · Mac · Linux

1

Tap the link for your device above

This takes you to the official Telegram download page. Telegram is completely free.

2

Install and open the app

Tap Get (iOS) or Install (Android) then open Telegram when it finishes.

3

Sign up with your phone number

Telegram asks for your mobile number. Enter it, receive a 5-digit code by SMS, type it in, and you're registered. No password needed.

4

You're in

You'll land on the main chat screen. Now go to the next section to find the café bot.

Telegram Bot

Setting Up the Bot

Once Telegram is installed, connecting to the café bot takes about one minute.

1

Get the bot username from your manager

The bot has a username like @carrollstreetcafebot. Your manager created it and will share the exact name.

2

Search for it in Telegram

Tap the 🔍 Search icon at the top of Telegram. Type the bot's username exactly. Tap the result when it appears.

3

Tap Start

At the bottom of the chat, tap the blue Start button. The bot sends a welcome message and a 🛒 New Order button.

4

Set your name (optional but recommended)

Type staff Maria (replace Maria with your name). This records your name against every sale you process through the bot.

🔒

"Not authorised" message?

Your Telegram ID hasn't been added to the bot's allowed list. To find your ID, message @userinfobot on Telegram — it replies with your numeric ID instantly. Send that number to your manager to be added.

Telegram Bot

Placing Orders via Bot

The bot uses tap-able button menus — no typing needed for orders. Browse categories, choose items, review your cart, and confirm in seconds.

9:41▶ 📶 🔋

☕

Carroll Street Café

● online

Carroll Street Café POS
Welcome, Maria!

Tap New Order to start 👇

🛒 New Order

Select a category:

☕ Hot Drinks

🧊 Iced Drinks

🍵 Herbal Teas

🥤 Fresh Juices

🥤 Smoothies

🍽 Breakfast

❌ Cancel

1

Tap 🛒 New Order (or type /sell)

This clears any previous cart and shows the category buttons freshly.

2

Tap a category

All items in that category appear as buttons, each showing the item name and price.

3

Tap an item

A second row of buttons appears: Small, Large, and ½ Half Price (for student/staff discounts). Tap your choice — it's added to the cart and the cart updates on screen.

4

Keep adding or view the cart

Tap ➕ Add More to go back to categories. Tap 🛒 View Cart to see everything. Use − and + buttons to adjust quantities.

5

Add a discount (optional)

In the cart, tap 🏷 Add Discount. Choose a percentage (5–50%) or a fixed amount (−$1 to −$10). To undo, tap ✖ Remove Discount.

6

Tap ✅ Confirm Sale

The sale saves instantly. A summary appears showing all items, discount (if any), and final total. The sale syncs to the web POS reports in real time.

Telegram Bot

Voice Ordering

Send a voice note and the bot transcribes it. Requires the Groq API key to be configured on the server by a manager.

1

Hold the 🎤 microphone button in Telegram

It's in the message bar on the right. Hold it and speak your order clearly — e.g. "One large latte, one blueberry muffin, two iced matcha".

2

Release to send

The bot replies with "🎙 Transcribing…" then shows what it heard in italics.

3

Confirm using the button menu

Voice shows what was said — then use /sell with the button menu to actually add items and confirm the order. Voice transcription is a reference tool, not an automatic cart builder.

🎙

Tips for accurate transcription

Speak clearly and use exact menu item names — "latte", "matcha", "falafel wrap". The AI works best in English and is trained on café vocabulary.

Telegram Bot

Reports & Commands via Bot

Get a full sales report delivered directly to Telegram — perfect for managers checking performance without opening the web POS.

Type this	What happens
`report`	Full report for today — revenue, items, staff, insights (3 messages)
`report week`	Last 7 days rolling summary
`report month`	Current calendar month summary
`refund 4.50 wrong order`	Logs a −$4.50 refund with reason "wrong order"
`staff Maria`	Sets your name to Maria for this session's sales
`/sell` or `order`	Starts a new order with the button menu
`help`	Shows all available commands with a New Order button
Send a voice note	Transcribes your message (Groq API required)

📊

The report arrives as 3 messages

Message 1 — Revenue, transactions, time-of-day breakdown, hourly chart.
Message 2 — Top items by revenue & volume, slow movers, category chart.
Message 3 — Staff performance, refunds, and smart insights.

Card Reader

Card Reader Setup

The POS integrates with Stripe Terminal — a physical card reader. Customers tap or insert their card directly. This is a one-time manager setup.

🏦

Stripe Account

Sign up at stripe.com. Free to create — you pay a small fee per transaction only.

📡

Terminal Reader

Recommended: Stripe Reader S700 or BBPOS WisePOS E. Both connect via WiFi. Buy from stripe.com/terminal.

🔑

Stripe Secret Key

Found in Stripe Dashboard → Developers → API Keys. Starts with sk_live_. Goes on the bot server as an environment variable.

🌐

Live Bot Server

The bot.js server must be online. The POS calls it to create payments. Hosting options: Railway, Render, Fly.io — all free tiers available.

Setup Steps (Manager only — done once)

1

Register the reader in Stripe Dashboard

Go to Stripe Dashboard → Terminal → Readers → + Add reader. Power on the reader — it shows a registration code on its screen. Enter that code in Stripe. Give it a label like "Carroll Street Counter".

2

Add STRIPE_SECRET_KEY to the bot server

On your hosting platform, go to Environment Variables and add: STRIPE_SECRET_KEY = sk_live_.... Restart the server after saving.

3

Set BACKEND_URL in index.html

Open index.html in a text editor. Find the line near the top of the script:
const BACKEND_URL = '';
Fill in your server URL, e.g. 'https://your-bot.railway.app'. Save the file.

4

Connect the reader from the POS

Log into the POS → Manage tab → Card Reader section → tap Discover Readers. Your reader appears in the list — tap it. The header dot turns green 💚 when connected.

✅

Reconnecting each session

The reader needs to be reconnected each time the POS is opened fresh. It only takes 5 seconds: Manage → Discover Readers → tap your reader. Once connected, it stays connected for the whole session.

Card Reader

Card Payment Flow

Once connected, the reader handles everything. No manual steps — just tap the button and let the customer present their card.

1

Check the green dot in the header

The small dot next to the clock should be green 💚. Tap it to open Manage and connect if it's grey.

2

Build the order and tap Confirm Sale

The payment screen shows the total and all items. The button reads 💳 Charge Card Reader.

3

Tap Charge Card Reader

The reader screen activates. Turn it toward the customer. They tap (contactless), insert (chip), or swipe their card.

4

Reader approves → POS saves automatically

On approval the POS detects it instantly, saves the sale to the database, and shows the invoice screen. No extra tapping needed from you.

💡

Automatic fallback

If the reader disconnects mid-session, the button automatically changes to Mark as Paid (Manual). You can still take payment on a standalone machine and record the sale.

Help

Frequently Asked Questions

Quick answers to the most common questions.

The POS shows a red dot — what does that mean?▼

The red dot means the app can't reach the database. Check your internet connection first. If your connection is fine, the Supabase database may be briefly unavailable — wait a moment and refresh the page. No sales data is lost.

I forgot the PIN. How do I get in?▼

Contact your manager. They can look up or reset the PIN from the Manage tab on a device that's still logged in. If nobody is logged in and the PIN was never changed from the default, try 1234.

I added a menu item but it doesn't appear on another phone.▼

Menu changes are saved to each device's local storage — not to the cloud. To have the same menu on all devices you need to add the item on each one separately. Cloud menu sync across devices is a planned future update.

Can two cashiers use the POS at the same time?▼

Yes — open the POS on as many phones or tablets as you need. Each cashier selects their name. All sales sync to the same database in real time. Any device's Reports tab shows live updates as sales come in from other devices.

A sale went through twice by accident. How do I fix it?▼

Go to Reports → Sale Log, find the duplicate, and tap Refund. Enter "Duplicate sale" as the reason. This logs a negative transaction that cancels it in your revenue totals. If the card was also charged twice, process the card refund separately in your Stripe Dashboard.

The card reader says "Declined" — what do I tell the customer?▼

A decline comes from the customer's bank — not a problem with the POS or reader. Politely ask them to try a different card or payment method. The sale is automatically cancelled on the POS (no charge was made to anyone). You can retry immediately.

The Telegram bot says "Not authorised".▼

Your Telegram chat ID hasn't been added to the bot's allowed list. Message @userinfobot on Telegram — it replies with your numeric ID. Send that ID to your manager. They add it to the ALLOWED_CHAT_IDS environment variable on the bot server and restart it.

How do I update this user guide?▼

This guide is an HTML file stored with the POS files — USER_GUIDE.html. Open it in any text editor (e.g. Notepad, VS Code). Each section has a clear comment label like . Edit the text, save, and refresh the browser. Also update the "Last updated" date at the bottom of the sidebar.

The card reader isn't showing up when I tap Discover Readers.▼

Check: (1) The reader is powered on and connected to WiFi — its screen should show the Stripe logo or idle screen. (2) The reader is registered in your Stripe Dashboard under Terminal → Readers. (3) BACKEND_URL is correctly set in index.html and the bot server is running with STRIPE_SECRET_KEY set.

Reference

Telegram Command Reference

Complete list of every command the bot understands. Any unrecognised message shows a New Order button automatically.

Command	What it does	Example
`/start` or `help`	Welcome message with New Order button	`/start`
`/sell` or `order`	Start a fresh order (clears current cart)	`/sell`
`staff [name]`	Set your name for this session	`staff Maria`
`report`	Today's full sales report (3 messages)	`report`
`report week`	Last 7 days rolling report	`report week`
`report month`	Current calendar month report	`report month`
`refund [amount] [reason]`	Log a refund with reason	`refund 9.50 wrong wrap`
🎤 Voice note	Transcribes audio (Groq API required)	Hold mic, speak clearly

Carroll Street CaféPOS System

First Sale in 5 Steps

Signing In

Building an Order

Taking Payment

Printing Receipts

Processing Refunds

Reading Your Reports

What else is in the report?

Exporting

Menu & Settings

Adding a New Menu Item

Editing or Hiding Items

Updating Staff Names

Changing the Access PIN

Download Telegram

Setting Up the Bot

Placing Orders via Bot

Voice Ordering

Reports & Commands via Bot

Card Reader Setup

Setup Steps (Manager only — done once)

Card Payment Flow

Frequently Asked Questions

Telegram Command Reference

Carroll Street Café
POS System