# Administrator Guide — A&B Hub

Everything in this guide is reachable from the sidebar once logged in
as a user with the relevant permission (User Management, Roles &
Permissions control who sees what — see "Access Control" below).

## Getting started

1. Log in with a seeded demo account or a real account created by
   another admin.
2. **User Management > Users** — create real staff accounts, assign
   roles, and set which business line(s) (Homecare / Cleaner / both)
   each person can access.
3. **Delete or deactivate the demo accounts** once real accounts exist
   — Users > (user) > Deactivate, or delete outright if they were
   never used.

## Access Control

- **Roles & Permissions** (User Management > Roles) defines what each
  role can do, per module, at one of four levels: none / view / edit /
  full. Built-in roles: Operations Admin, Sales Rep, Field Staff — but
  you can create custom roles.
- **Departments & Teams** group users for reporting and assignment,
  independent of role.
- Every list page, form, and button in the app checks a permission
  before rendering — a user without `leads_customers.edit` sees Leads
  in read-only form, not an error page.

## CRM

- **Leads**: list view or Kanban pipeline board (drag a card between
  stages to update it). Duplicate detection runs automatically when
  creating or importing leads.
- **Customers / Companies**: same pattern — Companies represent B2B
  accounts, Customers can optionally belong to one.
- **Appointments**: calendar view, conflict detection prevents
  double-booking the same staff member, recurring appointments
  generate real rows (not virtual placeholders) up to 52 occurrences
  ahead.
- **Import**: Leads > Import CSV — deduplicates by email/phone,
  reports per-row errors without failing the whole batch.
- **Export**: every list page and every report supports CSV, Excel
  (real .xlsx), PDF, and Print.

## Marketing

- **SMTP Settings** (Marketing > SMTP Settings) must be configured
  before any email — campaign, personal, or automated — will actually
  send. Use "Send Test Email" to confirm before going live.
- **Campaigns**: chip-based audience picker (All Leads / Homecare /
  Cleaner / Customers / Saved Segment / Filtered Audience), live
  recipient-count preview, optional recurrence (Newsletter).
- **Automation**: the 5 built-in rules (Welcome Email, Follow-up
  Email, Appointment Reminder, Birthday Email, Re-engagement) are
  active by default — toggle any off from Automation if you don't want
  it running. Prompt Management and Knowledge Base (below) feed the AI
  side of automation, not the email side.

## AI & Automation

- **Integrations** is where every external provider (OpenAI,
  ElevenLabs, Twilio, WhatsApp, Google, Facebook/Instagram/TikTok,
  Meta Pixel, Google Analytics) is connected — API-key providers use a
  simple form; OAuth providers (Google, Facebook, Instagram, TikTok)
  walk through the standard "Set Up & Connect" authorization flow.
  **Nothing else in the CRM requires these to be connected** — leads,
  customers, appointments, invoicing, and reporting all work with zero
  integrations configured.
- **AI Assistant** (staff-facing chat) needs OpenAI connected to
  answer freeform questions; without it, every other module still
  works normally.
- **Website Chatbot**: configure per business line (Chatbot Settings)
  — greeting message, human-handoff keywords, live/draft toggle. Works
  without OpenAI connected (falls back to Knowledge Base search + safe
  lead-capture), better with it connected (handles natural-language
  booking requests).
- **AI Voice Agent**: needs Twilio connected (and a phone number
  purchased through Twilio, pointed at this app's `/voice/incoming`
  webhook — see `docs/API.md`) to receive or place calls.
- **Knowledge Base**: FAQ entries the Chatbot and AI Assistant search
  before falling back to the LLM (or instead of it, if none is
  connected).
- **Prompt Management**: edit the system prompt each AI feature uses,
  optionally per business line.
- **Conversation Logs**: every chatbot, voice, and AI Assistant
  conversation, searchable, with full transcripts.

## Reports

Nine report types (Overview, Leads, Customers, Revenue, Marketing,
Appointments, AI, Staff Performance, System Logs), each filterable by
date range and business line, each exportable as CSV / Excel / PDF /
Print. These are the exact same numbers the AI Assistant's
"Generate Reports" tool produces when asked — there is only one
reporting engine (`ReportService`), not two.

## System Administration

- **Activity Logs**: every significant action (who did what, when),
  filterable by category (user action / system / security / admin).
- **API Keys**: generate a key for a third-party integration (Zapier,
  a custom script, etc.) with optional scoped permissions
  (`leads.read`, `leads.write`, `customers.read`). The full key is
  shown exactly once at creation — copy it immediately. Revoke a key
  instantly if it's ever compromised.
- **Notifications**: per-user notification preferences (Profile >
  Notifications).

## Data safety

- Nightly automated database backup (`deploy/backup-database.sh` via
  cron) — see `docs/INSTALLATION.md`.
- Nothing in this application hard-deletes a record a user creates
  (leads, customers, companies, appointments, knowledge base articles)
  — every delete is a soft delete (`deleted_at`), recoverable by an
  admin, never silently gone.
