1.1 — Platform Overview

As a Super Admin you have full control over the entire Heartbeat AI platform. You manage companies, provision modules, configure billing, and oversee all system-level settings.

• Access the Super Admin panel from the top nav (shield icon)
• View all registered companies, their subscription tiers, and user counts
• Toggle modules on/off per company and manage global settings

1.2 — Company Management

Create and configure companies that will use the platform:

1. Navigate to Super Admin → Companies
2. Click + New Company and fill in company name, admin email, and tier
3. The company admin receives a welcome email with login instructions
4. Set the Membership Tier (Free, Pro, Lifetime) to control feature access

1.3 — Module Activation

Enable or disable modules for each company:

1. Go to Super Admin → Module Manager
2. Toggle individual modules (Chat, Pages, Agents, Dynamic Forms) per company
3. Mark modules as "Developed" or "Coming Soon" to control visibility
4. Set display order to customize the navigation menu

1.4 — AI Model Provisioning

Configure which AI models are available across the platform:

1. Go to Super Admin panel or Settings → Models
2. Add API keys for OpenAI, Anthropic, Google Gemini, NVIDIA, Ollama, or custom providers
3. Set default chat and embedding models per company
4. Models appear in the sidebar dropdown for users to select during chat
5. Each company needs one embedding model (config role: "embedding") — recommended: gemini-embedding-001 (Google) or text-embedding-3-small (OpenAI). See Part 2, Section 2.3 for full list and base URLs.

1.5 — Billing & Stripe Integration

The platform integrates with Stripe for payment processing:

• Stripe checkout sessions are created automatically during company signup
• Webhook events confirm payment and activate the company account
• View payment status and email logs in the Super Admin dashboard

1.6 — Integration Credentials Setup

The platform supports several third-party integrations. As Super Admin, you manage the platform-level credentials. Tenant-level credentials are managed by each company admin.

Google Drive (Platform-Level)

1. Go to Google Cloud Console → same project as your Google Sign-In
2. Enable the Google Drive API
3. Go to OAuth consent screen → add the https://www.googleapis.com/auth/drive.readonly scope
4. Copy your OAuth Client Secret and set it as GOOGLE_OAUTH_CLIENT_SECRET in the Superadmin → Platform Config panel
5. Add your callback URL: {APP_BASE_URL}/integrations/drive/callback to Authorized Redirect URIs

Slack Bot (Platform-Level)

1. Go to Slack API → Your Apps and create a new app
2. Under OAuth & Permissions, add scopes: chat:write, app_mentions:read, channels:history, groups:history, im:history
3. Under Event Subscriptions, enable events and set the request URL to {APP_BASE_URL}/integrations/slack/events
4. Subscribe to bot events: app_mention, message.im
5. Copy Client ID, Client Secret, and Signing Secret → set as env vars in Platform Config
6. Add redirect URL: {APP_BASE_URL}/integrations/slack/callback

QuickBooks Online (Platform-Level)

1. Go to Intuit Developer Portal and create an app
2. Under Keys & credentials, select Production (or Sandbox for testing)
3. Copy Client ID and Client Secret
4. Add redirect URI: {APP_BASE_URL}/integrations/quickbooks/callback
5. Set QUICKBOOKS_CLIENT_ID and QUICKBOOKS_CLIENT_SECRET in Platform Config

Customer Stripe Invoicing (Tenant-Level)

Each company admin configures their own Stripe keys — no platform-level env vars needed:

1. Tenant admins go to Settings → Integrations → Customer Stripe
2. They enter their own sk_live_... secret key
3. Optionally add Publishable Key and Webhook Secret
4. Payments flow directly to their Stripe account — the platform never handles funds

Troubleshooting Common Issues:

• "OAuth client secret not configured" — Check that the env var is set in Platform Config and the service has been redeployed
• "Token refresh failed" — The user may need to re-authorize. Disconnect and reconnect the integration
• "Invalid redirect URI" — Ensure the callback URL in the provider's console exactly matches APP_BASE_URL + /integrations/{service}/callback
• "Webhook signature invalid" — Verify the signing/webhook secret matches between the provider and your config
• "QuickBooks 401 error" — Token expired. QB tokens expire after 1 hour; the platform auto-refreshes them, but if the refresh token expires (100 days), the user must reconnect

