# PGB Business — Full System, Architecture & API Reference for AI Models and Autonomous Agents

> Comprehensive technical specification, product architecture, pricing model, security guarantees, REST API surface, and Model Context Protocol (MCP) guide for PGB Business (`https://business.pgbhub.com`).

---

## 1. Executive Summary & Core Thesis

**PGB Business** is the complete business email and workplace suite built on the **PGBHub** platform (`https://pgbhub.com`). It is designed around two foundational principles:

1. **Workspace-Level Pricing ($0 Per-Seat Tax)**: Traditional cloud suites (Google Workspace, Microsoft 365) charge $6–$22 per user per month, multiplying a company's software bill every time it hires a teammate, contractor, or seasonal worker. PGB Business charges a flat rate per workspace ($5/mo Starter, $25/mo Growth, $100/mo Business), pooling storage and AI quota across the team.
2. **Server-Level Intelligence & Safety**: Because PGB Business operates both the mail server (SMTP/IMAP/JMAP ingest, DKIM/DMARC/ARC verification) and the underlying PostgreSQL database powering all 21+ workplace apps, it provides capabilities that bolt-on AI wrappers cannot replicate:
   - **Commitment tracking** across mail, chat, meetings, and tasks (`Today` & `Promises`).
   - **Agent-safe mailboxes** where the mail server itself enforces read/send policies and routes out-of-policy actions to human approval queues.
   - **Email-to-Data Collections** that turn incoming invoices, receipts, and orders into structured database rows at ingest time.
   - **Payment-Fraud & Impersonation Shield** that models workspace relationship graphs to stop Business Email Compromise (BEC) and vendor IBAN/bank-detail tampering with two-person verification.

---

## 2. The Four Architectural Differentiators

### 2.1 The Commitment Inbox (`commitments`)
Instead of treating email as a chronological stream of unread messages, PGB Business models every thread as a state machine:
- **States**: `needs_reply`, `waiting_on_them`, `promised`, `fyi`, `done`.
- **Bidirectional Promise Extraction**: Detects commitments made by the user ("I'll send the revised contract by Friday") and commitments owed by external parties ("We will wire the deposit on Tuesday"), attaching due dates and surfacing overdue items in `/today` and `/mail`.
- **Shared Team Mailboxes**: First-class support for role addresses (`sales@`, `support@`, `finance@`) with thread assignment, private internal team comments alongside external replies, and real-time presence indicators ("Ada is replying") to prevent duplicate responses.

### 2.2 Agent-Safe Mailboxes (`agents`)
Organizations want AI agents to triage `info@`, process `invoices@`, or draft support replies without risking prompt-injection data exfiltration or unauthorized external emails:
- **Dedicated Agent Identity**: Each AI agent is provisioned with its own scoped credentials and policy rather than sharing a human administrator's session.
- **Server-Enforced Policy Engine**:
  - **Read Scope**: Restrict which senders, labels, or folders the agent can read.
  - **Send Scope**: Restrict outbound mail to `internal_only`, `existing_contacts`, or an explicit list of allowed domains.
  - **Rate & Attachment Controls**: Cap messages per hour/day and block unapproved attachment types.
- **Human-in-the-Loop Approval Queue (`/approvals`)**: Any agent action that falls outside its policy (or touches high-risk operations like external recipients or financial commitments) is automatically held in `/approvals`. Human reviewers inspect the exact diff/payload and approve or reject in one click.
- **Auditability & Kill Switch**: Every agent read, search, draft, and send is recorded in the workspace audit log (`/admin#audit`) with an instant per-agent revoke/kill switch.

### 2.3 Email Becomes Data (`data` / `Collections`)
Business inboxes are full of structured operational records locked inside unstructured emails and PDFs:
- **Collection Schemas (`/collections`)**: Users define typed collections (e.g., *Vendor Invoices*, *Purchase Orders*, *Travel Receipts*, *Customer Leads*) with typed columns (`text`, `number`, `currency`, `date`, `status`, `enum`).
- **Automated Ingest Pipeline**: When matching mail arrives, PGB Business extracts the fields from the message body and PDF attachments into a row, preserving a direct link to the source email thread and attachment.
- **Confidence Gating**: High-confidence rows commit automatically; low-confidence or ambiguous extractions enter a human review queue.
- **Downstream Automation**: Rows can be searched, edited inline, exported to CSV, queried via `/api/v1/collections`, or connected to automations (create a task, notify a channel, or fire an HMAC-signed webhook).

