Platform

Shared cloud primitives before customer activation.

Shared accounts, memberships, service subscriptions, entitlements, usage events, billing mirrors, and audit events for tenant-aware LinkRidge Cloud services.

Control-plane API QR service contract Seed review Discuss early access

Status Planning

The public platform shell is being documented before real customer accounts are enabled.

Operator gate Manual

External account activation, billing, invites, production service enablement, and paid access stay manual until Matthew approves them.

First service QR Codes

The first service contract proves tenant isolation, entitlement checks, usage events, and audit events.

Account model

One account boundary for people, services, plans, and history.

Accounts own billing and customer-visible service subscriptions.
Users join accounts through memberships, roles, and invite state.
Entitlements are local records read before a service performs tenant work.
Audit events capture actor, account, service, action, and target context.

Platform lifecycle

Account states

Draft: Internal planning record for a possible account; no login, invite, billing, or service access exists.
Pending approval: Activation packet is locally complete and waiting for Matthew approval before any external action.
Active: Approved account with at least one owner membership and locally enabled services.
Suspended: Access is blocked while audit, billing, support, or operator review is unresolved.

Platform lifecycle

Invite states

Not created: No external invite record exists during platform planning.
Draft: Invite recipient, role, account, and service scope are prepared locally but not sent.
Sent: Outbound invite delivery is allowed only after the invite flow is explicitly approved.
Accepted: User has joined the account and received platform-derived service permissions.
Revoked: Pending or accepted access was removed and should remain visible in audit history.

Platform lifecycle

Service states

Modeled: Service contract and plan limits exist in the catalog but no account is provisioned.
Requested: Account has asked for the service and is waiting for operator review.
Enabled: Service workspace is provisioned and entitlements can be read by the service.
Paused: Service access is disabled without deleting tenant data or audit history.

Core records

Schema planning for the first account-aware services.

These records define the local platform contract before signup, billing, invite delivery, or external service access is enabled.

schema-planning

accounts

Customer, tenant, billing, and ownership boundary for LinkRidge Cloud services.

Fields: id, name, status, primary_owner_user_id, billing_customer_id, created_at, updated_at
Guardrail: Draft records are local planning objects until Matthew approves customer activation.

schema-planning

users

Fields: id, email, display_name, status, created_at, updated_at
Guardrail: No external auth-provider user or invite delivery is implied by this contract.

schema-planning

account_memberships

Account-scoped role assignment that services consume before loading tenant data.

Fields: id, account_id, user_id, role, status, created_at, updated_at
Guardrail: Memberships become active only after approved account activation or invite acceptance.

schema-planning

account_invites

Prepared invite packet for adding a user to an account and optional service scope.

Fields: id, account_id, email, role, service_scope, status, expires_at, created_by_user_id, created_at, updated_at
Guardrail: Invite creation and outbound delivery stay manual until the invite flow is approved.

schema-planning

account_services

Account-to-service enablement record that proves a service may provision tenant defaults.

Fields: id, account_id, service_id, plan_key, status, requested_by_user_id, approved_by_user_id, enabled_at, created_at, updated_at
Guardrail: Service enablement remains modeled or requested until operator approval creates an enabled local record.

schema-planning

service_entitlements

Effective feature and limit values read by services before tenant work is performed.

Fields: id, account_service_id, entitlement_key, kind, value, source, created_at, updated_at
Guardrail: Entitlements are local records first; billing-provider sync is a later approval-gated integration.

schema-planning

usage_events

Append-only service activity used for usage review, limits, billing export, and support history.

Fields: id, account_id, account_service_id, service_id, event_name, quantity, billable, occurred_at, metadata
Guardrail: Events are stored locally before any metered billing export is enabled.

schema-planning

support_cases

Account-service support and operator handoff records used before customer-visible ticketing or escalation workflows exist.

Fields: id, account_id, account_service_id, service_id, category, severity, status, subject, created_by_user_id, created_at, resolved_at, metadata
Guardrail: Support cases are local review records until Matthew approves external ticket creation, customer contact, escalation, or customer-visible timelines.

schema-planning

audit_events

Account-visible and operator-visible change history for platform and service actions.

Fields: id, actor_user_id, account_id, service_id, action, target_type, target_id, occurred_at, metadata
Guardrail: Audit history must be written for approval, activation, invite, entitlement, and service mutations before external access opens.

admin-only-planning

Activation packets stay local until operator approval.

Local review packet used before an account service can move toward operator approval.

