Status#
Founder-approved architecture decisions 21 through 64, consolidated July 12, 2026.
This document governs the long-term platform direction while preserving one deliberately narrow first release: a read-only Roam Free shadow pilot for Austin East Bird. Future capability is represented through contracts, policy boundaries, and version fields. It does not expand the MVP implementation scope.
Executive architecture#
The company is a neutral acceleration layer, not another closed property-management SaaS product. It preserves client-owned operating data, reconciles signals from replaceable vendors, presents trustworthy information beautifully, and provides governed interfaces through which people, software, and AI agents can build.
The implementation begins as a modular monolith with PostgreSQL and object storage. Its logical boundaries preserve future managed-cloud, client-cloud, and local/private deployment modes. The UI is a replaceable renderer over stable APIs, schemas, metrics, workflows, policies, and audit evidence.
The first product surface is a standard Property Data Health scorecard with bounded customization. Clients may later use Claude, another agent, a visual builder, structured forms, or an API to propose their own scorecard overlay. Every authoring surface produces the same portable declarative document and passes the same validation, access, cost, provenance, and approval controls.
Capability, action, and workflow governance#
Decision 21 — Mandatory capability manifests#
Every integration, agent, webhook, and custom component declares a machine-readable manifest covering data access, proposed actions, contacted systems, received fields, write ability, approval level, retries, idempotency, retention, model use, version, and publisher. Undeclared capabilities are denied.
Decision 22 — Explicit capability grants#
Workspace administrators approve capabilities at installation. Low-risk reads may remain authorized; sensitive reads and writes are purpose-specific. High-impact actions require per-action or approved-batch authorization. New capabilities introduced by an update remain suspended until reapproved.
Decision 23 — Credential isolation#
Credentials are encrypted per workspace. Agents, templates, plugins, and models never receive raw credentials. A connection broker performs authorized operations after checking policy, scope, approval, and rate limits. Clients may rotate or disconnect credentials without rebuilding workflows.
Decision 24 — Universal action contract#
Every operation from our UI, a client UI, an API, an agent, or a webhook becomes the same typed action request. Requests carry actor, purpose, target, version, inputs, expected result, required capabilities, approval level, idempotency key, validation, status, evidence, and reversal guidance.
Decision 34 — Declarative durable workflows#
Business processes are versioned workflows made of typed read, validation, transformation, human-input, AI-proposal, approval, execution, notification, and export steps. Runs persist across long pauses. The MVP uses a lightweight database-backed state machine; a heavier orchestrator waits for demonstrated need.
Decision 36 — Staged agent authority#
Agents advance through sandbox, shadow, supervised, bounded-autonomy, and expanded-autonomy levels. Promotions require evaluation, security evidence, shadow history, limits, ownership, rollback, and explicit approval. Material model, prompt, tool, policy, or schema changes may return an agent to shadow mode.
Decision 39 — Governed client-agent gateway#
Client-owned agents receive individual service identities, scoped short-lived credentials, declared capabilities, budgets, limits, processing rules, approvals, and kill switches. They use governed APIs and action contracts rather than direct databases or vendor credentials. REST/OpenAPI is first; protocol adapters such as MCP remain replaceable edges.
Data truth, history, and identity#
Decision 25 — Historical ledger plus current views#
Source observations, human decisions, AI proposals, transformations, approvals, and external actions create append-only events. Corrections supersede history rather than rewriting it. Fast current-state views serve dashboards and APIs while every displayed value remains traceable.
Decision 26 — Multi-source truth resolution#
Sources submit claims; they do not directly overwrite governed records. Every material field retains source values, observation time, reliability, freshness, transformations, governed value, selection reason, selector, and unresolved conflicts. Critical identity, financial, compliance, access, and safety fields require deterministic or human authority.
Decision 29 — Universal core plus domain packs#
The core owns workspaces, actors, entities, relationships, observations, governed values, files, artifacts, events, actions, policies, approvals, schemas, templates, views, provenance, and external links. STR, CRM, bookkeeping, compliance, websites, and later industries extend it through versioned domain packs.
Decision 30 — Universal entity graph#
Important objects receive permanent platform IDs independent of vendors. External identifiers attach to those entities. Relationships are typed and time-aware. Possible matches remain separate from confirmed links; merges and splits are governed, auditable, and reversible.
Decision 31 — Data-health contracts#
Every governed dataset and integration declares freshness, required fields, formats, ranges, acceptable conflicts, expected volume, cadence, dependencies, owner, and escalation thresholds. Health evaluates freshness, completeness, validity, consistency, lineage, and delivery reliability.
Decision 32 — Standard connector lifecycle#
Connectors discover objects, capture immutable snapshots, normalize observations, track cursors, process incremental changes, reconcile against later full snapshots, quarantine ambiguity, and emit lineage and health evidence. Retries are idempotent. Read access never implies write authority.
Decision 60 — Vendor-neutral migration framework#
Stable platform contracts remain independent of PMS identifiers. Migrations use snapshot, mapping, loss analysis, dry run, reconciliation, approval, staged cutover, final comparison, and rollback evidence. Vendor-specific extensions remain preserved rather than discarded during normalization.
Decision 61 — Explicit connected-system roles#
Each connection declares field- or object-scoped roles: observation source, field authority, managed destination, notification destination, export destination, or archive source. New connections default to observation-only. Role changes require preview, approval, effective date, and audit history.
Client ownership, access, and deployment#
Decision 27 — Enforceable ownership and exit portability#
Clients continuously access and export their governed data. Portability packages include open-format records, schemas, source crosswalks, templates, compositions, provenance, audit history, files, evidence manifests, and integration mappings. Client data, configurations, mappings, and generated business artifacts remain portable.
Decision 28 — Control-plane/data-plane separation#
The control plane manages workspaces, schemas, policies, grants, workflows, health, and deployment coordination. The data plane stores and processes records, files, credentials, embeddings, and model inputs. Both run together for the MVP but retain boundaries for client cloud, server, or local/private operation later.
Decision 33 — Multiple stable client interfaces#
Governed data is available through versioned REST/OpenAPI, signed webhooks, JSON/CSV exports, and snapshot/change feeds. GraphQL or warehouse delivery waits for demand. Client tools never couple directly to the operational database.
Decision 40 — Hybrid human authorization#
Simple roles are refined by data class, property, portfolio, department, purpose, action, risk, time, and responsibility. Permissions deny by default and remain auditable. High-impact actions may require separate approvers.
Decision 41 — Just-in-time support access#
Our staff receive no standing client-data access. Support access requires a ticket, purpose, technician, scope, expiration, and normally client approval. Break-glass access is limited to genuine emergencies with immediate notice, enhanced logging, and post-incident review.
Decision 59 — Hierarchical organizations#
The workspace is the primary security boundary. Portfolios, regions, departments, properties, owners, and teams form internal scopes. Managed-service and future partner organizations remain separate and receive delegated access without cross-client data flow.
Decision 63 — Separation from Roam Free#
Roam Free is the design partner and first test tenant. Before unrelated external sales, the platform operates under a neutral company and brand with separate infrastructure, identities, contracts, billing, and support access. Roam Free personnel receive no privileged access to other clients.
AI privacy and cost governance#
Decision 35 — Data classifications and processing zones#
Fields and artifacts are classified as public, internal business, confidential client, sensitive operational, or regulated/highly restricted. Policy determines whether processing is deterministic-only, client-local AI, client-cloud AI, our private AI environment, or an approved external model.
Decision 37 — Unified cost governance#
Every AI or automation execution attributes model tokens, tool charges, storage, local compute, and third-party actions to workspace, actor, workflow, purpose, provider, and payer. Platform-funded, client-funded, and bring-your-own modes share budgets, warnings, hard stops, per-run ceilings, and cost reporting.
Decision 38 — Policy-driven model routing#
Workflows request capability and quality rather than a provider by default. Routing considers privacy, evaluation performance, cost, latency, availability, client preference, local/external execution, and structured-output requirements. The least expensive proven-capable option is preferred; escalations are explained and auditable.
Decision 57 — Governed outcome learning#
The platform records whether recommendations were accepted, modified, rejected, or ignored, plus reasons, outcomes, cost, resolution time, and metric improvement. Production feedback creates versioned improvement proposals; it never silently retrains agents or changes policies. Cross-client training requires explicit permission.
Decision 58 — Opt-in benchmarking#
Cross-client benchmarking is disabled by default. Participation is explicit and revocable, uses certified metrics, requires minimum cohort sizes, suppresses identifiable groups, and never exposes another client's underlying records. It is outside the MVP.
Scorecards and composable client experiences#
Decision 48 — Standard scorecard with governed overlays#
We offer a supported standard scorecard and permit separate client customization overlays. Standard improvements can flow beneath an overlay. Upgrades produce compatibility previews and surface conflicts rather than overwriting client intent. Complex executable extensions remain isolated plugins.
Decision 49 — Governed metric layer#
Metrics have versioned definitions covering meaning, formula, sources, grain, time behavior, unit, dimensions, filters, freshness, quality dependencies, access class, owner, and approval. Clients and agents compose approved metrics rather than writing unrestricted SQL.
Decision 50 — Visible support tiers#
Metrics, components, workflows, and scorecards are platform-certified, client-governed, or experimental/plugin. We support the runtime and compatibility of client-governed work while the client owns its business meaning unless it purchases certification.
Decision 51 — First standard scorecard#
The first scorecard is Property Data Health for Austin East Bird. It displays identity, verified location, connected sources, latest observations, completeness, freshness, conflicts, governed values, provenance, blockers, recommendations, owners, status, and exports. Future business modules remain visibly not evaluated.
Decision 52 — Included customization boundary#
Clients may reorder, resize, show, hide, relabel, filter, brand, adjust approved thresholds, select visualizations, create audience views, and add approved metrics or components. Provenance, freshness, conflict, health definitions, access controls, certification status, and audit/version information cannot be obscured.
Decision 53 — One format, multiple authoring surfaces#
Visual drag-and-drop, conversational AI, structured forms, and API/schema-as-code all edit one portable declarative scorecard document. AI proposes validated patches and never rewrites a published scorecard directly. The MVP renders the standard scorecard and supports JSON import/export, validation, and preview.
Decision 54 — Governed query compiler#
Scorecards request approved metrics, dimensions, filters, and ranges declaratively. The compiler enforces tenant and row access, classification, compatibility, workload, cost, result size, and freshness. Expensive work runs asynchronously; unsafe or ambiguous requests fail with useful explanations.
Decision 55 — Policy-aware distribution#
The same scorecard can serve authenticated live views, embedded views, scheduled snapshots, and APIs. Live access requires identity by default; embedded tokens are short-lived and audience-scoped. Public sharing requires an explicitly sanitized publication profile. The MVP implements a mobile live view and on-demand exports.
Decision 56 — Evidence-to-action loop#
Scorecard issues may create structured recommendations containing cause, importance, evidence, confidence, impact, action, owner, urgency, cost, approval, and completion proof. Recommendations launch governed workflows and never bypass capability controls. MVP recommendations remain read-only and manually resolved.
Reliability, security, and evolution#
Decision 42 — Explicit retention and deletion#
Every class declares retention and deletion behavior. Deletion removes content from active storage and indexes, expires backups, revokes derived access, and leaves only a non-sensitive audit tombstone. Legal holds are visible and time-bounded. Clients receive deletion-completion evidence.
Decision 43 — Tiered recovery#
The shadow MVP uses encrypted daily backups outside the primary failure location, a 24-hour recovery-point target, a 24-hour restoration target, and verified restore tests. Before client production writes, critical data requires point-in-time recovery, immutable copies, tested failover, and tighter one-hour/four-hour targets.
Decision 44 — Privacy-safe observability#
Requests, syncs, workflows, AI runs, approvals, and actions share correlation IDs. Metrics, structured logs, traces, and audit events avoid raw client data by default. Sensitive fields and secrets are automatically redacted. The MVP begins with structured logs, correlation IDs, health metrics, and audit evidence.
Decision 45 — Modular monolith first#
One deployable application contains enforced modules for identity, ingestion, governance, composition, policy, workflows, AI/cost, APIs/exports, and audit. Modules communicate through owned contracts, durable jobs, and an outbox. Services are extracted only after measurable operational pressure.
Decision 46 — Compatibility-first versioning#
APIs, events, schemas, templates, workflows, metrics, and manifests carry versions. Additive evolution is preferred; breaking changes receive new major versions and migration previews. Clients can pin versions. Historical artifacts retain the exact versions that produced them.
Decision 47 — Synthetic-first testing#
Development and CI use fabricated workspaces and source simulators for normal, malformed, missing, duplicate, delayed, rate-limited, reordered, partial, and conflicting behavior. Production data stays out of developer laptops, logs, fixtures, and model evaluations by default.
Decision 62 — Security-ready, certification on demand#
Controls map to NIST CSF, NIST AI RMF, and OWASP ASVS. Audit evidence starts immediately, but paid SOC 2 or ISO 27001 work waits for qualified demand. Independent security review, isolation testing, appropriate penetration testing, incident planning, privacy contracts, insurance review, and a security summary precede external sensitive-data engagements.
Frozen MVP boundary#
Decision 64 — Read-only Roam Free shadow pilot#
The MVP is complete when Austin East Bird has a permanent platform identity; authorized observations from the approved sources can be captured and compared; original evidence and corrections remain reconstructable; human-confirmed identity and location values are governed; data-health issues are explained; the mobile Property Data Health scorecard and JSON/CSV/evidence exports work; isolation, retention, audit, connector-failure, backup, and restore tests pass; and the approved three-snapshot/five-day shadow cadence produces a final pilot report.
The MVP explicitly excludes production writeback, automated remediation, a full drag-and-drop builder, autonomous agents, revenue/pricing intelligence, full-portfolio rollout, external paying clients, and a SOC 2 audit.
Build translation#
The frozen decisions translate into five non-overlapping delivery groups after the current M2 runtime completes:
- Decision reconciliation: record these approvals in canonical ADRs and reconcile older MVP language without changing accepted historical evidence.
- M3 identity and observation: implement Austin East Bird's permanent identity, approved source observations, human confirmation, location structure, source roles, and conflict representation.
- Property Data Health: implement the standard metric catalog, transparent health statuses, provenance drill-down, recommendation records, and mobile read-only scorecard.
- Portability and reliability: implement JSON, CSV, evidence manifests, retention/deletion receipts, backup/restore evidence, isolation tests, and the pilot runbook.
- Shadow acceptance: execute three authorized snapshots over five days, measure operating effort and correctness, and publish the final pilot decision report.
No group is authorized to consume a live request, use client data, contact a model, or write to a source merely because this document describes the future architecture. Runtime authority remains milestone- and purpose-specific.
Revisit triggers#
Revisit these decisions only when evidence changes the trade-off, including sustained scale pressure, a qualified client procurement requirement, repeated connector demand, a proven need for independent services, a breaking contract, new privacy obligations, or measured client value that supports broader scope.