# Wise Business OS — Product Foundation **Version:** 1.0.0-draft **Status:** Proposed for ratification **Purpose:** Project constitution and authoritative foundation for product, design, architecture, engineering, security, and AI decisions. ## 1. Product Vision Wise Business OS is a modern operating system for service businesses and the agencies that support them. It unifies customer management, sales, communication, scheduling, automation, analytics, documents, knowledge, projects, billing, and AI-assisted work without forcing users to navigate a collection of disconnected tools. The goal is not feature parity with any existing CRM. The goal is to reduce operational complexity while increasing useful automation. Every feature should eliminate work, clarify decisions, or strengthen customer relationships. Configuration is a cost and must earn its place. The CRM is Module One, not the identity of the platform. The long-term product is a Business OS that remains coherent as new capabilities are added. ### Success definition - A new user understands the product’s structure without training. - Common actions are fast on desktop and mobile. - Agencies can manage many isolated client workspaces safely. - AI can complete useful work through governed platform capabilities. - Industry templates reduce setup from hours to minutes. - The architecture supports disciplined evolution for at least three years. ## 2. Product Principles ### AI first AI is an employee, not a detached chatbot. It discovers, summarizes, recommends, prepares, and—when authorized—executes work through the same governed capabilities as other applications. ### Mobile first Every essential workflow must be deliberately designed for phones. Mobile is not a compressed desktop layout. Critical actions must be reachable, readable, and operable by touch. ### Search first Customers, work, settings, commands, documents, and help must be searchable. Keyboard navigation and a command interface are first-class product surfaces. ### Speed first The interface should acknowledge input immediately. Slow work uses optimistic feedback where safe, clear progress, background execution, and recoverable errors. ### Beautiful, calm software Use whitespace, readable typography, restrained glass effects, purposeful motion, strong hierarchy, and minimal clutter. Visual novelty never overrides usability or accessibility. ### Client isolation Every client workspace feels private and complete. Tenant boundaries are enforced in identity, authorization, queries, caching, files, events, analytics, exports, integrations, AI, and logs. ### Progressive disclosure Simple workflows stay simple. Advanced configuration appears only when relevant or enabled. ### Reversible by default Where practical, actions provide previews, drafts, undo, version history, rollback, or recovery paths. ### Documentation is product The manual is reviewed and versioned with the software. Shipped behavior must not contradict the authoritative documentation. ## 3. Domain Model and Ownership The system is organized around bounded business domains rather than pages or database tables. | Domain | Owns | |---|---| | Agency | Agency portfolio, workspace provisioning, templates, plans and agency support access | | Identity | Users, sessions, authentication, memberships, roles, invitations and access evaluation | | Customers | People, organizations, contact methods, consent, tags, custom attributes and customer history | | Sales | Pipelines, stages, opportunities, ownership, forecasts and stage history | | Communications | Conversations, messages, channels, templates, delivery state and communication consent enforcement | | Scheduling | Calendars, availability, event types, appointments, resources and reminders | | Tasks & Projects | Tasks, assignments, recurrence, project work and associations | | Automation | Workflow definitions, versions, triggers, executions, retries and logs | | Analytics | Metrics, dashboards, reports, attribution and anomaly signals | | AI | Capability discovery, planning, tool invocation, approvals, context policy, evaluations and AI audit records | | Billing | Products, prices, invoices, subscriptions, transactions, taxes and entitlements | | Documents | Files, proposals, signatures, templates, retention and access policy | | Knowledge | Articles, SOPs, knowledge sources, indexing and retrieval policy | Each domain owns its business rules, canonical entities, domain events, public capabilities/APIs, tests, documentation and migrations. A domain may reference another domain only through stable identifiers, published capabilities, events, or approved read models. Shared-database convenience must not erase domain ownership. ### Domain contract rules - Public contracts are versioned. - No domain writes another domain’s canonical data directly. - Cross-domain workflows use application orchestration and events. - Breaking contract changes require an ADR and migration plan. - Pages may compose domains; pages do not define domain boundaries. ## 4. Technical Principles ### Capability first, implementation second The constitution specifies durable capabilities and constraints. Current technology choices are recorded separately in ADRs and may evolve without redefining product principles. Required capabilities include: - Edge-capable, serverless application delivery. - Strong transactional storage for canonical business data. - Tenant-safe authorization at every data boundary. - Secure object storage and delivery. - Durable background jobs, retries, scheduling, and dead-letter handling. - Real-time coordination only where the product requires shared state. - Observable, versioned APIs and event contracts. - Accessible components driven by design tokens. - Automated local, integration, security, and end-to-end testing. ### Initial implementation direction The current candidate stack is Cloudflare for delivery and edge services, Supabase for managed PostgreSQL and related data capabilities, and a TypeScript/React application framework with a reusable accessible component system and token-based styling. Cloudflare Workers, R2, Queues, and scheduled execution are preferred where they match the capability. Durable Objects are used only for a demonstrated coordination or shared-state requirement. These are proposed choices, not permanent constitutional laws. Ratification requires ADRs defining ownership of authentication, transactional data, authorization enforcement, files, queues, real-time state, observability, deployment, backups, and disaster recovery. ### Engineering invariants - Type-safe contracts at domain boundaries. - Schema changes are migrated, reviewed, reversible when practical, and compatible during rollout. - Secrets never enter source, logs, events, prompts, analytics, or client-visible payloads. - Background work is idempotent and retry-safe. - External webhooks are authenticated, deduplicated, ordered when required, and retained for diagnosis. - Observability includes correlation IDs across requests, jobs, events, and AI actions. - Performance budgets and accessibility checks are release criteria. ## 5. Event Architecture ### Domain events Domain events record meaningful business facts, such as `CustomerCreated`, `OpportunityStageChanged`, `OpportunityWon`, `AppointmentBooked`, `InvoicePaid`, and `WorkflowPublished`. They are durable business history and may drive automation, analytics, projections, notifications, integrations, audit views, and AI context. Domain events use past-tense names, are immutable, and are emitted only after the underlying state change succeeds. ### System events System events describe operational behavior, such as `UserLoggedIn`, `QueueJobCompleted`, `CacheInvalidated`, `DeploymentFinished`, and `AIRequestFinished`. They support security, reliability, observability, and cost management. They do not masquerade as business facts. ### Standard event envelope Every published event includes: - `eventId`, `eventType`, `eventVersion` - `occurredAt` - `agencyId`, `workspaceId` - `actor` and `source` - `entityType`, `entityId` - `correlationId`, `causationId` - `idempotencyKey` where applicable - minimal, classified payload metadata Sensitive data is referenced rather than copied whenever possible. Event consumers must be independently idempotent. Delivery is assumed to be at least once unless an ADR establishes a stronger guarantee. ### Event catalog governance Every event has an owner, purpose, schema, classification, producers, consumers, retention policy and compatibility rules. New events update the Event Catalog before implementation. ## 6. AI Capability Model AI is a bounded domain and a governed application of the Business OS. It does not own Customer, Sales, Scheduling, Billing, or other domain data and never bypasses those domains. Domains expose capabilities such as: - `customers.search`, `customers.summarize`, `customers.tag` - `sales.createPipeline`, `sales.moveOpportunity`, `sales.forecast` - `tasks.create`, `tasks.prioritize`, `tasks.reschedule` - `scheduling.findAvailability`, `scheduling.prepareBooking` - `analytics.explainTrend`, `analytics.detectAnomaly` ### AI safety levels 1. **Read:** search, summarize, explain. 2. **Recommend:** generate a proposal with rationale. 3. **Prepare:** create a reviewable draft or change plan. 4. **Execute:** perform an authorized reversible action. 5. **Sensitive execute:** send, publish, invite, charge, refund, delete, export, change access, or affect secrets; requires explicit confirmation and possibly step-up authentication. Every capability call applies normal authentication, authorization, tenant scope, validation, rate limits and audit logging. AI plans and tool results carry correlation IDs. Prompts and retrieved context follow data-classification, retention, consent and redaction policies. Model output is never treated as trusted instructions. AI quality is measured with versioned evaluations for correctness, permission adherence, tenant isolation, hallucination resistance, confirmation behavior, latency and cost. ## 7. Security and Tenant Isolation - Deny by default. Every request resolves authenticated user, agency, workspace, membership and capability scope. - Canonical business records include workspace ownership; agency-wide records are explicitly modeled. - Authorization is enforced server-side at the capability/data boundary, never only in navigation or UI. - Access scopes include `all`, `team`, `assigned`, `self`, and `none` where appropriate. - Financial, export, access-management, secret, impersonation and destructive capabilities are separately elevated. - Agency support access is explicit, time-limited where possible, client-visible, and fully logged. - MFA and recent reauthentication protect sensitive actions. - Cache keys, object paths, search indexes, queues, analytics, AI retrieval and exports preserve tenant scope. - Audit records capture actor, effective role, elevation/impersonation, tenant, action, object, before/after summary, origin and correlation ID. - Security tests include cross-tenant negative cases for every domain. ## 8. UI/UX Bible and Design Tokens The UI/UX Bible defines the product’s visual grammar and interaction rules. Components consume semantic tokens; they do not invent local values. ### Token categories - Color: surfaces, text, borders, brand, status and data visualization. - Typography: family, size, weight, line height and tracking. - Spacing: a consistent spatial scale. - Shape: radius and border widths. - Elevation: shadows, overlays and glass opacity. - Motion: durations, easing and reduced-motion alternatives. - Layout: containers, grids and responsive breakpoints. - Interaction: focus, hover, active, selected, disabled, loading and error states. Tokens support light/dark modes, accessibility contrast, future rebranding and controlled client themes. Themes may alter approved semantic tokens but cannot compromise usability or tenant distinction. ### Experience requirements - WCAG 2.2 AA target. - Full keyboard navigation and visible focus. - Command/search interface and documented shortcuts. - Purposeful motion with reduced-motion support. - Skeletons only when they clarify structure; no false progress. - Empty, loading, error, offline and permission-denied states are designed, not improvised. - Touch targets and mobile workflows are tested at defined breakpoints. - Charts include accessible labels, tables or summaries. ## 9. Initial Roadmap ### v0.1 — Core foundation Authentication, tenant/workspace foundation, security model, design system, navigation, dashboard, customers, pipelines/opportunities, tasks, audit trail and foundational events. ### v0.2 — Communication and scheduling Shared inbox, email/SMS adapters, consent, notifications, calendars, availability, booking and reminders. ### v0.3 — Automation Versioned workflow engine, triggers, conditions, actions, waits, testing, execution logs and retries. ### v0.4 — Agency Workspace provisioning, industry templates, plans/entitlements, agency portfolio, controlled support access and billing separation. ### v0.5 — AI Employee Capability registry, conversational command surface, governed execution, evaluations, summaries, recommendations and first industry assistants. ### v1.0 — Public release Production readiness, security review, accessibility conformance, documented APIs/events, operational runbooks, migrations, backups, support tooling and release-quality customer experience. Release scope is controlled by acceptance criteria, not calendar promises. Advanced website building, broad marketing suites, communities, affiliate systems and similar expansion are excluded until core product evidence justifies them. ## 10. Engineering Standards - Small, cohesive modules aligned to domains. - Tests accompany behavior: unit tests for rules, contract tests for boundaries, integration tests for persistence/events, end-to-end tests for critical journeys, and security tests for tenant isolation. - Changes include acceptance criteria, observability, migration/rollback notes and documentation impact. - Code review checks correctness, domain ownership, security, accessibility, performance, tests and manual alignment. - Feature flags are temporary rollout controls with owners and removal dates. - Errors are actionable, safe, correlated and observable. - Dependencies require ownership, update policy, security review and an exit strategy proportional to their criticality. ## 11. Documentation Hierarchy ```text /manual /foundation /roadmap /product-specs /domains /design /data-dictionary /api /events /ai-capabilities /security /adrs /engineering /testing /runbooks /releases ``` Precedence: ratified Product Foundation → accepted ADRs → versioned domain/product specifications → API/event contracts → implementation notes. A lower-level document cannot silently contradict a higher-level one. Each document has owner, status, version, last review date and related ADRs/specifications. ## 12. Governance and Change Control ### Foundation versioning - Patch: clarification without changing intent. - Minor: additive principles, domains or governance. - Major: breaking architectural or product-governance change. The initial ratified version will be **1.0.0**. This draft remains `1.0.0-draft` until formally approved. ### ADR requirement Material architectural changes require an ADR containing context, decision, alternatives, tradeoffs, security/tenant impact, data/event/API impact, migration and rollback, operational impact, and approval. Foundation changes cite the ADRs that justify them. ### Feature lifecycle 1. Update the Product Manual or create the product/domain specification. 2. Record required ADRs. 3. Define acceptance criteria, events, permissions, AI exposure and observability. 4. Implement the feature. 5. Write and pass required tests. 6. Verify security, accessibility and performance. 7. Update the manual and release history to match shipped behavior. ### Definition of ready A feature is ready for implementation when ownership, user outcome, scope, acceptance criteria, permissions, entities, events, APIs, AI capabilities, UX states, risks, tests and documentation impact are defined. ### Definition of done A feature is done when implementation, migrations, tests, security checks, accessibility, telemetry, documentation, operational notes and release records are complete and observed behavior matches the manual. ## Ratification Checklist - Approve product vision and principles. - Confirm initial bounded domains and owners. - Approve event classification and envelope. - Approve AI safety levels and confirmation policy. - Approve tenant-isolation invariants. - Commission ADRs for deployment, authentication, database/authorization, storage, background work, observability and design-system implementation. - Approve roadmap scope and exclusions. - Change status from `Proposed for ratification` to `Ratified` and version to `1.0.0`. No application implementation should begin until this checklist is completed or an explicitly documented exception is approved.