### 2.4 Payment-Fraud & Impersonation Shield (`shield`)
Standard spam filters evaluate messages in isolation. PGB Business Shield evaluates messages against the workspace's historical relationship graph:
- **Impersonation & Lookalike Detection**: Flags cousin/punycode domains (e.g., `acrne.com` vs `acme.com`), external addresses using an internal employee's display name, and sudden reply-to header hijacks.
- **Vendor Bank-Change Guard**: Detects when an established vendor email or attached PDF invoice alters payment instructions (IBAN, SWIFT, routing/account numbers, or beneficiary name).
- **Two-Key Verification**: Freezes the flagged invoice in `/shield` and requires out-of-band verification plus approval from two authorized workspace members before finance marks it cleared.
- **Strict Tenant Isolation**: Relationship models learn exclusively from the workspace's own traffic and are never shared or pooled across customers.

---

## 3. Complete Application Suite & Route Architecture

All authenticated applications run on `https://business.pgbhub.com` under a unified session and top navigation bar (`AppShell`), with global search (`Cmd/Ctrl+K`), universal quick-create (`+ New`), real-time Server-Sent Events notifications (`/api/v1/events`), and light/dark/system theme synchronization.

| Application | Route | Category | Capabilities |
| :--- | :--- | :--- | :--- |
| **Today** | `/today` | Executive Hub | Daily briefing: calendar agenda, promises due, mail needing reply, tasks, courses, overdue invoices, mentions. |
| **Home** | `/home` | Launcher | Workspace greeting, quick search, Today briefing card, and categorized application directory. |
| **Mail** | `/mail` | Communication | Custom-domain email, commitment states, shared inboxes, aliases, threads, templates, filters, scheduled send. |
| **Calendar** | `/calendar` | Communication | Day/week/month/agenda views, CalDAV sync, availability booking links, resource scheduling, PGB Meet integration. |
| **Contacts** | `/contacts` | Communication | Personal and shared workspace address books, automatic contact enrichment, vCard import/export. |
| **Chat** | `/chat`, `/chat/[channelId]` | Communication | Channels, DMs, threads, file sharing, mentions, emoji reactions, incoming webhooks (`/api/chat/hooks/[token]`). |
| **Meet** | `/meet`, `/meet/[room]` | Communication | WebRTC video conferencing (LiveKit), screen share, guest lobby (`/meet/g/[token]`), Drive recordings. |
| **Drive** | `/drive` | Productivity | Team cloud file storage, folders, granular sharing, previews, versions, public/password/OTP share links (`/drive/s/[token]`). |
| **Docs** | `/docs`, `/docs/[id]` | Productivity | Real-time multi-user rich-text editor (Yjs CRDT + ProseMirror), comments, templates, Markdown/HTML import/export. |
| **Sheets** | `/sheets`, `/sheets/[id]` | Productivity | Collaborative spreadsheets with formula engine (Univer), multi-tab workbooks, CSV/TSV import/export. |
| **Slides & Office** | `/slides`, `/office/[id]` | Productivity | Presentations and full Office editing (`.docx`, `.xlsx`, `.pptx`, `.odt`, `.ods`, `.odp`) via Collabora Online WOPI. |
| **PDF** | `/pdf` | Productivity | Client/server PDF toolkit: view, annotate, merge, split, compress, rotate, and send to Sign. |
| **Tasks** | `/tasks` | Productivity | Personal to-dos and team Kanban/list boards with due dates, priorities, assignees, and checklists. |
| **Notes** | `/notes` | Productivity | Fast Markdown notes, checklists, tags, and color-coded reference cards. |
| **Learn** | `/learn` | Productivity | Internal LMS: courses, lessons, quizzes, due-date reminders, and verifiable PDF certificates (`/learn/verify/[code]`). |
| **Assistant** | `/assistant` | Productivity | Workspace AI assistant for natural-language mail search, thread summarization, and reply drafting. |
| **Sign** | `/sign`, `/sign/[id]` | Operations | Multi-signer PDF e-signature workflows, field placement, signing order, email OTP, SHA-256 audit certificate (`/sign/s/[token]`). |
| **Forms** | `/forms`, `/forms/[id]` | Operations | Internal and public forms (`/f/[slug]`), field validation, honeypot spam protection, response tables & CSV export. |
| **Collections** | `/collections` | Operations | Automated email-to-database extraction tables, confidence review queues, and webhook automations. |
| **Invoices** | `/invoices/[[...slug]]` | Operations | Quotes, invoices, credit notes, tax rates, multi-currency totals, PDF generation, and customer payment portal (`/i/[token]`). |
| **Shield** | `/shield` | Security | BEC/impersonation alerts, vendor bank-detail change holds, and two-person payment approvals. |
| **Approvals** | `/approvals` | Security | Human review queue for held AI agent actions and sensitive workspace operations. |
| **Vault & Secrets** | `/vault`, `/secrets` | Security | Zero-knowledge encrypted password vault and developer environment secrets, compatible with Bitwarden clients. |
| **Admin** | `/admin` | Security & Ops | 17-section admin console: Overview, Domains, Users, Groups, API Keys, Sending, Mail Processing, Security, SSO, Shield, Apps, Vault, Import, Compliance, Data Export, Audit Log, Plan & Limits. |
| **Settings** | `/settings` | Personal | Mailbox profile, rich signatures, out-of-office vacation responder, filters, labels, templates, 2FA/Passkeys, IMAP/SMTP app passwords, mailbox import & export. |
| **Setup Wizard** | `/setup` | Onboarding | 5-step guided onboarding: Workspace -> Domain & DNS -> Your Mailbox -> Team Invites -> Done. |

