# QMax × Visionary EventCatalog Documentation

> The QMax platform as claude.ai sees it: queries direct, commands through the human-gated approval bus. Explore the domains, the message contracts (queries · commands · events), and the CQRS flow end to end.

## Events
- [Mutation Applied - mutation-applied - 0.1.0 ](https://eventcatalog.dev/docs/events/mutation-applied/0.1.0.mdx) - The approved mutation executed against its vendor system; the applier's result (e.g.- [Mutation Failed - mutation-failed - 0.1.0 ](https://eventcatalog.dev/docs/events/mutation-failed/0.1.0.mdx) - The applier threw (vendor down, validation, auth) — recorded as status `failed` with the error, surfaced to the card as a structured error.- [Proposal Approved - proposal-approved - 0.1.0 ](https://eventcatalog.dev/docs/events/proposal-approved/0.1.0.mdx) - A cleared human approved in the card (app-only commit path, RBAC-checked against the authenticated session).- [Proposal Created - proposal-created - 0.1.0 ](https://eventcatalog.dev/docs/events/proposal-created/0.1.0.mdx) - A propose_* command queued a mutation: a Proposal now exists in status `pending` with a freshly-minted per-card widget token.- [Proposal Rejected - proposal-rejected - 0.1.0 ](https://eventcatalog.dev/docs/events/proposal-rejected/0.1.0.mdx) - A cleared human rejected the proposal.

## Commands
- [Commit Approval - commit-approval - 0.1.0 ](https://eventcatalog.dev/docs/commands/commit-approval/0.1.0.mdx) - The ONLY execution path. A human click in the approval card approves (→ the write runs) or rejects a pending proposal. App-only — a compliant host never exposes it to the model.- [Entra Authorize - entra-authorize - 0.1.0 ](https://eventcatalog.dev/docs/commands/entra-authorize/0.1.0.mdx) - The relayed authorization request Entra actually sees — a normal auth-code + PKCE flow, minus the resource param it would reject.- [Entra Token - entra-token - 0.1.0 ](https://eventcatalog.dev/docs/commands/entra-token/0.1.0.mdx) - The relayed token exchange. Audience is driven by scope (api://…/mcp-access) since resource is stripped; the Entra app runs accessTokenAcceptedVersion=2.- [Fishbowl Import Bill - fishbowl-import-bill - 0.1.0 ](https://eventcatalog.dev/docs/commands/fishbowl-import-bill/0.1.0.mdx) - Enters a PO-linked vendor bill in Fishbowl (dated with the warehouse receipt date), which auto-pushes to QBO.- [Fishbowl Import Sales Order - fishbowl-import-sales-order - 0.1.0 ](https://eventcatalog.dev/docs/commands/fishbowl-import-sales-order/0.1.0.mdx) - Creates a draft SO (status Estimate) via Fishbowl's /api/import CSV path — Fishbowl's only write surface.- [Graph Send Mail - graph-send-mail - 0.1.0 ](https://eventcatalog.dev/docs/commands/graph-send-mail/0.1.0.mdx) - Sends the approved AR collections email via Microsoft Graph sendMail (app-only client credentials).- [OAuth Authorize (proxied) - oauth-authorize - 0.1.0 ](https://eventcatalog.dev/docs/commands/oauth-authorize/0.1.0.mdx) - claude.ai starts the user OAuth flow against the mesh's advertised authorization server; the gateway 302s the browser on to Entra with the RFC 8707 resource param stripped.- [OAuth Token (proxied) - oauth-token - 0.1.0 ](https://eventcatalog.dev/docs/commands/oauth-token/0.1.0.mdx) - claude.ai exchanges the auth code / refreshes tokens at the mesh's token endpoint; the gateway relays the POST to Entra with resource stripped, holding no client secret itself.- [Propose AR Collections Email - propose-ar-collection-email - 0.1.0 ](https://eventcatalog.dev/docs/commands/propose-ar-collection-email/0.1.0.mdx) - Workflow #4 — a relationship-aware dunning email queued for approval. The approval IS the send gate; the human can edit subject/body at send.- [Propose Bill-Date Correction - propose-bill-date-correction - 0.1.0 ](https://eventcatalog.dev/docs/commands/propose-bill-date-correction/0.1.0.mdx) - Workflow #2 — the next-day QBO follow-up: correct a bill's TxnDate/DueDate to the vendor invoice date. Queued for approval; applied as a QBO sparse update.- [Propose Customer Invoice - propose-invoice - 0.1.0 ](https://eventcatalog.dev/docs/commands/propose-invoice/0.1.0.mdx) - Workflow #3 — draft a customer invoice (AR) for approval; created in QBO only once a cleared human approves.- [Propose Sales Order - propose-order-entry - 0.1.0 ](https://eventcatalog.dev/docs/commands/propose-order-entry/0.1.0.mdx) - Workflow #8 — draft a Fishbowl sales order (status Estimate) from an approved customer PO; created only once sales approves.- [Propose Vendor Bill - propose-vendor-bill - 0.1.0 ](https://eventcatalog.dev/docs/commands/propose-vendor-bill/0.1.0.mdx) - Workflow #1 — AP intake. Queues a vendor bill as a PENDING proposal; nothing is written until a cleared human approves in the card.- [QBO Create Bill - qbo-create-bill - 0.1.0 ](https://eventcatalog.dev/docs/commands/qbo-create-bill/0.1.0.mdx) - Creates a vendor bill in QuickBooks (the non-PO path of vendor-bill intake).- [QBO Create Invoice - qbo-create-invoice - 0.1.0 ](https://eventcatalog.dev/docs/commands/qbo-create-invoice/0.1.0.mdx) - Creates a customer invoice from approved proposal lines.- [QBO Update Bill (sparse) - qbo-update-bill - 0.1.0 ](https://eventcatalog.dev/docs/commands/qbo-update-bill/0.1.0.mdx) - Sparse-updates one field on an existing bill using a fresh SyncToken (bill-date correction).- [Smartsheet Append Scorecard Row - smartsheet-append-scorecard-row - 0.1.0 ](https://eventcatalog.dev/docs/commands/smartsheet-append-scorecard-row/0.1.0.mdx) - Appends a dated KPI snapshot row to the scorecard sheet, preserving formula columns. The one write that does NOT route through the approval bus.

## Queries
- [Accounting Read (customers · reports · aging) - accounting-read - 0.1.0 ](https://eventcatalog.dev/docs/queries/accounting-read/0.1.0.mdx) - QBO customers, cash-flow/P&L reports and AR/AP aging (OAuth2 with rotated-token write-back).- [Cash Flow Tracker - cash-flow-tracker - 0.1.0 ](https://eventcatalog.dev/docs/queries/cash-flow-tracker/0.1.0.mdx) - Workflow #5 — the unified cash view: QBO cash position + AR/AP aging, Fishbowl open SO/PO, ClaritySoft weighted pipeline, with divergence and runway alerts.- [CRM Read (accounts · contacts · opportunities) - crm-read - 0.1.0 ](https://eventcatalog.dev/docs/queries/crm-read/0.1.0.mdx) - Paginated reads of ClaritySoft accounts, contacts and opportunities (api-key body-envelope auth).- [Daily Pipeline View - daily-pipeline-view - 0.1.0 ](https://eventcatalog.dev/docs/queries/daily-pipeline-view/0.1.0.mdx) - Workflow #7 — ClaritySoft opportunities rolled up by stage (count + value): the company funnel, plus a per-owner slice when requested.- [Find Customer Account - find-customer-account - 0.1.0 ](https://eventcatalog.dev/docs/queries/find-customer-account/0.1.0.mdx) - Resolve one joined customer account by company name (case/space-insensitive).- [Get Card Data - get-card-data - 0.1.0 ](https://eventcatalog.dev/docs/queries/get-card-data/0.1.0.mdx) - Approval-card bootstrap: the proposal's summary, payload and the per-card widget token the Accept/Send button needs. App-only — the assistant cannot call it.- [Get Customer (QBO) - get-customer - 0.1.0 ](https://eventcatalog.dev/docs/queries/get-customer/0.1.0.mdx) - Fetch one QuickBooks customer by id, including its SyncToken (the optimistic-lock key QBO sparse updates require).- [Inventory Read (customers · open SO/PO) - inventory-read - 0.1.0 ](https://eventcatalog.dev/docs/queries/inventory-read/0.1.0.mdx) - Fishbowl customers and open sales/purchase orders via data queries (session-login → bearer re-auth).- [KPI Scorecard - kpi-scorecard - 0.1.0 ](https://eventcatalog.dev/docs/queries/kpi-scorecard/0.1.0.mdx) - Workflow #9 — the L10 cross-system scorecard: 7 KPIs (cash, AR, AP, pipeline, open SO/PO, NWC) with target/status. Optional bounded publish to Smartsheet.- [Lead-Source Read (project candidates) - lead-source-read - 0.1.0 ](https://eventcatalog.dev/docs/queries/lead-source-read/0.1.0.mdx) - Public-source project candidates for Project Hunter (mock feed + stubbed live ETL)..- [List Contacts (CRM) - list-contacts - 0.1.0 ](https://eventcatalog.dev/docs/queries/list-contacts/0.1.0.mdx) - All ClaritySoft contacts as clean domain models, vendor pagination hidden behind an async iterator.- [List Customer Accounts - list-customer-accounts - 0.1.0 ](https://eventcatalog.dev/docs/queries/list-customer-accounts/0.1.0.mdx) - The account-join primitive: every customer joined across ClaritySoft (CRM), QuickBooks (accounting) and Fishbowl (inventory), with presence and linkage flags.- [List Pending Approvals - list-pending-approvals - 0.1.0 ](https://eventcatalog.dev/docs/queries/list-pending-approvals/0.1.0.mdx) - The approval inbox: every proposed mutation still awaiting a human decision.- [Project Hunter - project-hunter - 0.1.0 ](https://eventcatalog.dev/docs/queries/project-hunter/0.1.0.mdx) - Workflow #6 — scores public-source project candidates against the QMax domain, cross-references ClaritySoft (dedup only, never creates a lead), returns a ranked report + digest.- [Sheets Read (scorecard sheet + columns) - sheets-read - 0.1.0 ](https://eventcatalog.dev/docs/queries/sheets-read/0.1.0.mdx) - Smartsheet sheet + column reads (static PAT) used to locate the scorecard sheet and protect formula columns on publish..

## Agents


## Services
- [Approval Bus (command service — owns the queue) - approval-bus - 0.1.0 ](https://eventcatalog.dev/docs/services/approval-bus/0.1.0.mdx) - The command side: owns the proposal queue. propose_* only queue; a cleared human approves in the card; only then does the kind's applier execute the vendor write. Every transition is recorded on the shared store.- [ArCollectionsApplier (workflow #4) - ar-collections-applier - 0.1.0 ](https://eventcatalog.dev/docs/services/ar-collections-applier/0.1.0.mdx) - Applies an approved AR collections email: sends via Microsoft Graph sendMail. The approval IS the send gate; the human can edit subject/body at send.- [BillDateCorrectionApplier (workflow #2) - bill-date-correction-applier - 0.1.0 ](https://eventcatalog.dev/docs/services/bill-date-correction-applier/0.1.0.mdx) - Applies an approved bill-date correction: re-fetches the bill for a fresh SyncToken, then sparse-updates the one date field in QBO.- [CashFlowService — cash-flow read workflow - cash-flow-service - 0.1.0 ](https://eventcatalog.dev/docs/services/cash-flow-service/0.1.0.mdx) - Workflow #5. Fans into QBO (cash position + AR/AP aging), Fishbowl (open SO/PO) and ClaritySoft (weighted pipeline) in parallel, assembles the unified cash view with divergence + runway alerts.- [ClaritySoft CRM - claritysoft-crm - 0.1.0 ](https://eventcatalog.dev/docs/services/claritysoft-crm/0.1.0.mdx) - CRM of record: accounts, contacts, opportunities/pipeline. Read-only in the beta — the first connector going live.- [claude.ai (Max + approval card) - claude-ai - 0.1.0 ](https://eventcatalog.dev/docs/services/claude-ai/0.1.0.mdx) - The host: QMax staff drive the mesh from claude.ai. The Max agent calls queries and propose commands; the human-only approval card calls the app-only execute pair. Connected via remote MCP with Entra OAuth.- [CustomerAccountService — account-join workflow - customer-account-service - 0.1.0 ](https://eventcatalog.dev/docs/services/customer-account-service/0.1.0.mdx) - The account-join primitive: every customer folded across ClaritySoft (CRM), QBO (accounting) and Fishbowl (inventory), with presence + linkage flags. Serves both the list and find tools.- [DailyPipelineService — pipeline read workflow - daily-pipeline-service - 0.1.0 ](https://eventcatalog.dev/docs/services/daily-pipeline-service/0.1.0.mdx) - Workflow #7. Single-source: ClaritySoft opportunities rolled up by stage (count + value) into the company funnel, plus an optional per-owner slice.- [Entity reads — direct foundational-service tools - entity-read-service - 0.1.0 ](https://eventcatalog.dev/docs/services/entity-read-service/0.1.0.mdx) - The two thin entity-read tools: get_customer (QBO, with SyncToken) and list_contacts (ClaritySoft). Direct foundational-service passthrough — no workflow orchestration.- [Microsoft Entra ID (QMax tenant) - entra-id - 0.1.0 ](https://eventcatalog.dev/docs/services/entra-id/0.1.0.mdx) - The identity provider: org-scoped OAuth for QMax staff. Issues the v2 access tokens (audience + scope mcp-access) the gateway verifies on every request.- [Fishbowl Inventory - fishbowl-inventory - 0.1.0 ](https://eventcatalog.dev/docs/services/fishbowl-inventory/0.1.0.mdx) - Inventory/ERP: customers, parts, open SO/PO; the write path is CSV import (draft sales orders, PO-linked bills). NOT LIVE — the long pole; on-prem behind a Cloudflare Tunnel, no sandbox exists.- [InvoiceGenerationApplier (workflow #3) - invoice-applier - 0.1.0 ](https://eventcatalog.dev/docs/services/invoice-applier/0.1.0.mdx) - Applies an approved customer invoice: creates it in QBO with one SalesItemLineDetail per approved line.- [Lead Source (Web) - lead-source-web - 0.1.0 ](https://eventcatalog.dev/docs/services/lead-source-web/0.1.0.mdx) - Public-source project-candidate feed for Project Hunter. Mock feed + stubbed live ETL.- [MCP Gateway (transport + auth) - mcp-gateway - 0.1.0 ](https://eventcatalog.dev/docs/services/mcp-gateway/0.1.0.mdx) - The single front door: the streamable-HTTP MCP endpoint, per-request Entra JWT verification (issuer + audience + scope), bounded sessions, and the OAuth authorization-server proxy.- [Microsoft 365 (Graph) - microsoft-365 - 0.1.0 ](https://eventcatalog.dev/docs/services/microsoft-365/0.1.0.mdx) - Mail: the AR collections send path (Graph sendMail, app-only client credentials). Blocked on admin consent for Mail.Send — deferred with the write phase.- [OrderEntryApplier (workflow #8) - order-entry-applier - 0.1.0 ](https://eventcatalog.dev/docs/services/order-entry-applier/0.1.0.mdx) - Applies an approved sales order: imports a draft SO (status Estimate) via Fishbowl's CSV import path.- [ProjectHunterService — project-hunter workflow - project-hunter-service - 0.1.0 ](https://eventcatalog.dev/docs/services/project-hunter-service/0.1.0.mdx) - Workflow #6. Scores public-source project candidates against the QMax domain rubric, cross-references ClaritySoft for dedup (never creates a lead), returns a ranked report + digest.- [QuickBooks Online - quickbooks-online - 0.1.0 ](https://eventcatalog.dev/docs/services/quickbooks-online/0.1.0.mdx) - Accounting of record: customers, bills, invoices, reports, AR/AP aging. Reads feed cash-flow + scorecard + the account join; writes (bills/invoices) are approval-gated.- [ScorecardService — KPI scorecard workflow - scorecard-service - 0.1.0 ](https://eventcatalog.dev/docs/services/scorecard-service/0.1.0.mdx) - Workflow #9 — the L10 scorecard: 7 KPIs assembled from QBO, Fishbowl and ClaritySoft, with an optional bounded publish (dated snapshot row) to Smartsheet.- [Smartsheet - smartsheet - 0.1.0 ](https://eventcatalog.dev/docs/services/smartsheet/0.1.0.mdx) - Ops sheets: the KPI scorecard target. Read + the one bounded direct write (dated snapshot row append, formula columns preserved).- [VendorBillApplier — AP intake (workflow #1) - vendor-bill-applier - 0.1.0 ](https://eventcatalog.dev/docs/services/vendor-bill-applier/0.1.0.mdx) - Applies an approved vendor bill by PO linkage: PO-linked bills import into Fishbowl (auto-pushes to QBO); non-PO bills post directly to QBO.

## Data Products


## Domains
- [External Systems - external-systems - 0.1.0 ](https://eventcatalog.dev/docs/domains/external-systems/0.1.0.mdx) - Everything outside the mesh: the claude.ai host, the Entra identity provider, and the five vendor platforms behind the connector layer (all fixture-mocked until each goes live).- [QMax Operations (Service Mesh) - qmax-operations - 0.1.0 ](https://eventcatalog.dev/docs/domains/qmax-operations/0.1.0.mdx) - The QMax service mesh: a layered NestJS build exposing the QMax platform as one remote MCP server, split CQRS-style into per-workflow read services and a human-gated approval bus + appliers over a shared proposal store.

## Flows
- [Propose AR Collections Email — command lifecycle - ar-collections-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/ar-collections-flow/0.1.0.mdx) - One propose_ar_collection_email call end to end: queue → human reviews AND CAN EDIT subject/body → approve is the send → Graph sendMail → MutationApplied.
- [Propose Bill-Date Correction — command lifecycle - bill-date-correction-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/bill-date-correction-flow/0.1.0.mdx) - One propose_bill_date_correction call end to end — the recommended FIRST live command: single reversible field, QBO-only, naturally idempotent.
- [Cash Flow Tracker — tool-call lifecycle - cash-flow-tracker-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/cash-flow-tracker-flow/0.1.0.mdx) - One cash_flow_tracker call end to end: the query hits CashFlowService, which fans into QBO + Fishbowl + ClaritySoft in parallel and assembles the unified cash view. No events — reads are direct.
- [Customer Account Join — tool-call lifecycle - customer-account-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/customer-account-flow/0.1.0.mdx) - list_customer_accounts / find_customer_account end to end: the three-system account join (CRM + accounting + inventory) with presence and linkage flags.
- [Daily Pipeline View — tool-call lifecycle - daily-pipeline-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/daily-pipeline-flow/0.1.0.mdx) - One daily_pipeline_view call end to end: single-source into ClaritySoft, rolled up by stage. The simplest read path — and the demo-safe one.
- [Gated Write — the generic command lifecycle - gated-write - 0.1.0 ](https://eventcatalog.dev/docs/flows/gated-write/0.1.0.mdx) - The command path every propose_* shares: the agent proposes, a cleared human approves in the card, the kind's applier executes the vendor write — with every step recorded on the shared store.
- [Propose Customer Invoice — command lifecycle - invoice-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/invoice-flow/0.1.0.mdx) - One propose_invoice call end to end: queue → human approve → applier creates the QBO invoice from the approved lines.
- [KPI Scorecard — tool-call lifecycle - kpi-scorecard-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/kpi-scorecard-flow/0.1.0.mdx) - One kpi_scorecard call end to end: four sources fold into 7 KPIs; with publish: true the service performs the one direct bounded write (a dated Smartsheet snapshot row).
- [Propose Sales Order — command lifecycle - order-entry-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/order-entry-flow/0.1.0.mdx) - One propose_order_entry call end to end: queue → sales approves → applier imports a draft SO (status Estimate) via Fishbowl's CSV import path.
- [Project Hunter — tool-call lifecycle - project-hunter-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/project-hunter-flow/0.1.0.mdx) - One project_hunter call end to end: score the public candidate feed against the domain rubric, cross-reference ClaritySoft for dedup, return a ranked report. Never creates a lead.
- [Propose Vendor Bill — command lifecycle - vendor-bill-flow - 0.1.0 ](https://eventcatalog.dev/docs/flows/vendor-bill-flow/0.1.0.mdx) - One propose_vendor_bill call end to end: queue → ProposalCreated → human approve → ProposalApproved → applier routes by PO linkage → Fishbowl import or QBO bill → MutationApplied.

## Channels


## Containers (Databases, External Systems)
- [Proposal Store - proposal-store - 0.1.0 ](https://eventcatalog.dev/docs/containers/proposal-store/0.1.0.mdx) - The shared CQRS database: every proposal, its payload, status transitions, decisions, results and per-card widget token. Postgres (Drizzle) in the real topology; in-memory in the beta.

## Entities


## Teams
- [visionary-engineering](https://eventcatalog.dev/docs/teams/visionary-engineering.mdx) - Visionary Engineering

## Users
- [george](https://eventcatalog.dev/docs/users/george.mdx) - George
- [jesh](https://eventcatalog.dev/docs/users/jesh.mdx) - Jesh