Account identity: Draft account name, primary owner, support contact, and intended LinkRidge Cloud service are recorded locally.
Membership plan: Owner role, optional invited users, service roles, and invite status are prepared without sending external invitations.
Service plan: Requested service, plan key, entitlement defaults, workspace defaults, and usage-event expectations are selected from the manifest.
Billing boundary: Billing customer, product, price, subscription, and metered export actions are explicitly marked not created.
Operator review: Approval checklist records reviewer, reviewed-at timestamp, skipped external actions, and unresolved blockers before activation.

schema-planning

Service events share one platform envelope.

Common envelope every service usage or audit event must carry before platform billing, support, or customer-visible history can rely on it.

Events remain local records until Matthew approves any billing export, customer-visible timeline, or externally reachable service workflow.

admin-only-planning

Operator approvals require evidence before activation.

Checklist metadata an operator must complete before a modeled account service can become enabled or externally reachable.

Account identity verified: Draft account name, primary owner email, support contact, and intended service match the activation packet.
Membership scope reviewed: Owner, admin, editor, viewer, and invite scopes are prepared locally with no outbound invite delivery.
Entitlement defaults reviewed: Plan key, feature flags, and usage limits come from the service manifest and do not imply paid billing state.
Usage and audit events ready: Service actions identify account, account service, workspace, actor, event name, target, timestamp, quantity, and metadata.
External actions skipped: Billing writes, invite sends, external access, DNS, and production deploys are explicitly marked skipped unless separately approved.

Decision states

Not started: No local approval packet has been prepared for the account service.
Ready for review: Required checklist evidence exists locally but no approval decision has been recorded.
Approved local only: Operator approved local enablement while billing, invites, external access, DNS, and production deploy actions remain skipped.
Blocked: Missing evidence, unresolved risk, paused account state, or an unapproved external action prevents enablement.

Audit requirement

Every approval decision must write an audit_events entry with checklist keys, decision state, skipped actions, reviewer, account_id, account_service_id, service_id, target_type, target_id, occurred_at, and unresolved blockers.

planning

Rollout readiness moves one local phase at a time.

Ordered local milestones that turn a service manifest into a tenant-aware hosted service without opening billing, invites, DNS, or public customer access early.

Contract ready: Service manifest, tenant keys, entitlement map, event names, and operator gates are documented and rendered from repo data.
Local schema ready: Account, membership, account service, entitlement, usage, audit, and service workspace records can be created in a local/admin-only environment.
Adapter ready: The service can read platform account context, enforce entitlements, and emit usage/audit events while remaining separately deployable.
Operator review ready: Activation packet and approval checklist evidence are complete locally with every external action marked skipped.
Beta candidate: Matthew can review one proposed first account/service activation packet before any invite, billing write, DNS change, or production exposure happens.

admin-only-planning

Local schema scaffolding starts with seed records.

Minimum local records required to prove a tenant-aware account service can be prepared without creating external access.

Draft account: accounts: draft. Internal account identity with name, primary owner placeholder, support contact, and no billing provider customer.
Owner user: users: local_pending. Local identity placeholder used for membership planning without creating an external auth-provider user.
Owner membership: account_memberships: planned. Account owner role mapped locally so service permissions can be evaluated before invites are sent.
Account service: account_services: modeled. Requested service and plan key selected from the manifest while service enablement remains blocked.
Entitlement defaults: service_entitlements: local_default. Feature and limit values copied from the service manifest without syncing billing products, prices, or subscriptions.
Activation audit: audit_events: planned. Audit event shape for the local activation review, including skipped external actions and unresolved blockers.

contract-only

Seed packets make local schema evidence testable.

Admin-only JSON packet shape for proving local seed records can be prepared before a database migration, signup flow, invite delivery, billing sync, DNS change, or production route exists.

Use this packet as the fixture contract for local/admin-only schema tests before adding signup, billing, invite, or hosted service access code.

Required packet fields

packet_id
account
primary_owner
membership
account_invites
service_tokens
account_service
entitlements
service_workspace
qr_campaigns
qr_codes
qr_route_resolutions
qr_import_jobs
local_provisioning_run
operator_approval_decision
approval_audit_events
qr_scan_events
qr_billing_export_requests
qr_support_cases
qr_audit_events
billing_boundary
external_actions
operator_review
audit_event

Validation rules

