yakpanel-core/architecture/2026/01-bounded-contexts.md

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.