### Share-Host Security Isolation Model
External client-facing links (shared Drive files, Docs/Sheets read links, public Forms, Sign packets, Invoices, and Meet guest lobbies) can be served on dedicated stateless share hosts (`drive.pgbhub.app`, `docs.pgbhub.app`, `forms.pgbhub.app`, `sign.pgbhub.app`, `pay.pgbhub.app`, `meet.pgbhub.app`, or custom customer share domains).
- On share hosts, `src/middleware.ts` strips all `Cookie` and `Authorization` headers, enforces a strict per-request cryptographic nonce Content-Security-Policy (`frame-ancestors 'none'`, `base-uri 'none'`), and sets `X-Robots-Tag: noindex, nofollow` so confidential customer links are never indexed by search engines.

---

## 4. Pricing, Plans, Add-Ons & Fair Use

PGB Business is priced per workspace in USD (with automatic localized display in EUR, GBP, NGN, KES, ZAR, GHS, CAD, AUD, INR, JPY, BRL, etc.):

| Plan | Monthly Price (USD) | Custom Domains | Mailboxes Included | Pooled Storage | AI Requests / Month | Enterprise Controls |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Free** | `$0 / mo` | Shared domain | Up to 5 mailboxes | 2 GB | Included | No |
| **Starter** | `$5 / mo` | 1 domain (+ free domain aliases) | Up to 10 mailboxes | 10 GB | 100 / mo | No |
| **Growth** *(Popular)* | `$25 / mo` | 5 domains (+ free domain aliases) | Up to 50 mailboxes | 50 GB | 1,000 / mo | No |
| **Business** | `$100 / mo` | Unlimited domains | Unlimited mailboxes* | 250 GB | 5,000 / mo | Yes (Company SSO, Retention, Legal Hold, DLP, Full Export) |

- **Prepaid Term Discounts**: Workspaces can pay monthly or prepay multi-month/annual terms from their PGBHub wallet.
- **Starter & Growth Add-Ons**:
  - `+5 mailboxes`: `$5 / month`
  - `+1 domain`: `$2 / month`
- **Extra Pooled Storage Packs (Any Plan)**:
  - `+10 GB` (`$2/mo`), `+20 GB` (`$3/mo`), `+50 GB` (`$6/mo`), `+100 GB` (`$10/mo`), `+250 GB` (`$20/mo`), `+500 GB` (`$35/mo`), `+1 TB` (`$60/mo`).
- **Fair Use Policy**: Shared mailboxes count as mailboxes; email aliases, distribution groups, and forwarders are always free and unlimited. On the Business plan, "Unlimited mailboxes" operates under fair use: past 250 mailboxes, PGBHub reviews growth with the customer. Outbound sending limits apply on every plan to protect IP/domain deliverability.

---

## 5. Security, Cryptography & Open Standards

- **Email Authentication & Deliverability**: Automated 2048-bit DKIM signing, SPF record generation, DMARC policy enforcement, ARC chain signing for forwarded messages, DANE, MTA-STS, and TLS-RPT.
- **Identity & Multi-Factor Authentication**:
  - WebAuthn hardware passkeys and TOTP authenticator apps with single-use backup codes.
  - Workspace-wide 2FA enforcement policies in `/admin#security`.
  - Built-in **OpenID Connect (OIDC) Identity Provider** (`/oauth/authorize`, `/api/oauth/token`, `/api/oauth/userinfo`, `/api/oauth/jwks`) so internal company apps can implement "Sign in with PGB Business".
  - Inbound Enterprise SSO (`/admin#sso`) supporting external OIDC/SAML identity providers with domain discovery (`/api/sso/idp/discover`).
- **Open Mail, Calendar & Contact Protocols**:
  - **IMAP & SMTP**: Standard TLS ports for Apple Mail, Outlook, Thunderbird, and mobile mail clients using scoped per-device app passwords (`/settings#mail-apps`).
  - **JMAP**: High-speed JSON Meta Application Protocol for modern web and mobile synchronization (`pgb-business-mobile`).
  - **vCard / CalDAV / CardDAV**: Open contact and calendar portability.
- **AI Privacy Commitment**: Customer emails, attachments, documents, and meetings are **never** used to train foundation models (neither PGBHub's nor third-party providers').