2.1 — Getting Started

After your company is provisioned, sign in with your Google account:

1. Visit the Heartbeat AI login page and select your company
2. Click Sign in with Google — your email must match the admin email on file
3. You'll land on the Chat module by default with full admin privileges

2.2 — Knowledge Base Setup

Build your AI knowledge base by uploading documents:

1. Go to Settings → Containers and create categories (e.g., "HR Policies", "Product Docs")
2. Click the 📂 Files icon in the sidebar to open the Knowledge Base
3. Upload PDFs, Word docs, Excel files, images, or plain text
4. Files are automatically chunked, embedded, and stored in the vector database
5. Assign each file to a container for organized retrieval

2.3 — AI Model Configuration

Configure the AI models your team will use:

1. Go to Settings → Models
2. Add models with their API keys — supported providers: OpenAI, Anthropic (Claude), Google Gemini, NVIDIA NIM, Ollama (local), and custom OpenAI-compatible endpoints
3. Mark one model as the default for new conversations
4. Add an embedding model (config role: "embedding") — this is required for document uploads and AI search

Supported Embedding Models

You need exactly one embedding model configured. Below are the recommended options:

2.4 — Team Management

Add and manage your team members:

1. Go to Settings → Users
2. Invite users by email — they must use Google Sign-In with that email
3. Set roles: Admin (full access) or User (module access only)
4. Remove users or change roles at any time

2.5 — Dynamic Forms Module

Create custom data-collection forms that auto-vectorize into your knowledge base:

1. Open the Dynamic Forms module from the navigation menu
2. Click + New to create a Module Instance (e.g., "HR Onboarding")
3. In the Config tab, assign a RAG container, chat model, and embedding model
4. Switch to Forms tab and click + New Form
5. Use the drag-and-drop form builder to add fields: Text, Textarea, Number, Email, Date, Dropdown, Multi-select, Radio, Checkbox, File
6. Save the form — it's immediately available for users to fill out

2.6 — Permission Management

Control who can access each Dynamic Forms instance:

1. Open a module instance and go to the Access tab
2. Grant access to individual users with User or Editor level
3. Admins automatically have access to all instances
4. Regular users only see instances they've been explicitly granted access to

2.7 — QR Code Strategy

Every form submission generates a unique QR code:

• QR codes link to a public detail page for the entry
• Scans are logged with IP, timestamp, and user agent for audit
• Use QR codes for employee badges, event check-ins, asset tracking, or document verification
• QR images include your company logo overlay for branding

2.8 — Company Branding

Customize your company's appearance:

1. Go to Settings → Company
2. Update your company name, logo URL, and primary color
3. The logo appears on QR codes and public-facing pages
4. Branding is applied across all shared content (pages, QR scans, exports)

2.9 — Analytics Dashboard

View usage trends and insights for your company:

1. Go to Settings → Analytics
2. See KPI cards at the top: total queries (30 days), active users, widget queries, and top container
3. Query Volume — bar chart showing daily query counts over the last 30 days
4. Top Queries — most frequently asked questions this month
5. Most Active Users — team members sorted by query count
6. Model Usage — breakdown of which AI models are used most

2.10 — Embeddable Chat Widget

Add an AI chat assistant to your website so visitors can ask questions answered by your knowledge base:

1. Go to Settings → Widget
2. Click + Create Widget Key and fill in:
   • Label — a name for this widget (e.g. "Main Website")
   • Allowed Origins — restrict which domains can use the widget (leave blank for any)
   • System Prompt — optional custom instructions for the AI
   • Welcome Message — greeting shown when the chat opens
   • Starter Prompts — suggested questions for visitors
3. After creation, click the </> button to copy the embed snippet
4. Paste the <script> tag into your website's HTML — a floating chat button appears
5. Widget queries count against your monthly quota

2.11 — User Guide & Help Mode

Make the platform self-explaining by indexing the user guide into your AI:

1. Go to Settings → Company
2. Scroll down to User Guide Knowledge Base
3. Click Index User Guide — this stores the guide content in your RAG knowledge base
4. In the Chat view, click the ? button next to the input to enter Help Mode
5. While in Help Mode, your questions are answered from the user guide (e.g. "How do I upload a document?")
6. Click ? again to return to normal document search

