# Bridge Platform Architecture Standard V1.0

## Product objective

V1 proves that independently configurable Flask apps can be sold and composed
through WordPress: for example an AI agent can use AroFlo, QR and messaging/OTP
in one customer solution. The immediate goal is a reliable demonstrator and
commercial pilot, not a premature rewrite of the entire platform.

## V1 layers

1. **Bridge Platform kernel** — runtime, tenant context, authentication,
   entitlements, quotas, storage, secrets, logging, contracts and invocation.
   It contains no customer-specific business workflows.
2. **Apps** — QR, messaging, AroFlo, invoices and future business capabilities.
   Each owns its business rules and publishes versioned operations.
3. **WordPress App Packs** — presentation and adapters that call the Bridge.
   They do not contain provider credentials or duplicate server rules.
4. **Solutions (Composer Plugins)** — commercial WordPress experiences that
   compose multiple app operations, such as Secure QR Access or Invoice
   Approval. In V1 these are curated integrations, not a new runtime layer.

## Mandatory boundaries

- Apps communicate through Bridge contracts, not direct imports of another app.
- Public operations have versioned input/output schemas and permissions.
- Every request carries tenant and correlation context.
- Side effects are idempotent, authorized, quota-aware and auditable.
- Apps use platform storage and secrets facilities; secrets never enter an App
  Pack or manifest.
- WordPress is an adapter/client. Server-side policy remains authoritative.
- V1 app registration is explicit and reviewed. Copy-to-install discovery is
  deferred until manifests, trust and lifecycle rules are mature.

## V1 release gate

An app is demonstrable only when its unit tests pass, manifest validates, its
WordPress pack calls the Bridge, tenant isolation and permission failures are
tested, secrets are externalized, and a real end-to-end scenario is recorded.
Database changes additionally require a known revision, backup and explicit
target database.

## V2 evolution backlog

The following improvements are deliberately documented, not partially built:

1. Split Alembic histories and ownership for control-plane and tenant databases.
2. Introduce a central Contract Registry with owner, schemas, permissions,
   version, deprecation and replacement metadata.
3. Route all cross-app invocation by capability/operation through that registry.
4. Add signed app installation, lifecycle and safe manifest discovery.
5. Model identity as subjects (people, devices, kiosks, APIs and agents) and
   expose verification methods independently of QR or messaging.
6. Consolidate secrets/credentials behind a single audited service contract.
7. Formalize Solutions/Composer Plugins and dependency compatibility rules.
8. Package the Python project for reproducible installs and worker processes.
9. Expand isolated test environments and contract compatibility tests.
10. Automate release evidence, observability, backup verification and rollback.

These items must not block V1 demonstrations unless they create an immediate
security, data-integrity or tenant-isolation risk.

## Commercial model and learning loop

Monetization should map to customer value while reusing the same capabilities:

- a base Bridge/site subscription;
- app subscriptions per tenant or site;
- metered usage for AI, messages, storage and high-volume operations;
- packaged Solutions combining several apps and a WordPress experience;
- onboarding, configuration, connectors and premium support.

Each pilot must record setup effort, operations used, provider cost, support
load, customer outcome and willingness to pay. Those measurements determine V2
priorities. Avoid bespoke forks: customer variation belongs in tenant config,
contracts, policies and Composer Plugins.

## Approval checklist for a new app

- Clear capability, owner, app ID and semantic version.
- No direct dependency on another business app.
- Versioned contracts and documented failure envelopes.
- Tenant, auth, entitlement, quota and audit behavior defined.
- Storage and secrets boundaries respected.
- WordPress pack and at least one composable customer scenario demonstrated.
- Unit, security and contract tests pass without production dependencies.
- Migration ownership is explicit and rollback is documented.
- Pricing unit and measurable customer outcome are recorded.