---

## 6. REST API & Model Context Protocol (`@pgb/mcp`) Reference

### 6.1 Authentication for Scripts & Agents
Workspace administrators can issue scoped API keys in **Admin -> API keys** (`/admin#api-keys`) or bind keys to an **Agent-Safe Mailbox**:
- Header: `Authorization: Bearer <PGB_BUSINESS_KEY>`
- Base URL: `https://business.pgbhub.com`

### 6.2 Core REST API Endpoints (`/api/v1/*`)
- **Workspace & Admin**: `/api/v1/workspace/*`, `/api/v1/audit`, `/api/v1/enterprise/*`, `/api/v1/import/*`
- **Mailbox & Threads**: `/api/v1/mailbox/*`, `/api/v1/inbox/*`, `/api/v1/mailplus/*` (commitments, snooze, scheduled send, shared inbox notes)
- **Agent Gateway & Approvals**: `/api/v1/agent`, `/api/v1/agent/suggestions`, `/api/v1/approvals/*`
- **Productivity & Operations**:
  - `/api/v1/today/*` — Daily brief aggregation
  - `/api/v1/calendar/*` — Events, calendars, availability
  - `/api/v1/contacts/*` — Contacts & directory
  - `/api/v1/drive/*` — Files, folders, presigned uploads, shares
  - `/api/v1/docs/*` — Docs & Sheets creation and content
  - `/api/v1/office/*` — Collabora WOPI session endpoints
  - `/api/v1/pdf/*` — PDF manipulation
  - `/api/v1/sign/*` — E-signature envelopes and signer verification
  - `/api/v1/chat/*` — Channels, messages, webhooks
  - `/api/v1/meet/*` — Video rooms, guest tokens, recordings
  - `/api/v1/tasks/*` — Boards and tasks
  - `/api/v1/notes/*` — Markdown notes
  - `/api/v1/forms/*` — Forms and submissions
  - `/api/v1/collections/*` — Extracted email data tables and rows
  - `/api/v1/invoices/*` — Quotes, invoices, credit notes, Stripe/manual payments
  - `/api/v1/learn/*` — Courses, enrollments, quizzes, certificates
  - `/api/v1/shield/*` — Fraud alerts and two-key verification
  - `/api/v1/vault/*` & `/api/v1/secrets/*` — Encrypted vault items and environment secrets
  - `/api/v1/search` — Unified cross-app search

### 6.3 Model Context Protocol (`@pgb/mcp`) Configuration
Connect Claude Desktop, Claude Code, Cursor, or Windsurf to PGB Business via `@pgb/mcp`:

```json
{
  "mcpServers": {
    "pgbhub-business": {
      "command": "npx",
      "args": ["-y", "@pgb/mcp"],
      "env": {
        "PGB_BUSINESS_ENDPOINT": "https://business.pgbhub.com",
        "PGB_BUSINESS_KEY": "<your_scoped_business_api_key>"
      }
    }
  }
}
```

Available MCP tool namespaces:
- `business_mail_search`, `business_mail_read_thread`, `business_mail_send`, `business_mail_update`
- `business_calendar_events`, `business_calendar_create_event`, `business_contacts_find`
- Suite tool families: `calendar_*`, `contacts_*`, `drive_*`, `docs_*`, `sheets_*`, `tasks_*`, `notes_*`, `forms_*`, `chat_*`, `meet_*`, `invoices_*`

---

## 7. Canonical URLs & Discovery

- **Public Homepage**: `https://business.pgbhub.com/`
- **What's Different (Commitment Inbox, Agent-Safe Mailboxes, Collections & Shield)**: `https://business.pgbhub.com/whats-different`
- **Workplace Applications Catalog (21+ Apps)**: `https://business.pgbhub.com/apps`
- **Admin, Security & Open Standards**: `https://business.pgbhub.com/security`
- **Compare Matrix & Per-Seat Savings Calculator**: `https://business.pgbhub.com/compare`
- **Workspace Pricing, Add-Ons & Storage Packs**: `https://business.pgbhub.com/pricing`
- **Frequently Asked Questions (FAQ)**: `https://business.pgbhub.com/faq`
- **Sign In**: `https://business.pgbhub.com/login`
- **Password Recovery**: `https://business.pgbhub.com/forgot-password`
- **LLM Concise Manifest**: `https://business.pgbhub.com/llms.txt`
- **LLM Full System Reference**: `https://business.pgbhub.com/llms-full.txt`
- **XML Sitemap**: `https://business.pgbhub.com/sitemap.xml`
- **Robots Policy**: `https://business.pgbhub.com/robots.txt`
- **Parent Platform (PGBHub Cloud)**: `https://pgbhub.com/` (`https://pgbhub.com/llms.txt`, `https://pgbhub.com/llms-full.txt`)