2.12 — Google Drive Integration

Connect Google Drive to automatically sync documents into your RAG knowledge base:

1. Go to Settings → Integrations
2. Click Connect Google Drive and authorize access with your Google account
3. Once connected, click Browse Drive to see your files
4. Use the search bar to find specific files, or click folders to navigate
5. Select files with checkboxes and click Sync Selected
6. Synced files are chunked, embedded, and added to your AI knowledge base
7. Use the ↻ button on synced files to pull the latest version from Drive

2.13 — Slack Integration

Install a Slack bot that answers questions using your company's RAG knowledge base:

1. Go to Settings → Integrations
2. Click Add to Slack and install the bot in your workspace
3. Once connected, the bot is ready to use in your Slack workspace
4. Mention @HeartbeatAI in any channel followed by your question
5. Or send a direct message to the bot for private queries
6. The bot responds in threads to keep channels clean

2.14 — Contract Signatures

Create contract forms with digital signature capture and automatic PDF generation:

1. Open any Dynamic Forms module instance and click + New Form
2. Set Form Type to Contract
3. Write your contract body template in the text area — use {{field_key}} placeholders (e.g. {{client_name}}, {{date}}) to insert submitted values
4. Add your form fields: client name, date, terms, etc.
5. Click + Signature to add a signature capture field (only one per form)
6. Save the form — it's ready for use

How signing works:

1. Users fill out the form and draw their signature on the canvas pad
2. On submit, the signature is captured as an image and stored with the entry
3. Admins can Download PDF from the entry detail — the PDF contains the contract body with field values filled in, a table of all submitted data, the signature image, and a signed-by footer
4. Admins can Send Contract to email the signed PDF to the signer
5. Contracts are auto-vectorized into RAG — ask the AI "show me contracts signed by John" or "find the latest NDA"

2.15 — Customer Stripe Invoicing

Send invoices with Stripe payment links directly from your forms:

Step 1: Connect Stripe

1. Go to Settings → Integrations → Customer Stripe
2. Enter your Stripe Secret Key (starts with sk_live_ or sk_test_)
3. Optionally enter your Publishable Key and Webhook Secret
4. Click Connect Stripe

Step 2: Create an Invoice Form

1. In any Dynamic Forms module, click + New Form
2. Set Form Type to Invoice — default fields (client name, email, amount, description, due date) are auto-added
3. Customize fields as needed and save

Step 3: Send Invoices

1. Fill and submit the invoice form with client details and amount
2. Open the entry detail and click Create Payment Link — a Stripe payment link is generated
3. Click Send Invoice — the client receives an email with a "Pay Now" button
4. Track payment status: Pending → Paid
5. Use Mark Paid for manual/offline payments

2.16 — QuickBooks Integration

Sync your QuickBooks Online data into the AI knowledge base for financial Q&A:

Connecting QuickBooks:

1. Go to Settings → Integrations → QuickBooks Online
2. Click Connect QuickBooks — you'll be redirected to Intuit's authorization page
3. Sign in to your QuickBooks account and authorize the connection
4. After authorization, you'll be redirected back — status shows "Connected"

Syncing Data:

1. Select which data types to sync: Customers, Invoices, Payments
2. Click Sync Now — data is pulled from QuickBooks, converted to text, and embedded into your RAG knowledge base
3. The synced data table shows record counts, chunk counts, and last sync time
4. Re-sync anytime to pull the latest data

Querying Financial Data:

1. Go to Chat and ask questions like:
   • "Who are our top 5 customers by balance?"
   • "Show me all unpaid invoices"
   • "What payments came in last month?"
   • "How much does Acme Corp owe us?"
2. Optionally filter by the quickbooks container to scope queries to QB data only

3.1 — Signing In

Access Heartbeat AI with your Google account:

1. Visit the platform URL provided by your admin
2. Enter your company name and click Sign in with Google
3. Your email must be registered by an admin — if not, you'll see an "Unauthorized" message
4. Once signed in, the navigation menu shows your available modules

3.2 — AI Chat

