Architecture & Engineering Principles (High-Level)¶

These are principles, not implementation details.

Microservices Orientation¶

Services are independently deployable and scalable.
Teams can iterate independently while honoring contracts.

API-First¶

Every UI action is backed by an API.
No hidden UI-only behavior.

Security-First¶

Secure defaults and least privilege.
Secrets are never logged and are encrypted at rest/in transit.
Threat and abuse cases are part of design reviews.

Tenant Isolation by Infrastructure¶

Customer workloads run in per-tenant service sets.
Isolation should not rely only on application code checks.
Tenant data-plane credentials and resource access are scoped per tenant.
Cross-tenant product data access is out of scope for v0.

Workspace as Product Boundary¶

Workspace is the default user-facing scope.
Cross-workspace operations are explicit, role-gated, and auditable.

RBAC¶

Minimum roles for v0: - Admin - Connector Builder - Viewer/Auditor - Tenant Admin (administrative workflows such as workspace owner transfer)

Auditability¶

Every significant action is auditable, including: - Connection lifecycle (create/edit/delete) - Test connection attempts (success/fail + reason) - Discovery runs (start/complete/partial/fail) - Exports and administrative scope changes

Control Plane Separation¶

Global control plane manages tenant registry, licensing, routing metadata, and fleet operations.
Tenant data planes handle customer business workloads.
Control plane must not become a path for cross-tenant business data queries.

Discovery Execution Boundary¶

Discovery service coordinates runs; workers execute long-running tasks.
Workers fetch scoped configuration securely and process one run at a time.

Connector Boundary = Extensibility Boundary¶

Connector contract is the interface between provider-specific systems and canonical model behavior.
Contract changes require explicit ADR-driven updates.