new changes

architecture/2026/01-bounded-contexts.md

@@ -0,0 +1,64 @@
+# YakPanel 2026 Bounded Contexts and Ownership
+
+This document defines ownership boundaries between the Laravel control plane and Go execution services.
+
+## Domain Contexts
+
+### IdentityAndAccess (Laravel)
+- Owns tenants, users, membership, roles, permissions, and scoped policy evaluation.
+- Exposes authn/authz services to all modules.
+- Guarantees tenant isolation at query and policy layers.
+
+### TenantBillingAndLifecycle (Laravel)
+- Owns tenant lifecycle, plan limits, billing integration hooks, and quota enforcement.
+- Emits events used by job orchestration and plugin entitlements.
+
+### InventoryAndServerRegistry (Laravel + agent-gateway)
+- Laravel owns canonical server records, labels, region mapping, and assignment.
+- `agent-gateway` owns live session presence and online/offline detection.
+
+### HostingResourceManagement (Laravel)
+- Owns site, domain, SSL metadata, FTP metadata, database metadata, and lifecycle workflows.
+- Delegates mutable node operations to Go engines through command orchestration.
+
+### WorkloadOrchestration (Laravel + Go engines)
+- Laravel owns workflow composition, step state machine, retry policy, audit trail.
+- Go services own command execution logic for privileged operations.
+
+### PluginMarketplace (Laravel + Go engine-fileops/engine-docker)
+- Laravel owns catalog, signatures, compatibility metadata, entitlements.
+- Go services own installation actions on managed nodes.
+
+### ObservabilityAndAlerting (Laravel + metrics pipeline)
+- Laravel owns dashboards, alert rules, routing, and incident metadata.
+- Metrics ingestion pipeline owns aggregation and retention.
+
+### IntegrationAPI (Laravel)
+- Owns third-party API tokens, webhooks, and scoped public endpoints.
+
+## Service Ownership Matrix
+
+| Capability | Laravel Module | Go Service | Notes |
+|---|---|---|---|
+| Tenant and RBAC | Auth, Tenant, Rbac | N/A | Policy checks happen before dispatch. |
+| Server enrollment metadata | Server | agent-gateway | Enrollment token issued by Laravel, redeemed via gateway. |
+| Website lifecycle | Site, Domain, Ssl | engine-site | Laravel stores desired state; engine enforces actual state. |
+| Docker app deployment | Apps | engine-docker | Templates validated in Laravel, executed by engine-docker. |
+| MySQL/Redis management | Database, Redis | engine-db | Credentials references stored in Laravel. |
+| File operations | Files | engine-fileops | Strict allowlists and safe path constraints. |
+| Firewall/security | Firewall | engine-security | Security engine returns audit evidence artifacts. |
+| Backup and restore | Backups | engine-backup | Backup plans defined in Laravel. |
+| Agent session routing | Agents | agent-gateway | mTLS and command channel handling in gateway. |
+| Monitoring and alerts | Metrics, Alerts | metrics-ingest | Live streams + retained aggregates. |
+
+## Cross-Context Contracts
+
+- Commands are immutable envelopes with `idempotency_key`.
+- All control-plane writes emit domain events.
+- Engines are stateless workers and read policy-free command payloads.
+- Agents execute only capability-approved command types.
+
+## Non-Goals
+
+- No direct shell command execution from Laravel workers.
+- No shared mutable state between engine services outside contract stores/queues.