Ask questions and get AI-powered answers from your company's knowledge base:

1. Click 💬 Chat in the navigation menu
2. Select an AI model from the sidebar dropdown (e.g., GPT-4, Claude, Gemini)
3. Optionally filter by Container to scope answers to specific document sets
4. Type your question and press Enter or click Send
5. The AI retrieves relevant passages from your documents and generates an answer with source citations

3.3 — Interactive Pages

Create and interact with AI-generated content:

• Ask the AI to create quizzes, surveys, forms, or reports in the chat
• When the AI generates HTML content, click Save as Page to store it
• Open the 📄 Pages module to view and manage saved pages
• Share pages via public links — visitors provide their name and email before accessing
• Quiz scores and form submissions are automatically captured

3.4 — Multi-Agent Pipeline

Leverage multiple AI workers for complex tasks:

1. Open the 🤖 Agents module
2. Add worker agents — each with its own model, system prompt, and document scope
3. Submit a task and all workers process it in parallel
4. A Supervisor agent synthesizes their outputs into a unified, comprehensive response
5. Great for getting diverse perspectives or comparing model outputs

3.5 — Dynamic Forms & Data Entry

Fill out forms and contribute to the knowledge base:

1. Open a Dynamic Forms module instance you have access to
2. In the Forms tab, click a form to fill it out
3. Complete all required fields and click Submit
4. Your submission is auto-vectorized — the AI can now answer questions about your data
5. View your entries in the Entries tab with search and filters

3.6 — QR Codes

Every form submission gets a unique QR code:

• Click the QR button on any entry to view or download the QR code
• Share or print the QR code — anyone scanning it sees the entry details
• All scans are logged for audit purposes

3.7 — AI Insights & Module Chat

Ask questions about data within a Dynamic Forms module:

1. Open a module instance and switch to the AI Chat tab
2. Ask questions like "How many entries were submitted this month?" or "List all employees in Engineering"
3. The AI searches only within that module's vectorized data for precise answers

3.8 — Reporting & Export

Export your data for analysis or sharing:

• Excel Export: Click 📥 Excel in the Entries tab to download a spreadsheet of all entries
• PDF Export: Click 📄 PDF for a formatted report
• AI Report: Use the AI to generate narrative reports and insights from your data
• Chat responses can be exported as Excel, PDF, or sent via email

4.1 — Data Privacy

Heartbeat AI is designed with multi-tenant data isolation:

• Each company's data is completely isolated — no cross-company data leakage
• Documents, embeddings, chat history, and form data are all company-scoped
• API keys are stored server-side and never sent to the browser
• Google Sign-In provides secure, passwordless authentication

4.2 — Optimizing AI Queries

Get the best results from your AI interactions:

• Use specific questions — "What is the return policy for electronics?" beats "Tell me about returns"
• Filter by container — narrow the scope to relevant document sets for faster, more accurate results
• Choose the right model — GPT-4/Claude for complex analysis, faster models for simple lookups
• Upload quality documents — clean, well-structured documents produce better embeddings
• Organize containers logically — separate topics into distinct containers for precision

4.3 — Access Control Best Practices

• Follow the principle of least privilege — only grant users access to the modules they need
• Use the Admin role sparingly — most team members should be Users
• Review user access lists periodically and remove inactive accounts
• Use Dynamic Forms permissions to control who can see sensitive data modules

4.4 — Document Management Tips

• Keep documents up to date — outdated docs lead to stale AI answers
• Use descriptive file names — they're included in the vector metadata
• Delete and re-upload documents when major changes occur (re-vectorizes automatically)
• Monitor your vector store size in Settings → Vector Store

4.5 — Platform Architecture

For the technically curious, Heartbeat AI is built with:

• Backend: FastAPI (Python) with SQLAlchemy ORM on PostgreSQL + pgvector
• AI: Multi-provider support (OpenAI, Anthropic, Google, NVIDIA, Ollama) with RAG pipeline
• Embeddings: pgvector for similarity search with cosine distance
• Infrastructure: Google Cloud Run with auto-scaling and Cloud SQL
• Auth: Google OAuth 2.0 with server-side session management
• Payments: Stripe Checkout with webhook verification