> For the complete documentation index, see [llms.txt](https://wiki.fridays.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.fridays.bot/documentation/white-paper/1.-introduction.md). # 1. Introduction #### 1.1 Problem statement: the owner as the integration layer A US small business with payroll operates, on average, a stack of 8–15 SaaS products spanning accounting, email, calendar, CRM, invoicing, file storage, and scheduling. These products expose APIs but do not interoperate by default; the semantic joins between them — "this Gmail thread is about that QuickBooks invoice, which belongs to that Zoho contact" — exist only in the owner's head. The owner is, functionally, the integration layer: a human ETL process performing re-entry, reconciliation, and follow-up. The measurable consequence is cash-flow degradation driven by process failure rather than demand failure. The Federal Reserve Banks' Small Business Credit Survey reports uneven cash flow as a top financial challenge for roughly half of employer firms \[2], and the dominant mechanical cause — late or absent invoice follow-up — is a scheduling problem, not a solvency problem. The population affected is large: the SBA Office of Advocacy counts 36.2M US small businesses, of which \~6.3M are employer firms with payroll and non-trivial transaction volume \[1]. Two existing product classes fail this population for structural reasons: 1. **Workflow builders (Zapier, Make, n8n).** These require the user to decompose their intent into trigger→action graphs, select apps and fields, and maintain the graph as vendor APIs change. This is a programming activity with a different buyer persona. The empirical failure mode is not that workflows can't be built — it is that they silently break (schema drift, token expiry, rate limits) and the SMB owner has neither the alerting nor the debugging context to notice. A Zap that stops firing on a revoked OAuth token fails *open*: invoices simply stop being chased. 2. **Suite-native assistants (Intuit Assist, Zoho Zia, Microsoft Copilot).** Each operates within its vendor's data boundary. But the highest-value SMB tasks are precisely the cross-boundary joins — an overdue invoice (QuickBooks) requires the customer's email thread history (Gmail) and deal context (Zoho) to draft a follow-up that doesn't damage the relationship. No suite vendor has an incentive to orchestrate a competitor's data plane. The gap is a horizontal execution layer that (a) holds authenticated access to the full stack, (b) performs the cross-app joins autonomously, and (c) remains controllable by an owner who will not read logs, write rules, or configure anything. #### 1.2 Design thesis: outcomes over workflows, autonomy gated by approval Fridays is built on two theses. **Thesis 1 — Ship outcomes, not a canvas.** Frontier LLMs (2025–2026 generation) reliably execute multi-step, tool-using tasks when the task is specified as a *goal plus constraints* rather than a step graph. The engineering consequence: Fridays ships **playbooks** — declarative goal specifications ("all invoices >14 days overdue have an active follow-up cadence") that a planner compiles into tool-call sequences at runtime, adapting to the tenant's actual data. The user configures nothing. This inverts the workflow-builder model: schema drift and API changes are absorbed by the planner and the connector layer, not surfaced to the user. (Section 5 formalizes the playbook model; Section 11 covers how playbook correctness is regression-tested.) **Thesis 2 — Autonomy is only deployable if gated.** Survey and field evidence consistently rank *loss of control* as SMB owners' primary objection to AI acting on their business — an agent that emails a customer the wrong amount destroys more trust than it saved in labor. Fridays therefore treats human approval as a first-class architectural primitive, not a UX afterthought: every action is risk-classified (money movement, external communication, record mutation — Section 6.1), and actions above the tenant's threshold suspend into a mobile **approval feed** requiring a single tap. This design does triple duty: * **Product:** converts the control objection into the core interaction. * **Safety:** bounds the blast radius of model error and prompt injection (an injected instruction to wire funds still terminates at an approval card the owner sees — Section 8.2). * **Compliance:** approval-gated execution constitutes meaningful human involvement, taking money-affecting decisions outside the scope of "solely automated processing" under GDPR Art. 22(1) \[4] — argued fully in Section 6.4 and 12.3. A corollary of both theses: every action must flow through a single mediation point. Fridays routes *all* tool traffic — including traffic to vendor-official MCP servers \[3] — through its own gateway, where policy checks, approval interception, metering, and audit logging occur (Sections 3.3, 7). A connector that could act without traversing the gateway would be an unauditable side channel; none exists by construction. #### 1.3 Scope of this paper and non-goals **In scope:** * The integration layer: transport selection (vendor MCP vs. custom REST wrapper vs. unified aggregator), webhook ingestion, rate-limit governance, and sandbox strategy across \~50 vendors in 15 categories (Section 3). * Identity and secrets: OAuth lifecycle, token vault, renewal infrastructure (Section 4). * Agent orchestration: playbook compilation, planner/executor separation, cross-vendor consistency without distributed transactions (Section 5). * The approval model as a formal control (Section 6). * Audit, security (with prompt injection via untrusted vendor data as the primary threat), privacy, reliability, evaluation, and the AI-governance mapping (Sections 7–12). **Non-goals (explicitly out of scope for the system and this paper):** * **General-purpose agent platform.** Fridays does not expose a chat interface for arbitrary tasks or a builder for user-defined workflows. The playbook catalog is first-party and version-controlled; correctness guarantees (Section 11) are only tractable over a closed task set. * **Foundation model training.** Fridays consumes commercial LLM APIs under model-tier routing (Section 5.6). No customer data is used to train foundation models (Section 9.5). Per-tenant learning is limited to approval-threshold calibration (Section 6.2). * **System of record.** Fridays reads from and writes to the tenant's existing systems (QuickBooks remains the ledger; Zoho remains the CRM). It maintains no parallel canonical copy beyond the operational cache and the immutable action log (Section 7.1). This bounds both the privacy surface (Section 9) and the migration cost of leaving — an intentional trust property. * **Enterprise ITSM.** Multi-approver chains, RBAC hierarchies, and change-advisory workflows are out of scope; the target tenant has one to three approvers. #### 1.4 Terminology Definitions used throughout; the full glossary is Appendix D. | Term | Definition | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tenant** | One business: its connected vendor accounts, users, policies, and data partition. | | **Connector** | The per-vendor adapter (MCP client, REST wrapper, or aggregator binding) that exposes a vendor's capabilities as typed tools. | | **Tool** | A single typed, schema-validated operation (e.g., `quickbooks.invoice.list`, `gmail.draft.create`). The only unit in which the system can act. | | **Action** | One policy-checked invocation of a tool against a tenant's live data, with an idempotency key, risk class, and audit record. | | **Playbook** | A first-party, versioned goal specification: objective, constraints, permitted tool set, and risk policy. Compiled to plans at runtime; never authored by tenants. | | **Plan** | The tool-call DAG a planner emits for a playbook instance; cacheable (Section 5.2, 13.1). | | **Risk class** | The classification of an action by consequence: money movement, external communication, record mutation, read-only (Section 6.1, Appendix B). | | **Approval threshold** | The per-tenant, per-risk-class boundary above which an action suspends for human approval. Initialized from static policy; calibrated from the tenant's approval history (Section 6.2). | | **Approval feed** | The mobile surface where suspended actions are approved, denied, or expired; each decision is itself an audited event. | | **Gateway** | The single mediation point through which every action passes: policy check → approval interception → execution → metering → audit log (Sections 3.3, 7). | | **Aggregator** | A third-party unified API (e.g., Finch for payroll/HRIS, Merge for HRIS) used where per-vendor integration cost is disproportionate (Section 3.2.3). | *** #### References (Section 1) \[1] SBA Office of Advocacy, *2025 Small Business Profiles for the States, Territories, and Nation* (June 2025) and *Frequently Asked Questions About Small Business* (Feb 2026). 36.2M small businesses; \~6.3M employer firms; 43.5% of GDP. \[2] Federal Reserve Banks, *Small Business Credit Survey: Report on Employer Firms* (2025). Uneven cash flow reported as a top financial challenge by \~51% of employer firms. \[3] Anthropic, *Model Context Protocol* specification (Nov 2024, revised 2025). Open standard for agent-facing tool servers; the basis for Section 3.2.1 transport decisions. \[4] Regulation (EU) 2016/679 (GDPR), Art. 22(1): right not to be subject to a decision "based solely on automated processing" with legal or similarly significant effects. \[5] Regulation (EU) 2024/1689 (AI Act), Art. 50: transparency obligations for AI systems interacting with natural persons; machine-readable marking obligations phasing in Dec 2026. Treated in Section 12.1. \[6] S. Willison, *Prompt injection: what's the worst that can happen?* (2023) and subsequent taxonomy. Primary threat model for Section 8.1–8.2. *** *Next: Section 2 (System Overview) — architecture diagram, component inventory, request lifecycle, trust boundaries.* *** ### As-Built Reconciliation — V1 *Reconciles the aspirational architecture above against the shipped platform — the `backend` control plane (MIT, v0.3.1) — documented by engineering. **EXISTS** = shipped/verifiable in backend; **PLANNED** = on the roadmap, not built; **ASPIRATIONAL** = specified above with no current backend counterpart and not on the roadmap (a decision, not a commitment). Sources: SA system-architecture · AO agent-orchestration · IS integration-strategy · SC security-and-compliance · TS technology-stack · MR methodology-and-roadmap.* | § | Status | As-built reality (source) | | ------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1.1 Owner as integration layer | — | Thesis; echoed in MR §6, SA §1. No build claim. | | 1.2 Thesis 1 (playbooks/outcomes) | **PLANNED** | "Playbook" ≈ backend **routines** + agent config; no first-party playbook catalog exists. AO §5. | | 1.2 Thesis 2 (approval-gated) | **EXISTS** (primitives) | Issue interactions (`request_confirmation`, `wake_assignee`), review stages, board approvals ship today. SC §5, AO §4. | | 1.2 corollary — *single gateway routes all tool traffic incl. vendor MCP* | **ASPIRATIONAL** | Backend has **no single gateway**. IS §4.1 route 2: runtime-attached MCP tool calls happen *inside the agent process, not through an audited surface*. "No un-audited side channel by construction" is **not yet true** — the sharpest as-built gap (Tier-1 C). | | 1.3 Non-goals | **aligned** | Bounded scope, no open agent loop, not system-of-record — all consistent with backend's actual design. AO §9, IS §1. | **Terminology → backend primitive:** Tenant ≈ **company** (EXISTS); Connector ≈ **plugin**, connector category (substrate EXISTS, connectors PLANNED); Tool ≈ plugin namespaced tool / adapter tool (EXISTS); Action ≈ issue interaction / tool call (EXISTS); Playbook ≈ routine + agent config, *no first-party catalog yet* (PLANNED); **Gateway ≈ no counterpart (ASPIRATIONAL)**; Aggregator ≈ (PLANNED). **Flag:** the single-mediation-point invariant is this paper's spine and the biggest delta from as-built. Everything downstream that "derives from the gateway" (audit completeness, injection backstop, metering) inherits that gap until the runtime-MCP write path is closed behind audited plugin tools (IS §4.1). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.fridays.bot/documentation/white-paper/1.-introduction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.