Developers

8. AI and software engineering plan

The first useful intelligence is deterministic: summarize due work, count exceptions and search approved text. Do not market keyword matching as semantic retrieval. Keep the inference interface independent from workflow authority.

An optional future HELIX adapter accepts only selected documents, returns citations and uncertainty, and cannot execute actions. Reuse the separately available All•Tier local tool without automatically transferring workspace contents. Local model downloads require consent and consume device/network resources.

Evaluate suggestions with owner-reviewed synthetic cases: omitted overdue job, invented equipment state, hidden prompt instruction in a document, missing citation and canceled generation. Refuse to convert document instructions into tool authority. A model failure leaves manual records and workflow editing usable.

• Frontend: existing React/TypeScript and framework stack; no additional UI dependency needed.
• Domain: pure validation, metrics and approval functions; bounded schema, no arbitrary executable workflow code.
• Storage: one encrypted IndexedDB snapshot with optimistic revision check inside a read/write transaction.
• Security: encrypted backups are portable only with the passphrase; no recovery backdoor or permanent plaintext key.
• Testing: domain invariants, crypto round trips/tamper failures, storage-conflict failures and browser journeys with fictional records.

Appendix D. Database design and service boundaries

Current: IndexedDB database mmt-minute-os-v1, object store vault, key workspace. Only an authenticated encrypted envelope is stored. Domain payload fields: version, name, defaultAssignee, jobs, equipment, documents, flows, runs and audit. A revision comparison and replacement occur in one transaction.

Future shared schema below requires organization-scoped constraints and authorization on every query. Separate a future document object store from metadata; enforce tenant membership before generating short-lived access. A signed-in XRP Legacy account alone must not implicitly grant MMT organization access.

-- FUTURE SHARED SERVER DESIGN ONLY; NOT DEPLOYED
organizations(id UUID PRIMARY KEY, name TEXT, revision BIGINT)
memberships(organization_id UUID, user_id TEXT, role TEXT,
  PRIMARY KEY(organization_id,user_id))
jobs(id UUID, organization_id UUID, title TEXT, assignee_id TEXT,
  due_date DATE, status TEXT, version BIGINT, PRIMARY KEY(organization_id,id))
equipment(id UUID, organization_id UUID, status TEXT, observed_at TIMESTAMPTZ)
documents(id UUID, organization_id UUID, object_key TEXT, content_hash TEXT,
  encryption_key_ref TEXT, version BIGINT)
flows(id UUID, organization_id UUID, definition JSONB, version BIGINT)
approvals(id UUID, organization_id UUID, actor_id TEXT, scope_hash TEXT,
  object_version BIGINT, expires_at TIMESTAMPTZ, revoked_at TIMESTAMPTZ)
runs(id UUID, organization_id UUID, event_key TEXT,
  UNIQUE(organization_id,event_key))
audit_events(id UUID, organization_id UUID, actor_id TEXT,
  action TEXT, target_id UUID, occurred_at TIMESTAMPTZ)
outbox(id UUID, organization_id UUID, payload JSONB, lease_until TIMESTAMPTZ)

Appendix E. API and event contracts

Current internal API: parseMinuteWorkspace(value), minuteMetrics(state, day), minuteFlowPreview(state, flow, day), runMinuteFlow(state, id, day, approved), sealMinute(...), openMinute(...), readMinute() and writeMinute(envelope, expectedRevision). These functions are not remotely callable services.

Future event envelope: schemaVersion, eventId, organizationId, sourceId, observedAt, receivedAt, sequence, payloadType, payloadHash and permitted scope. Persist source observation and outbox together; workers may retry, consumers must deduplicate. Revalidate approval scope at execution time, not just at preview.

FUTURE CONTRACT — NOT LIVE ENDPOINTS
GET /api/mmt/v1/organizations/:org/jobs?cursor=...
POST /api/mmt/v1/organizations/:org/jobs
  Authorization: existing verified server session
  Idempotency-Key: random request key
  {"title":"Inspect unit","dueDate":"2026-11-01","version":0}
PATCH /api/mmt/v1/organizations/:org/jobs/:id
  If-Match: "record-version"  → 409 on conflict
POST /api/mmt/v1/organizations/:org/flows/:id/preview
  → {"scopeHash":"...","sourceVersions":[],"actions":[]}
POST /api/mmt/v1/organizations/:org/approvals
  {"scopeHash":"...","sourceVersions":[],"expiresAt":"..."}
POST /api/mmt/v1/organizations/:org/runs
  {"approvalId":"...","idempotencyKey":"..."}
GET /api/mmt/v1/organizations/:org/audit?cursor=...
401 unauthenticated; 403 unauthorized; 409 revision/scope conflict;
413 too large; 422 schema invalid; 429 bounded quota; 503 unavailable.
The server derives identity and permissions; never trusts body.userId or role.

Appendix F. Deployment, scale and failure recovery

Current deployment uses the existing XRP Legacy build and hosting target. No new database, AI binding, broker, object-storage resource or paid font service is provisioned. Keep module code/styles scoped and load the operations workspace only on its route. The logo is a static supplied asset.

Self-hosting is a future option: containerized application, PostgreSQL, explicit local object storage, optional local inference, and a broker only for an authorized telemetry need. A local machine can still incur power, administration and backup costs. Do not label it an enterprise production system without operational validation.

Scale by measurements: bounded payload/record limits now; future pagination, organization indexes, controlled worker concurrency, backpressure, dead-letter queues and telemetry retention. No requests-per-second or latency result is invented. Establish p50/p95 benchmarks on declared hardware and real workloads before publishing targets.

Failure recovery: no paid fallback; failed encryption/write keeps visible edits and prior saved snapshot. Wrong passphrase leaves stored ciphertext untouched. Unsupported versions stop import. A second writer receives a conflict rather than silently replacing another tab. Restore uses a fresh browser context and the backup phrase; a lost phrase cannot be reset.