#Admin — User & Beacon Management

If the Dashboard is the bridge, this is the engine room. Here's where you actually manage the people, devices, and data that make up your ambientChat deployment.

#What It Does

The Admin Console goes well beyond a dashboard. It provides full management capabilities for user accounts, beacon infrastructure, billing oversight, scan pipeline monitoring, chat auditing, and system diagnostics. Every section has search, filtering, and the ability to take action — not just look at numbers.

This guide covers the operational sections of the admin console: the places where you do things rather than just observe them.

#How to Use It

#Web

The operational web admin screens below live in the superuser-only Admin section of the web interface, namespaced under /admin/*.

#User Management

Finding users:

  1. Go to the Users section from the sidebar
  2. Use the search bar to find users by name, email, or user ID
  3. Results appear as a list with key details: name, email, subscription tier, last active date

User detail view:

Click any user to see their full profile:

  • Account info — email, sign-in provider, account creation date, last login
  • Subscription tier — Free, Standard, Premium, or Max
  • Billing status — active subscription, billing exempt, credits remaining
  • Usage metrics — chat messages, scans, storage used
  • Role — regular user, brand admin, or superuser

Managing user billing:

Navigate to a user's billing detail view to see:

  • Current subscription tier and renewal date
  • Credit usage history
  • Whether the user is billing-exempt (superusers, partners)
  • Ability to adjust tier or exemption status (superuser only)

#Billing Administration

The Billing section provides the financial overview:

  • Revenue tracking — subscription revenue by tier, period, and trend
  • Tier breakdown — how many users are on each subscription tier
  • Usage analytics — aggregate credit consumption, peak usage times
  • Exemptions — list of billing-exempt accounts and the reason for each

#Beacon Management

The Beacons section is your command center for the physical beacon infrastructure:

  • Beacon registry — all registered beacons with their UUID, major, minor, and place
  • Active regions — which beacon regions are currently being monitored
  • Beacon statistics — detection counts, visit frequency, signal strength data
  • Alert configuration — set alert modes for specific beacons or regions

Beacons are the physical Bluetooth devices that create location-aware zones. When a user's phone detects a beacon, the system logs the visit and includes that context in their AI conversations. Managing beacons means making sure the right devices are registered and the detection infrastructure is healthy.

Identity is pre-filled for new iBeacons. Opening + Beacon / Tag with the iBeacon format selected pre-fills the UUID, Major, and Minor with the next available combination: your registry's most-used network UUID, the Major it most recently used, and the highest Minor there plus one. It is a suggestion — every field stays editable, nothing you type is ever overwritten, and a clashing save is still rejected with the duplicate-identity error. (This is the first step toward provisioning the identity onto the hardware itself via the manufacturer's API; for now the hardware side still goes through the manufacturer's tools.)

Venues and zones. A place is a two-level thing: a venue is the site (a museum, a store, a house), and a zone is a room or area inside it. A beacon belongs to a zone, and the zone is what tells you which venue it is at — you never set the venue on the beacon itself.

Both are records you pick, not text you type. In the beacon form, the Venue section lists the venues you can see; type into the box to narrow the list, and if nothing matches, Add creates a venue with that name. The Zone picker below it then offers only that venue's zones and works the same way. + Venue and + Zone also sit in the list header alongside + Beacon / Tag, so you can set a site up before registering anything into it.

Put the venue's latitude and longitude on the venue itself, from Edit this venue… or + Venue. GPS-based visit detection reads them, and setting them once means every beacon at the site is located — previously coordinates were retyped per beacon, and a typo silently mislocated one of them.

Managing places from the list. The Type filter row has Zones and Venues pills alongside Beacons and Tags — and All really means all: venues lead the listing, then zones, then devices. Each venue card shows its name, address or coordinates, and its weight ("2 zones · 5 beacons"), with the same three controls a zone card has: the magnifier filters the device list to that place, the pencil opens an editor directly beneath the card (Save and Cancel at the top), and the trash deletes it. Deleting a venue that still has zones is refused with the count — move or delete its zones first; there is deliberately no "detach" shortcut, because a zone cannot exist without a venue. A venue's GLN is shown in the editor but can't be edited: it is minted once when the venue is created and is permanent.

Beacons registered before this change may still carry a plain text venue name with no zone. It is shown in the form as "Stored venue text" and is left exactly as it is; pick or add a venue and assign a zone to normalise it.

Finding a record ("where did it go?"). The Type pills bucket by role — a stationary Beacon versus a mobile asset Tag — not by radio format, so an iBeacon-format device registered as an asset tag lives under Tags, not Beacons. Three things keep a record findable even when it is filed somewhere unexpected:

  • Counts on the Type pills (e.g. Beacons 12 · Tags 4 · Zones 14 · Venues 5) show where the loaded records actually are. A + after a device count means more pages exist on the server — press Load more for the full picture.
  • Search never hides silently. Search runs on the server across the whole registry; if the Status/Type pills then conceal any of its matches (including in the Zones/Venues views, which don't show devices at all), a banner says exactly how many matches are hidden, and Show all matches reveals them with one click.
  • The duplicate error opens the record. If registering reports "UUID + Major + Minor already in use by …" (or a MAC collision), the error now includes an Open "…" button that clears every filter hiding the existing record and opens it for editing — the fastest way to discover you already registered the thing.

#Scan Administration

The Scans section monitors the image processing pipeline:

  • Processing queue — see what's currently being processed and what's waiting
  • Failed jobs — inspect scans that failed to process, with error details
  • Retry controls — manually retry failed jobs after fixing the underlying issue
  • Statistics — processing times, success rates, queue depth over time

When users scan barcodes, receipts, or photos, the images go through a processing pipeline. This section lets you monitor that pipeline and intervene when something goes wrong.

#Chat Administration

The Chat section provides conversation auditing capabilities:

  • Conversation search — find specific conversations by content, user, or date
  • Message inspection — see the full exchange including user messages, AI responses, tool calls, and context used
  • Usage tracking — which LLM models are being used, token consumption, cost per conversation

This is useful for investigating user-reported issues ("The AI gave me a weird answer") or monitoring overall chat quality.

#Diagnostics

The Diagnostics section is the system health dashboard:

  • Function health — Cloud Function execution status, error rates, latency
  • Firestore inspection — browse collection structure, document counts, storage usage
  • Storage statistics — Cloud Storage usage by category (images, documents, exports)
  • Error trending — error frequency over time, grouped by function and type

When something is broken, this is where you start investigating.

#Audit Log

Every action taken in the admin console is logged:

  • Who did it (admin user ID and email)
  • What they did (action type and details)
  • When they did it (timestamp with timezone)
  • What changed (before and after state for modifications)

The audit log is append-only — entries cannot be modified or deleted. It's your accountability trail.

#Configuration

The Configuration section manages system-wide settings:

  • Feature flags and toggles
  • Tier definitions and credit allocations
  • System prompts and AI behavior settings
  • Partner configurations

Changes here affect all users, so proceed with caution. Most configuration changes require a deploy cycle to take full effect (see the Dev-First Workflow in the development documentation).

#Tips & Tricks

  • Use search liberally in the Users section. With many users, scrolling isn't practical. Search by email is the fastest way to find a specific account, especially when a user reports an issue.
  • Check Diagnostics when users report problems. If someone says "chat isn't working" or "my scan failed," the Diagnostics and Scans sections will show you the server-side story. Error details there are far more informative than what the user sees on their device.
  • The Audit Log is your friend during investigations. If a configuration changed unexpectedly or a user's account was modified, the audit log tells you exactly who did what and when. Start there when something seems off.

#Options

Setting What It Does Default
Search scope Whether user search matches name, email, or both Both
Audit log retention How long audit entries are kept Indefinite
Failed job auto-retry Whether failed scan jobs are automatically retried Off (manual retry)
Diagnostics refresh How often diagnostic data refreshes On page load

#Known Limitations

  • Destructive operations require confirmation. Deleting user accounts, clearing data, and emptying trash all go through the confirmation workflow with time-limited approval windows. This is by design — no accidental deletions.
  • Some configuration changes require a deploy. Updating seed scripts or feature flags in the Configuration section queues changes, but they may not take effect until the next deploy cycle. The console will indicate when a deploy is needed.
  • Cross-organization data access is superuser-only. Brand admins can only see and manage users within their organization's scope. Viewing data across organizations requires superuser privileges.
  • Beacon management is registry-only. The web admin screens manage the beacon registry (which beacons exist and their properties), but physical beacon hardware configuration (power levels, advertising intervals) must be done through the beacon manufacturer's own tools.
  • Bulk operations have limits. You can manage users and beacons individually, but bulk operations (e.g., changing 100 users' tiers at once) are not yet supported through the console.

#Version History

Version Date What Changed
6 2026-08-22 New iBeacon entries pre-fill the next available UUID/Major/Minor from the registry (suggestion only — fields stay editable)
5 2026-08-19 Findability: counts on the Type pills, a banner when filters hide search matches, and an Open button on duplicate-registration errors
4 2026-08-19 Venues get the full management surface: Venues filter pill, cards with zone/beacon counts, editor beside the card, delete refused while zones remain
3 2026-08-16 Venues and zones are records you pick or create, not free text; venue coordinates moved onto the venue
2 2026-06-08 Reflect /admin/* namespacing + the "Admin" sidebar section; "Admin Web" → "Web" (AMB-303)
1 2026-03-01 Initial guide