account.status is draft and account.billing_customer_id is null.
primary_owner.external_auth_provider_user_id is null and membership.status is planned.
account_invites are draft-only local records with delivery not_sent, Matthew approval required, and no external effect performed.
service_tokens are prepared only as local planned records and never issue secret material while Matthew approval is pending.
account_service.status is modeled, service_id comes from services[].id, and plan_key comes from services[].plans[].key.
entitlements are copied from the selected service manifest and mark billing_sync_status as not_created.
service_workspace is prepared only as a local plan and includes account_id, account_service_id, service_id, plan_key, and status.
qr_campaigns are prepared only as local planned records and must resolve through the planned service workspace.
qr_codes are prepared only as local planned records and must resolve through the planned service workspace and optional planned campaign.
qr_route_resolutions are prepared only as fixture evidence and must resolve one slug through the planned QR code, workspace, account service, account, and entitlement checks while leaving redirects disabled.
qr_route_resolutions are exposed through read-only /v1 fixtures with external_redirects_enabled false before hosted redirect routing exists.
qr_import_jobs stay planned, resolve through the planned account service and workspace, reconcile source Open QR slugs locally, and perform no import or external redirect effect.
local_provisioning_run is a rehearsal-only record that references the packet, account service, workspace, local record list, blocked external writes, and next operator action without executing provisioning.
operator_approval_decision is a local-only decision fixture that resolves the packet, account service, workspace, and reviewer boundary while keeping activation blocked pending Matthew approval.
approval_audit_events records the operator decision outcome locally, ties it to the decision id, and keeps every approval-gated action blocked.
qr_scan_events are prepared only as non-exported fixture evidence and must resolve through the planned QR code, workspace, account service, and account.
qr_billing_export_requests are prepared only as blocked billing-review evidence and must resolve through local scan events while leaving metered export disabled.
qr_support_cases are prepared only as local operator handoff evidence and must resolve through account, account service, workspace, and optional QR target while customer notifications, external tickets, escalations, customer timelines, and service-status changes remain blocked.
qr_audit_events are prepared only as local audit evidence and must resolve through the planned QR code, workspace, account service, and account.
external_actions marks billing, invite, DNS, production route, and customer access writes as skipped.
audit_event records the packet review target, skipped actions, unresolved blockers, and operator decision state.

fixture-checked

Provisioning rehearsals prove what stays local.

Local-only rehearsal contract for preparing tenant-aware records from a seed packet without creating auth users, billing records, invites, DNS, external QR redirects, or production routes.

Statuses: rehearsal_only, ready_for_local_operator_review, blocked.

Run fields

status
run_id
source_packet_id
account_id
account_service_id
service_id
qr_workspace_id
requested_by_user_id
approved_by_user_id
started_at
completed_at
local_records_prepared
external_writes_blocked
next_required_operator_action
result

Exit criteria

The run references exactly one local seed packet, draft account, modeled account service, planned workspace, and local requester.
started_at, completed_at, approved_by_user_id, and result prove no provisioning execution or approval has happened.
Every blocked external write remains listed before local schema or adapter code can claim readiness.

fixture-checked

Operator decisions stay local until Matthew approves activation.

Local-only operator decision record that captures whether a reviewed seed packet may move past review while customer activation, billing, invites, DNS, hosted redirects, and production deploys remain blocked.

Statuses: not_started, blocked_pending_matthew_approval, approved_local_only.

Decision fields

status
decision_id
source_packet_id
account_id
account_service_id
service_id
qr_workspace_id
reviewer_user_id
decided_at
decision_state
required_approval
approved_actions
blocked_actions
audit_event_action
result

Exit criteria

The decision references one seed packet, draft account, modeled account service, QR service id, and planned workspace.
reviewer_user_id and decided_at stay null while Matthew approval has not been recorded.
approved_actions stays empty and every approval-gated action stays blocked before local enablement or external access can proceed.
The decision result stays not_executed until a future admin-only tool records an explicit local-only approval.

fixture-checked

Approval decisions must leave local audit evidence.

Local platform audit evidence that records the blocked operator decision before any activation, billing, invite, DNS, hosted redirect, or production deploy action is allowed.

Allowed actions: account_service.operator_decision_blocked, account_service.operator_decision_approved_local_only.

Audit fields

id
account_id
account_service_id
service_id
action
target_type
target_id
actor_user_id
occurred_at
metadata

Exit criteria

The audit row references the same account, account service, service, and decision id as the operator approval decision fixture.
actor_user_id and occurred_at stay null while Matthew approval has not been recorded.
metadata.approved_actions stays empty and metadata.blocked_actions carries every activation-gated action.
metadata.external_actions remains skipped so the audit row cannot imply billing, invite, DNS, redirect, or deploy work occurred.

Seed service Hosted utility

QR Codes

Tenant-aware hosted QR code workspaces based on the separately deployable Open QR seed app.

Service id: qr-codes
Source: makersridge/open-qr

Service contract