Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
71 KiB
71 KiB
CoaxysPanel Backend Product Contract
Purpose
- CoaxysPanel is a hosting control panel product with a production-oriented frontend already in place.
- The backend should become the trusted control plane behind the existing frontend.
- The backend should provide account, server, website, domain, file, database, email, security, automation, backup, notification, audit, support, and settings services.
- The backend should treat the current frontend mock service layer as the public frontend contract surface.
- The backend should preserve the product feel of a dense hosting administration interface.
- The backend should support the CoaxysPanel brand without using third-party control-panel trademarks or copied assets.
- The backend should be designed for real hosting operations, not only visual demos.
- The backend should keep destructive infrastructure operations guarded by explicit policy.
- The backend should keep the frontend responsive while long-running operations continue asynchronously.
- The backend should provide typed, stable, versionable responses for all frontend modules.
- The backend should make real infrastructure state visible without exposing unsafe command execution to the browser.
- The backend should separate user-facing workflows from privileged host-level execution.
- The backend should support mock, staging, and production environments through the same conceptual contracts.
- The backend should make it possible to replace mock data one service at a time.
- The backend should not require the frontend to know implementation details of servers, packages, daemons, or storage engines.
- The frontend should continue to depend on service interfaces rather than importing raw backend payloads directly.
- The frontend should receive normalized data that matches the current DTO vocabulary.
- The frontend should show loading, success, error, empty, permission, maintenance, and partial-failure states from backend signals.
- The backend should provide enough metadata for the frontend to explain status clearly.
- The backend should treat every panel action as an auditable business event.
Product Scope
- The backend should own authentication and session lifecycle.
- The backend should own account selection and current server context.
- The backend should own permission evaluation for all modules.
- The backend should own hosting-account data.
- The backend should own website and application records.
- The backend should own domain records and DNS-zone state.
- The backend should own file-manager metadata and file-operation jobs.
- The backend should own database inventory and database-user relationships.
- The backend should own mailbox inventory and email-routing state.
- The backend should own metrics ingestion and metric summaries.
- The backend should own security findings and security policy state.
- The backend should own software-runtime availability.
- The backend should own advanced tools that inspect or coordinate server state.
- The backend should own server-administration models.
- The backend should own users, teams, resellers, roles, and package models.
- The backend should own backup schedules, backup artifacts, and restore jobs.
- The backend should own automation definitions and automation execution history.
- The backend should own notification delivery preferences and notification events.
- The backend should own audit-event persistence.
- The backend should own support-ticket and diagnostic-report state.
- The backend should own global and per-account settings.
- The backend should provide read models optimized for the frontend shell.
- The backend should provide write models optimized for validated panel operations.
- The backend should define ownership boundaries for every module.
- The backend should preserve module independence where practical.
- The backend should support future module additions without rewriting the app shell.
- The backend should expose consistent navigation and capability metadata.
- The backend should identify unavailable modules explicitly.
- The backend should avoid hidden failures behind generic success messages.
- The backend should make backend maintenance state visible to the frontend.
Core Principles
- The backend should be contract-first.
- The backend should be permission-aware by default.
- The backend should be tenant-aware by default.
- The backend should be audit-aware by default.
- The backend should be failure-aware by default.
- The backend should be localization-ready.
- The backend should be observability-ready.
- The backend should be horizontally scalable where panel traffic requires it.
- The backend should support background jobs for slow operations.
- The backend should support eventual consistency where infrastructure state cannot be instant.
- The backend should not block ordinary UI reads on slow server probes.
- The backend should not expose raw secrets to the browser after creation.
- The backend should not expose host credentials to frontend clients.
- The backend should not treat frontend validation as sufficient.
- The backend should not trust client-provided role or permission claims.
- The backend should not assume a single server forever.
- The backend should not assume a single account forever.
- The backend should not assume all customers have the same feature set.
- The backend should not require every operation to be synchronous.
- The backend should not create fake success for infrastructure actions.
- The backend should provide explicit job states for deferred work.
- The backend should provide explicit conflict states for contested resources.
- The backend should provide explicit validation fields for form errors.
- The backend should provide explicit maintenance states for unavailable modules.
- The backend should provide explicit permission states for denied modules.
- The backend should provide stable identifiers across refreshes.
- The backend should provide human-readable names alongside stable identifiers.
- The backend should preserve immutable audit data.
- The backend should keep destructive actions reversible when the domain allows it.
- The backend should document irreversible actions in response metadata.
API Envelope
- Every backend response should use a standard envelope.
- Successful responses should contain
data. - Successful responses should contain
meta. - Successful responses should contain
error: null. - Failed responses should contain
data: null. - Failed responses should contain
meta. - Failed responses should contain a structured
error. - The error object should contain a stable code.
- The error object should contain a human-readable message.
- The error object should contain field-level errors when validation fails.
- The meta object should include a request identifier.
- The meta object should include pagination metadata for list responses.
- The meta object should include sort metadata when sorting is applied.
- The meta object should include filter metadata when filters are applied.
- The meta object should include permission metadata when useful.
- The meta object should include partial-failure metadata when applicable.
- The meta object should include freshness metadata for cached infrastructure state.
- The meta object should include maintenance metadata for degraded services.
- The meta object should include job metadata when an operation starts background work.
- The meta object should include rate-limit metadata where customer-facing limits exist.
API Consistency
- List endpoints should share pagination semantics.
- List endpoints should share search semantics.
- List endpoints should share filter semantics.
- List endpoints should share sort semantics.
- List endpoints should provide total counts when feasible.
- List endpoints should provide cursor metadata when offset pagination is unsuitable.
- Detail endpoints should include all fields needed by the current page.
- Detail endpoints should avoid requiring many dependent calls for first render.
- Mutation endpoints should return the updated resource or a job reference.
- Bulk endpoints should return per-item status.
- Bulk endpoints should report partial failures explicitly.
- Create endpoints should return the canonical new resource identifier.
- Update endpoints should report conflict versions when optimistic concurrency fails.
- Delete endpoints should distinguish soft delete, trash, archive, and permanent delete.
- Restore endpoints should describe restored scope.
- Import endpoints should describe parsed resources, warnings, and rejected records.
- Export endpoints should return export metadata and delivery status.
- Validation endpoints should return field-level errors without performing the operation.
- Preview endpoints should return impact summaries without performing the operation.
- Capability endpoints should describe what the authenticated user can see and do.
Frontend Wiring Contract
- The frontend should keep using
src/api/servicesas the service boundary. - The frontend should switch from mock services to HTTP-backed services behind the same method names.
- The frontend should preserve TanStack Query query keys as stable cache concepts.
- The frontend should invalidate query groups after successful mutations.
- The frontend should use backend request identifiers in error displays where helpful.
- The frontend should map backend field errors into React Hook Form fields.
- The frontend should keep route definitions independent from HTTP transport details.
- The frontend should receive permission data before showing protected module actions.
- The frontend should treat backend permission denials as valid product states.
- The frontend should treat backend maintenance states as valid product states.
- The frontend should show backend job progress for long-running operations.
- The frontend should show backend conflict warnings before overwriting data.
- The frontend should show backend validation messages without inventing alternate meanings.
- The frontend should not infer infrastructure success from a started job.
- The frontend should not assume mock-only latency in production.
- The frontend should not assume all tables fit in memory.
- The frontend should not assume all file trees are small.
- The frontend should not assume all log streams are finite.
- The frontend should not assume all charts have complete data.
- The frontend should not assume all routes are available for every role.
Authentication
- The backend should provide login.
- The backend should provide logout.
- The backend should provide session refresh.
- The backend should provide session expiration signals.
- The backend should provide forgot-password flow state.
- The backend should provide reset-password flow state.
- The backend should provide two-factor challenge state.
- The backend should provide recovery-code challenge state.
- The backend should provide passkey authentication state.
- The backend should provide device-verification state.
- The backend should provide account-locked state.
- The backend should provide invitation-acceptance state.
- The backend should provide first-run setup state.
- The backend should provide current-user identity.
- The backend should provide current-account identity.
- The backend should provide current-server identity.
- The backend should provide available account selectors.
- The backend should provide available server selectors.
- The backend should provide user preferences after authentication.
- The backend should provide active session metadata.
Authentication Safety
- Password validation should be enforced by the backend.
- Two-factor policy should be enforced by the backend.
- Passkey policy should be enforced by the backend.
- Recovery-code policy should be enforced by the backend.
- Device verification should be enforced by the backend.
- Account lockout should be enforced by the backend.
- Session timeout should be enforced by the backend.
- Session revocation should be enforced by the backend.
- Invitation expiration should be enforced by the backend.
- First-run setup completion should be enforced by the backend.
- Login attempts should be audited.
- Failed login attempts should be audited.
- Password resets should be audited.
- Two-factor changes should be audited.
- Passkey changes should be audited.
- Trusted-device changes should be audited.
- Session termination should be audited.
- Account lock events should be audited.
- Recovery-code usage should be audited.
- Invitation acceptance should be audited.
Permissions
- The backend should own the canonical permission model.
- The backend should support module permissions.
- The backend should support action permissions.
- The backend should support account-scoped permissions.
- The backend should support server-scoped permissions.
- The backend should support reseller-scoped permissions.
- The backend should support support-operator permissions.
- The backend should support read-only auditor permissions.
- The backend should support custom roles.
- The backend should support permission inheritance.
- The backend should support permission overrides.
- The backend should support permission previews.
- The backend should support permission-denied response states.
- The backend should support permission metadata in navigation responses.
- The backend should support feature-list restrictions.
- The backend should support package restrictions.
- The backend should support suspension restrictions.
- The backend should support maintenance restrictions.
- The backend should support emergency-lockdown restrictions.
- The backend should make permissions auditable.
Dashboard
- The backend should provide dashboard account information.
- The backend should provide dashboard server information.
- The backend should provide dashboard resource usage.
- The backend should provide dashboard service status.
- The backend should provide dashboard quick-action availability.
- The backend should provide dashboard widget preferences.
- The backend should provide dashboard widget order.
- The backend should provide dashboard hidden-widget state.
- The backend should provide dashboard refresh timestamps.
- The backend should provide dashboard stale-data indicators.
- The backend should provide dashboard partial-failure indicators.
- The backend should provide dashboard empty states for new accounts.
- The backend should provide dashboard warnings for quota pressure.
- The backend should provide dashboard warnings for service degradation.
- The backend should provide dashboard warnings for expiring certificates.
- The backend should provide dashboard warnings for failed backups.
- The backend should provide dashboard warnings for security findings.
- The backend should provide dashboard links to relevant modules.
- The backend should provide dashboard metrics at suitable granularity.
- The backend should keep dashboard reads fast.
Tools Registry
- The backend should expose available tools for the authenticated user.
- The backend should expose tool categories.
- The backend should expose tool labels.
- The backend should expose tool descriptions.
- The backend should expose tool keywords.
- The backend should expose tool badges.
- The backend should expose tool warnings.
- The backend should expose tool permission status.
- The backend should expose tool availability status.
- The backend should expose tool maintenance status.
- The backend should expose tool favorite state.
- The backend should expose recently used tools.
- The backend should accept favorite ordering.
- The backend should accept recently used updates.
- The backend should support tool search.
- The backend should support category filtering.
- The backend should support tools hidden by packages.
- The backend should support tools hidden by reseller policy.
- The backend should support tools disabled by server capability.
- The backend should make tool metadata stable enough for frontend caching.
Websites
- The backend should provide website lists.
- The backend should provide website details.
- The backend should provide website creation state.
- The backend should provide website runtime choices.
- The backend should provide domain assignment choices.
- The backend should provide SSL assignment choices.
- The backend should provide backup assignment choices.
- The backend should provide database assignment choices.
- The backend should provide repository assignment choices.
- The backend should provide upload assignment choices.
- The backend should validate website names.
- The backend should validate document roots.
- The backend should validate runtime settings.
- The backend should validate environment variables.
- The backend should validate resource limits.
- The backend should validate deployment settings.
- The backend should validate maintenance-mode settings.
- The backend should validate redirect settings.
- The backend should validate health-check settings.
- The backend should return website creation as a job when provisioning is required.
Website Operations
- Website creation should be auditable.
- Website deletion should be auditable.
- Website cloning should be auditable.
- Website staging creation should be auditable.
- Website deployment should be auditable.
- Website rollback should be auditable.
- Website domain assignment should be auditable.
- Website SSL assignment should be auditable.
- Website backup assignment should be auditable.
- Website runtime changes should be auditable.
- Website environment changes should be auditable.
- Website resource-limit changes should be auditable.
- Website process changes should be auditable.
- Website maintenance-mode changes should be auditable.
- Website redirect changes should be auditable.
- Website health-check changes should be auditable.
- Website log access should be permission-gated.
- Website deployment logs should be streamable.
- Website access logs should be filterable.
- Website error logs should be filterable.
Domains
- The backend should provide domain lists.
- The backend should provide domain details.
- The backend should provide subdomain records.
- The backend should provide alias records.
- The backend should provide parked-domain records.
- The backend should provide redirect records.
- The backend should provide domain transfer status.
- The backend should provide domain verification status.
- The backend should provide DNSSEC status.
- The backend should provide nameserver settings.
- The backend should provide domain health state.
- The backend should provide propagation status.
- The backend should provide certificate status.
- The backend should validate domain syntax.
- The backend should validate ownership checks.
- The backend should validate redirect targets.
- The backend should validate nameserver changes.
- The backend should validate alias conflicts.
- The backend should validate subdomain conflicts.
- The backend should report DNS and certificate dependencies clearly.
DNS
- The backend should provide DNS-zone records.
- The backend should support A records.
- The backend should support AAAA records.
- The backend should support CNAME records.
- The backend should support MX records.
- The backend should support TXT records.
- The backend should support SRV records.
- The backend should support CAA records.
- The backend should support NS records.
- The backend should support PTR records where applicable.
- The backend should validate record names.
- The backend should validate record values.
- The backend should validate TTL values.
- The backend should validate priority values.
- The backend should validate record conflicts.
- The backend should validate apex restrictions.
- The backend should validate CNAME exclusivity.
- The backend should validate MX dependencies.
- The backend should validate CAA syntax.
- The backend should return propagation-check state.
DNS Operations
- DNS record creation should be auditable.
- DNS record editing should be auditable.
- DNS record duplication should be auditable.
- DNS record deletion should be auditable.
- DNS bulk deletion should be auditable.
- DNS imports should be auditable.
- DNS exports should be auditable.
- Raw-zone edits should be auditable.
- DNSSEC changes should be auditable.
- Nameserver changes should be auditable.
- DNS operations should identify affected zones.
- DNS operations should identify affected records.
- DNS operations should identify conflicts.
- DNS operations should identify warnings.
- DNS operations should identify propagation expectations.
- DNS operations should not require frontend parsing of raw zone files.
- DNS operations should return normalized records.
- DNS operations should preserve comments where the backend supports them.
- DNS operations should protect provider-managed records.
- DNS operations should expose read-only records as read-only.
Files
- The backend should provide directory trees.
- The backend should provide file lists.
- The backend should provide file details.
- The backend should provide file previews.
- The backend should provide image previews.
- The backend should provide text previews.
- The backend should provide source previews.
- The backend should provide upload jobs.
- The backend should provide download authorizations.
- The backend should provide archive jobs.
- The backend should provide extract jobs.
- The backend should provide compress jobs.
- The backend should provide trash state.
- The backend should provide restore state.
- The backend should provide permission metadata.
- The backend should provide ownership metadata.
- The backend should provide checksum metadata.
- The backend should provide storage usage.
- The backend should provide hidden-file visibility policy.
- The backend should provide conflict-resolution options.
File Operations
- File upload should be job-aware.
- Multi-file upload should be job-aware.
- Drag-and-drop upload should be job-aware.
- File rename should be conflict-aware.
- File move should be conflict-aware.
- File copy should be conflict-aware.
- File duplicate should be conflict-aware.
- File delete should be trash-aware.
- File restore should be conflict-aware.
- File creation should validate path and name.
- Directory creation should validate path and name.
- Archive creation should report progress.
- Archive extraction should report progress.
- Compression should report progress.
- Permission changes should be auditable.
- Ownership display should be accurate.
- Checksum calculation should be asynchronous for large files.
- Source editing should preserve encoding metadata.
- Source editing should detect concurrent modifications.
- Source editing should report validation warnings where supported.
File Safety
- The backend should prevent path traversal.
- The backend should enforce account root boundaries.
- The backend should hide unauthorized paths.
- The backend should protect system paths.
- The backend should protect panel-owned files.
- The backend should enforce upload size limits.
- The backend should enforce file count limits.
- The backend should enforce extension restrictions where configured.
- The backend should scan uploads where policy requires it.
- The backend should quarantine suspicious files where policy requires it.
- The backend should avoid exposing server absolute paths beyond allowed account context.
- The backend should avoid exposing raw host usernames unless policy permits it.
- The backend should represent symlinks safely.
- The backend should make destructive file operations reversible when possible.
- The backend should require confirmation metadata for permanent deletes.
- The backend should keep operation transcripts for audits.
- The backend should support Web Disk state.
- The backend should support FTP account state.
- The backend should support FTP session state.
- The backend should support Git repository state.
Databases
- The backend should provide MySQL database state.
- The backend should provide MariaDB database state.
- The backend should provide PostgreSQL database state.
- The backend should provide database user state.
- The backend should provide database permission state.
- The backend should provide database creation workflow state.
- The backend should provide remote access state.
- The backend should provide backup state.
- The backend should provide restore state.
- The backend should provide size analytics.
- The backend should provide active connection state.
- The backend should provide slow query summaries.
- The backend should provide process-list state.
- The backend should provide admin-tool launch readiness.
- The backend should validate database names.
- The backend should validate database usernames.
- The backend should validate passwords.
- The backend should validate privileges.
- The backend should validate remote hosts.
- The backend should validate backup policies.
Database Operations
- Database creation should be auditable.
- Database deletion should be auditable.
- Database rename should be auditable where supported.
- Database user creation should be auditable.
- Database user deletion should be auditable.
- Database password changes should be auditable.
- Database privilege changes should be auditable.
- Remote access changes should be auditable.
- Database backup creation should be auditable.
- Database restore should be auditable.
- Admin-tool launch should be auditable.
- Connection tests should return explicit results.
- Connection tests should not expose passwords.
- Process-list actions should be permission-gated.
- Slow query access should be permission-gated.
- Database analytics should be cacheable.
- Database storage values should be normalized.
- Database engines should be represented explicitly.
- Database versions should be represented explicitly.
- Database limits should be represented explicitly.
- The backend should provide email account state.
- The backend should provide mailbox creation state.
- The backend should provide quota state.
- The backend should provide password-management state.
- The backend should provide forwarder state.
- The backend should provide domain-forwarder state.
- The backend should provide routing state.
- The backend should provide autoresponder state.
- The backend should provide default-address state.
- The backend should provide mailing-list state.
- The backend should provide delivery-tracking state.
- The backend should provide email-filter state.
- The backend should provide global-filter state.
- The backend should provide spam-filtering state.
- The backend should provide DKIM state.
- The backend should provide SPF state.
- The backend should provide DMARC state.
- The backend should provide encryption state.
- The backend should provide calendar state.
- The backend should provide contact state.
Email Operations
- Mailbox creation should be auditable.
- Mailbox deletion should be auditable.
- Mailbox quota changes should be auditable.
- Mailbox password changes should be auditable.
- Forwarder changes should be auditable.
- Routing changes should be auditable.
- Autoresponder changes should be auditable.
- Default-address changes should be auditable.
- Mailing-list changes should be auditable.
- Delivery tracking should be searchable.
- Email filters should be testable.
- Spam filter changes should be auditable.
- DKIM changes should be auditable.
- SPF changes should be auditable.
- DMARC changes should be auditable.
- Encryption key changes should be auditable.
- Mail queue actions should be auditable.
- Mail log access should be permission-gated.
- Webmail launch should be auditable.
- Client configuration should be generated from canonical server data.
Email Client Configuration
- The backend should provide IMAP settings.
- The backend should provide SMTP settings.
- The backend should provide POP3 settings.
- The backend should provide TLS information.
- The backend should provide mobile configuration data.
- The backend should provide desktop configuration data.
- The backend should provide server hostnames.
- The backend should provide ports.
- The backend should provide encryption requirements.
- The backend should provide authentication methods.
- The backend should provide username formats.
- The backend should provide mailbox storage data.
- The backend should provide last-login data.
- The backend should provide forwarding state.
- The backend should provide spam score summaries.
- The backend should provide authentication status.
- The backend should provide active sessions.
- The backend should provide device setup hints as data.
- The backend should avoid exposing passwords.
- The backend should keep generated settings account-specific.
Metrics
- The backend should provide visitor metrics.
- The backend should provide access-log summaries.
- The backend should provide error-log summaries.
- The backend should provide bandwidth metrics.
- The backend should provide raw-access metadata.
- The backend should provide AWStats-style metrics.
- The backend should provide Webalizer-style metrics.
- The backend should provide resource-usage metrics.
- The backend should provide CPU history.
- The backend should provide memory history.
- The backend should provide disk history.
- The backend should provide network-traffic history.
- The backend should provide HTTP-status distributions.
- The backend should provide top URLs.
- The backend should provide top referrers.
- The backend should provide top countries.
- The backend should provide top user agents.
- The backend should provide top IP addresses.
- The backend should provide database performance metrics.
- The backend should provide email-delivery metrics.
Metrics Behavior
- Metrics responses should support date ranges.
- Metrics responses should support comparison ranges.
- Metrics responses should support export metadata.
- Metrics responses should support live-update indicators.
- Metrics responses should support empty states.
- Metrics responses should support delayed-ingestion states.
- Metrics responses should support partial data warnings.
- Metrics responses should support timezone-aware labels.
- Metrics responses should support account scoping.
- Metrics responses should support domain scoping.
- Metrics responses should support website scoping.
- Metrics responses should support server scoping.
- Metrics responses should normalize units.
- Metrics responses should identify sampled data.
- Metrics responses should identify estimated data.
- Metrics responses should avoid leaking other tenants.
- Metrics exports should be auditable.
- Metrics retention should be policy-driven.
- Metrics aggregation should be product-consistent.
- Metrics freshness should be visible.
Security
- The backend should provide SSL/TLS status.
- The backend should provide certificate management state.
- The backend should provide Let's Encrypt state.
- The backend should provide custom certificate upload state.
- The backend should provide CSR state.
- The backend should provide private-key metadata.
- The backend should provide automatic HTTPS state.
- The backend should provide HTTPS redirect state.
- The backend should provide HSTS state.
- The backend should provide SSH access state.
- The backend should provide SSH key state.
- The backend should provide IP blocker state.
- The backend should provide firewall state.
- The backend should provide port-rule state.
- The backend should provide brute-force protection state.
- The backend should provide WAF rule state.
- The backend should provide malware scanning state.
- The backend should provide antivirus scanning state.
- The backend should provide file-integrity state.
- The backend should provide security-advisor state.
Security Operations
- Certificate issuance should be job-aware.
- Certificate renewal should be job-aware.
- Certificate upload should validate chains.
- CSR generation should be auditable.
- Private-key import should be guarded.
- HTTPS redirect changes should be auditable.
- HSTS changes should be auditable.
- SSH key changes should be auditable.
- IP blocker changes should be auditable.
- Firewall changes should be auditable.
- Port-rule changes should be auditable.
- Brute-force policy changes should be auditable.
- WAF rule changes should be auditable.
- Malware scans should be job-aware.
- Antivirus scans should be job-aware.
- Integrity scans should be job-aware.
- Security findings should have severity.
- Security findings should have target metadata.
- Security findings should have recommended actions.
- Security findings should have remediation status.
Defensive Boundary
- The backend should treat security modules as defensive administration interfaces.
- The backend should not expose offensive attack tooling.
- The backend should not execute arbitrary user-provided attack payloads.
- The backend should not provide exploit automation.
- The backend should not provide credential harvesting features.
- The backend should not expose private keys after creation unless explicit policy allows it.
- The backend should not reveal sensitive scan internals to unauthorized users.
- The backend should not allow firewall lockout without recovery policy.
- The backend should not allow security-policy bypass from the frontend.
- The backend should not silently downgrade security settings.
- The backend should provide safe previews for risky changes.
- The backend should provide typed confirmation requirements.
- The backend should provide reason-field requirements.
- The backend should provide second-factor requirements for critical actions.
- The backend should provide impact descriptions for critical actions.
- The backend should provide audit previews for critical actions.
- The backend should provide rollback metadata where possible.
- The backend should provide emergency-contact or recovery metadata where appropriate.
- The backend should preserve evidence for security events.
- The backend should make security state explainable.
Software And Runtimes
- The backend should provide PHP version state.
- The backend should provide PHP extension state.
- The backend should provide PHP configuration state.
- The backend should provide per-domain PHP version state.
- The backend should provide PHP-FPM settings state.
- The backend should provide Node.js application state.
- The backend should provide Node.js version state.
- The backend should provide Python application state.
- The backend should provide Python version state.
- The backend should provide Ruby application state.
- The backend should provide Docker application state.
- The backend should provide Composer state.
- The backend should provide npm script state.
- The backend should provide package-manager status.
- The backend should provide application-installer state.
- The backend should provide runtime environment variables.
- The backend should provide process-manager state.
- The backend should provide website optimization state.
- The backend should provide compression state.
- The backend should provide cache state.
Runtime Framework
- Runtime definitions should be data-driven.
- Runtime versions should be explicit.
- Runtime extensions should be explicit.
- Runtime process managers should be explicit.
- Runtime environment-variable rules should be explicit.
- Runtime resource limits should be explicit.
- Runtime compatibility warnings should be explicit.
- Runtime update availability should be explicit.
- Runtime deprecation state should be explicit.
- Runtime default settings should be explicit.
- Runtime package operations should be job-aware.
- Runtime process operations should be job-aware.
- Runtime configuration changes should be auditable.
- Runtime package changes should be auditable.
- Runtime version changes should be auditable.
- Runtime environment changes should be auditable.
- Runtime restart requirements should be visible.
- Runtime rollback availability should be visible.
- Runtime future additions should not require frontend redesign.
- Runtime labels should remain product-friendly.
Advanced Tools
- The backend should provide cron-job state.
- The backend should provide task-scheduler state.
- The backend should provide DNS lookup state.
- The backend should provide traceroute state.
- The backend should provide index-manager state.
- The backend should provide error-page state.
- The backend should provide MIME type state.
- The backend should provide Apache handler state.
- The backend should provide Nginx snippet state.
- The backend should provide reverse-proxy rule state.
- The backend should provide process-manager state.
- The backend should provide service-manager state.
- The backend should provide terminal session state.
- The backend should provide log-viewer state.
- The backend should provide queue-manager state.
- The backend should provide webhook state.
- The backend should provide API explorer metadata.
- The backend should provide API documentation metadata.
- The backend should provide environment-inspector state.
- The backend should provide system-information state.
Terminal
- The terminal backend should be mockable.
- The terminal backend should be permission-gated.
- The terminal backend should be session-scoped.
- The terminal backend should be server-scoped.
- The terminal backend should provide connection state.
- The terminal backend should provide tab state.
- The terminal backend should provide transcript state.
- The terminal backend should provide resize state.
- The terminal backend should provide copy-paste policy.
- The terminal backend should provide search metadata.
- The terminal backend should provide reconnect state.
- The terminal backend should provide fullscreen state metadata.
- The terminal backend should provide clear-session actions.
- The terminal backend should provide transcript download metadata.
- The terminal backend should not expose unrestricted command execution to normal users.
- The terminal backend should not bypass account isolation.
- The terminal backend should not bypass audit logging.
- The terminal backend should not bypass role restrictions.
- The terminal backend should distinguish mock sessions from real sessions.
- The terminal backend should be optional per server.
Server Administration
- The backend should provide server overview state.
- The backend should provide server status.
- The backend should provide services state.
- The backend should provide process state.
- The backend should provide network-interface state.
- The backend should provide mounted-filesystem state.
- The backend should provide storage-device state.
- The backend should provide system-update state.
- The backend should provide kernel information.
- The backend should provide reboot state.
- The backend should provide shutdown state.
- The backend should provide hostname state.
- The backend should provide timezone state.
- The backend should provide DNS resolver state.
- The backend should provide nameserver state.
- The backend should provide firewall state.
- The backend should provide package-update state.
- The backend should provide service-log state.
- The backend should provide health-check state.
- The backend should provide server-registration state.
Dangerous Server Actions
- Reboot actions should require confirmation.
- Shutdown actions should require confirmation.
- Package update actions should require confirmation.
- Kernel update actions should require confirmation.
- Firewall lockout-risk actions should require confirmation.
- Service restart actions should require confirmation where impact exists.
- Migration actions should require confirmation.
- Destructive storage actions should require confirmation.
- Hostname changes should require impact summaries.
- Timezone changes should require impact summaries.
- DNS resolver changes should require impact summaries.
- Nameserver changes should require impact summaries.
- Reboot actions should request a reason field.
- Shutdown actions should request a reason field.
- Migration actions should request a reason field.
- Destructive storage actions should request a reason field.
- Critical actions should support mock two-factor confirmation in frontend mode.
- Critical actions should enforce real second-factor confirmation in production mode.
- Critical actions should create audit-preview metadata.
- Critical actions should create final audit entries.
Users And Teams
- The backend should provide hosting-user state.
- The backend should provide team-member state.
- The backend should provide role state.
- The backend should provide permission state.
- The backend should provide reseller-account state.
- The backend should provide hosting-package state.
- The backend should provide account-quota state.
- The backend should provide feature-list state.
- The backend should provide impersonation state.
- The backend should provide invitation state.
- The backend should provide suspended-account state.
- The backend should provide account-termination state.
- The backend should provide account-migration state.
- The backend should provide ownership-transfer state.
- The backend should provide access-log state.
- The backend should provide session-management state.
- The backend should validate user email addresses.
- The backend should validate role assignments.
- The backend should validate package assignments.
- The backend should validate quota assignments.
Roles
- The backend should support super administrator role.
- The backend should support server administrator role.
- The backend should support reseller role.
- The backend should support hosting account owner role.
- The backend should support developer role.
- The backend should support billing viewer role.
- The backend should support support operator role.
- The backend should support read-only auditor role.
- The backend should support custom role.
- The backend should provide detailed permission matrices.
- The backend should provide module-level permissions.
- The backend should provide action-level permissions.
- The backend should provide resource-level permissions where needed.
- The backend should provide permission templates.
- The backend should provide permission diffs.
- The backend should provide permission-impact previews.
- The backend should audit role creation.
- The backend should audit role updates.
- The backend should audit role deletion.
- The backend should audit impersonation events.
Backups
- The backend should provide backup dashboard state.
- The backend should provide full-account backup state.
- The backend should provide website backup state.
- The backend should provide database backup state.
- The backend should provide email backup state.
- The backend should provide configuration backup state.
- The backend should provide incremental backup state.
- The backend should provide snapshot backup state.
- The backend should provide scheduled backup state.
- The backend should provide retention-policy state.
- The backend should provide backup-destination state.
- The backend should provide restore-wizard state.
- The backend should provide backup-browser state.
- The backend should provide backup-verification state.
- The backend should provide encryption status.
- The backend should provide storage usage.
- The backend should provide failed-job history.
- The backend should provide download authorization.
- The backend should provide delete state.
- The backend should provide clone-from-backup state.
Backup Destinations
- Local storage should be represented as a destination.
- SFTP should be represented as a destination.
- S3-compatible storage should be represented as a destination.
- Backblaze B2 should be represented as a destination.
- Google Cloud Storage should be represented as a destination.
- Azure Blob Storage should be represented as a destination.
- Custom object storage should be represented as a destination.
- Destination credentials should not be revealed after creation.
- Destination tests should return explicit connection status.
- Destination tests should return explicit permission status.
- Destination capacity should be visible where available.
- Destination encryption should be visible.
- Destination retention should be visible.
- Destination failure state should be visible.
- Destination last-success metadata should be visible.
- Destination last-failure metadata should be visible.
- Destination changes should be auditable.
- Destination deletion should be guarded.
- Destination reuse should be supported.
- Destination policy should be account-scoped.
Restore
- Restore operations should be wizard-driven.
- Restore operations should include scope selection.
- Restore operations should include conflict policy.
- Restore operations should include impact preview.
- Restore operations should include reason capture.
- Restore operations should include second-factor confirmation.
- Restore operations should include audit-preview metadata.
- Restore operations should include job progress.
- Restore operations should include rollback availability where possible.
- Restore operations should include post-restore validation.
- Restore operations should report partial success.
- Restore operations should report skipped resources.
- Restore operations should report overwritten resources.
- Restore operations should report created resources.
- Restore operations should report failed resources.
- Restore operations should report warnings.
- Restore operations should be auditable.
- Restore downloads should be permission-gated.
- Restore destructive choices should be explicit.
- Restore state should remain visible after page refresh.
Automation
- The backend should provide scheduled-task state.
- The backend should provide deployment-pipeline state.
- The backend should provide webhook state.
- The backend should provide event-trigger state.
- The backend should provide automation-template state.
- The backend should provide retry-policy state.
- The backend should provide execution-history state.
- The backend should provide failed-execution state.
- The backend should provide environment-based workflow state.
- The backend should provide backup automation state.
- The backend should provide certificate automation state.
- The backend should provide update automation state.
- The backend should provide monitoring automation state.
- The backend should provide notification automation state.
- The backend should validate triggers.
- The backend should validate conditions.
- The backend should validate actions.
- The backend should validate branches.
- The backend should validate execution previews.
- The backend should validate test-mode constraints.
Notifications
- The backend should provide notification-center state.
- The backend should provide read/unread state.
- The backend should provide categories.
- The backend should provide notification preferences.
- The backend should provide email notification settings.
- The backend should provide webhook notification settings.
- The backend should provide browser notification settings.
- The backend should provide critical alerts.
- The backend should provide security alerts.
- The backend should provide backup alerts.
- The backend should provide resource alerts.
- The backend should provide SSL alerts.
- The backend should provide deployment alerts.
- The backend should provide notification delivery status.
- The backend should provide notification retry status.
- The backend should provide notification suppression state.
- The backend should provide quiet-hour state.
- The backend should provide digest state.
- The backend should audit preference changes.
- The backend should preserve critical-alert history.
Support
- The backend should provide documentation metadata.
- The backend should provide knowledge-base metadata.
- The backend should provide system-diagnostics state.
- The backend should provide support-ticket lists.
- The backend should provide ticket details.
- The backend should provide ticket replies.
- The backend should provide file attachment metadata.
- The backend should provide ticket status.
- The backend should provide ticket priority.
- The backend should provide diagnostic-report generation state.
- The backend should validate ticket subjects.
- The backend should validate ticket messages.
- The backend should validate attachments.
- The backend should validate ticket ownership.
- The backend should audit ticket creation.
- The backend should audit ticket replies.
- The backend should audit ticket status changes.
- The backend should audit diagnostic report generation.
- The backend should protect sensitive diagnostic data.
- The backend should expose shareable diagnostic summaries.
Settings
- The backend should provide general settings.
- The backend should provide branding settings.
- The backend should provide logo metadata.
- The backend should provide theme settings.
- The backend should provide accent-color settings.
- The backend should provide locale settings.
- The backend should provide date-format settings.
- The backend should provide time-format settings.
- The backend should provide timezone settings.
- The backend should provide session-timeout settings.
- The backend should provide security defaults.
- The backend should provide password policy.
- The backend should provide two-factor policy.
- The backend should provide email settings.
- The backend should provide notification settings.
- The backend should provide backup defaults.
- The backend should provide DNS defaults.
- The backend should provide SSL defaults.
- The backend should provide runtime defaults.
- The backend should provide file-manager settings.
More Settings
- The backend should provide API settings.
- The backend should provide feature flags.
- The backend should provide experimental feature state.
- The backend should provide privacy settings.
- The backend should provide data-retention settings.
- The backend should provide maintenance-mode settings.
- Settings changes should be auditable.
- Branding changes should be auditable.
- Theme changes should be user-scoped or account-scoped as policy requires.
- Locale changes should be user-scoped or account-scoped as policy requires.
- Security-default changes should be guarded.
- Password-policy changes should be guarded.
- Two-factor-policy changes should be guarded.
- API-setting changes should be guarded.
- Feature-flag changes should be guarded.
- Maintenance-mode changes should be guarded.
- Settings should support live preview where the frontend already previews state.
- Settings should distinguish draft values from saved values.
- Settings should expose inherited values.
- Settings should expose overridden values.
Audit Logs
- The backend should create audit entries for authentication events.
- The backend should create audit entries for permission events.
- The backend should create audit entries for website events.
- The backend should create audit entries for domain events.
- The backend should create audit entries for DNS events.
- The backend should create audit entries for file events.
- The backend should create audit entries for database events.
- The backend should create audit entries for email events.
- The backend should create audit entries for metric export events.
- The backend should create audit entries for security events.
- The backend should create audit entries for software events.
- The backend should create audit entries for advanced-tool events.
- The backend should create audit entries for server events.
- The backend should create audit entries for user events.
- The backend should create audit entries for reseller events.
- The backend should create audit entries for backup events.
- The backend should create audit entries for restore events.
- The backend should create audit entries for automation events.
- The backend should create audit entries for notification events.
- The backend should create audit entries for settings events.
Audit Metadata
- Audit entries should include actor identity.
- Audit entries should include actor role context.
- Audit entries should include account context.
- Audit entries should include server context.
- Audit entries should include reseller context where applicable.
- Audit entries should include target type.
- Audit entries should include target identifier.
- Audit entries should include target label.
- Audit entries should include action.
- Audit entries should include outcome.
- Audit entries should include request identifier.
- Audit entries should include IP address.
- Audit entries should include user agent where available.
- Audit entries should include timestamp.
- Audit entries should include reason field where required.
- Audit entries should include confirmation metadata where required.
- Audit entries should include before-and-after metadata where safe.
- Audit entries should avoid storing secrets.
- Audit entries should be immutable.
- Audit entries should be exportable by authorized users.
Jobs
- The backend should represent long-running operations as jobs.
- Jobs should have stable identifiers.
- Jobs should have type.
- Jobs should have status.
- Jobs should have progress.
- Jobs should have started timestamp.
- Jobs should have updated timestamp.
- Jobs should have completed timestamp when complete.
- Jobs should have actor metadata.
- Jobs should have target metadata.
- Jobs should have cancellability metadata.
- Jobs should have retry metadata.
- Jobs should have warnings.
- Jobs should have errors.
- Jobs should have result summaries.
- Jobs should have audit references.
- Jobs should support polling.
- Jobs should support event updates where available.
- Jobs should remain visible after navigation.
- Jobs should expire according to retention policy.
Real-Time Events
- The backend should provide event streams for job progress.
- The backend should provide event streams for notifications.
- The backend should provide event streams for terminal sessions.
- The backend should provide event streams for log viewers.
- The backend should provide event streams for deployment logs.
- The backend should provide event streams for backup progress.
- The backend should provide event streams for restore progress.
- The backend should provide event streams for automation executions.
- Event messages should include type.
- Event messages should include timestamp.
- Event messages should include account context.
- Event messages should include server context where relevant.
- Event messages should include payload.
- Event messages should include request or job references where relevant.
- Event messages should preserve authorization boundaries.
- Event messages should support reconnect behavior.
- Event messages should support last-seen cursors where applicable.
- Event messages should not expose data from other tenants.
- Event messages should be versionable.
- Event messages should remain compatible with frontend state updates.
Errors
- The backend should provide validation errors.
- The backend should provide permission errors.
- The backend should provide authentication errors.
- The backend should provide conflict errors.
- The backend should provide not-found errors.
- The backend should provide rate-limit errors.
- The backend should provide maintenance errors.
- The backend should provide dependency errors.
- The backend should provide partial-failure errors.
- The backend should provide network-facing timeout errors.
- Error codes should be stable.
- Error messages should be readable.
- Error fields should map to form fields.
- Error metadata should include request identifiers.
- Error metadata should include retryability where relevant.
- Error metadata should include support references where relevant.
- Error metadata should avoid leaking secrets.
- Error metadata should avoid leaking host internals.
- Error states should be testable by the frontend.
- Error states should be documented as product behavior.
Data Model Expectations
- Resource identifiers should be stable.
- Resource labels should be human-readable.
- Resource status values should be enumerated.
- Resource timestamps should be normalized.
- Resource ownership should be explicit.
- Resource server placement should be explicit.
- Resource account placement should be explicit.
- Resource feature availability should be explicit.
- Resource permission availability should be explicit.
- Resource maintenance availability should be explicit.
- Resource soft-delete state should be explicit.
- Resource archival state should be explicit.
- Resource health state should be explicit.
- Resource warning state should be explicit.
- Resource dependency state should be explicit.
- Resource quota impact should be explicit.
- Resource audit metadata should be explicit.
- Resource version metadata should be explicit where edits can conflict.
- Resource display metadata should be frontend-friendly.
- Resource transport metadata should remain separate from business data.
Frontend State
- The frontend should keep global UI state in Zustand only for UI concerns.
- The frontend should keep server data in TanStack Query.
- The frontend should keep form state in React Hook Form.
- The frontend should keep validation schemas aligned with backend validation concepts.
- The frontend should keep route definitions centralized.
- The frontend should keep permission definitions centralized.
- The frontend should keep table definitions close to feature views.
- The frontend should keep mock services replaceable.
- The frontend should keep loading skeletons for backend latency.
- The frontend should keep empty states for backend empty responses.
Frontend Data Handling
- The frontend should cache list reads by module and filter state.
- The frontend should cache detail reads by stable resource identifier.
- The frontend should invalidate related reads after mutations.
- The frontend should preserve optimistic UI only where backend confirmation semantics allow it.
- The frontend should avoid optimistic UI for irreversible operations.
- The frontend should show job progress for asynchronous operations.
- The frontend should show stale data indicators from backend metadata.
- The frontend should show partial-failure messages from backend metadata.
- The frontend should show maintenance banners from backend metadata.
- The frontend should show permission-denied states from backend responses.
- The frontend should use request IDs in support-friendly errors.
- The frontend should use backend-provided display labels.
- The frontend should use backend-provided status values.
- The frontend should use backend-provided quota values.
- The frontend should use backend-provided unit metadata.
- The frontend should use backend-provided route availability.
- The frontend should not parse logs when backend can provide structured summaries.
- The frontend should not calculate security scores from raw findings.
- The frontend should not calculate billing-grade usage from approximate metrics.
- The frontend should not invent backend capability state.
Internationalization
- Backend-provided labels should be localizable where they are product copy.
- Backend-provided enum display names should be localizable.
- Backend-provided validation messages should support localization.
- Backend-provided timestamps should be timezone-neutral.
- Backend-provided durations should be unit-neutral.
- Backend-provided numeric values should be raw numbers plus unit context.
- Backend-provided currency values should include currency codes where billing appears.
- Backend-provided country names should use stable codes plus display labels.
- Backend-provided language choices should use stable locale identifiers.
- Backend-provided date formatting should not be preformatted unless explicitly needed.
Performance
- Backend dashboard reads should be fast.
- Backend navigation reads should be fast.
- Backend permission reads should be fast.
- Backend table reads should support pagination.
- Backend file-list reads should support virtualized frontend consumption.
- Backend log reads should support streaming or cursor windows.
- Backend metric reads should support aggregation.
- Backend search reads should support bounded result sets.
- Backend expensive reads should expose freshness metadata.
- Backend expensive reads should support cached summaries.
- Backend write operations should not block on nonessential refresh work.
- Backend long-running writes should return jobs.
- Backend heavy exports should return jobs.
- Backend imports should return parsed previews or jobs.
- Backend file operations should return progress for large work.
- Backend backup operations should return progress.
- Backend restore operations should return progress.
- Backend metrics should avoid over-fetching by default.
- Backend tables should avoid returning unused giant payloads.
- Backend responses should remain predictable under load.
Observability
- The backend should emit structured logs.
- The backend should emit request metrics.
- The backend should emit job metrics.
- The backend should emit module health metrics.
- The backend should emit dependency health metrics.
- The backend should emit authentication metrics.
- The backend should emit authorization-denial metrics.
- The backend should emit validation-failure metrics.
- The backend should emit audit-write metrics.
- The backend should emit notification-delivery metrics.
- The backend should emit backup-success metrics.
- The backend should emit backup-failure metrics.
- The backend should emit restore-success metrics.
- The backend should emit restore-failure metrics.
- The backend should emit certificate-renewal metrics.
- The backend should emit security-scan metrics.
- The backend should emit database-operation metrics.
- The backend should emit file-operation metrics.
- The backend should emit email-delivery metrics.
- The backend should correlate logs with request IDs.
Compliance And Privacy
- The backend should minimize sensitive data sent to the frontend.
- The backend should minimize secrets stored in audit logs.
- The backend should minimize personal data in exports.
- The backend should support data retention policies.
- The backend should support privacy settings.
- The backend should support account data export where product policy requires it.
- The backend should support account data deletion where product policy requires it.
- The backend should distinguish operational logs from audit logs.
- The backend should distinguish customer data from platform data.
- The backend should support consent-sensitive notification channels where required.
- The backend should keep diagnostic reports scoped.
- The backend should redact credentials from diagnostic reports.
- The backend should redact tokens from diagnostic reports.
- The backend should redact private keys from diagnostic reports.
- The backend should redact connection strings from diagnostic reports.
- The backend should redact environment secrets from diagnostic reports.
- The backend should provide safe support summaries.
- The backend should provide retention metadata to the settings UI.
- The backend should make privacy-impacting changes auditable.
- The backend should keep compliance behavior explicit.
Migration From Mock Services
- Mock services should remain useful for local frontend development.
- HTTP services should preserve the same conceptual methods.
- DTO names should remain aligned with existing contracts.
- Response envelopes should remain aligned with existing contracts.
- Error envelopes should remain aligned with existing contracts.
- Pagination contracts should remain aligned with existing contracts.
- Filtering contracts should remain aligned with existing contracts.
- Sorting contracts should remain aligned with existing contracts.
- Search contracts should remain aligned with existing contracts.
- Bulk-operation contracts should remain aligned with existing contracts.
- Job-progress contracts should remain aligned with existing contracts.
- Audit-metadata contracts should remain aligned with existing contracts.
- Permission-check contracts should remain aligned with existing contracts.
- WebSocket-event contracts should remain aligned with existing contracts.
- Mock latency should remain configurable.
- Mock errors should remain configurable.
- Mock maintenance states should remain configurable.
- Mock permission states should remain configurable.
- Mock empty states should remain configurable.
- Mock data should remain realistic enough for UI regression tests.
Release Readiness
- The backend should be considered ready only when auth flows are wired.
- The backend should be considered ready only when permission checks are authoritative.
- The backend should be considered ready only when dashboard reads are real.
- The backend should be considered ready only when primary module lists are real.
- The backend should be considered ready only when destructive actions are guarded.
- The backend should be considered ready only when audit logging is durable.
- The backend should be considered ready only when job progress is reliable.
- The backend should be considered ready only when frontend errors are explainable.
- The backend should be considered ready only when observability is in place.
- The backend should be considered ready only when backup and restore semantics are clear.
- The backend should be considered ready only when security module boundaries are enforced.
- The backend should be considered ready only when tenant boundaries are enforced.
- The backend should be considered ready only when performance targets are met.
- The backend should be considered ready only when e2e frontend flows pass against it.
- The backend should be considered ready only when support diagnostics are safe.
- The backend should be considered ready only when settings persistence is reliable.
- The backend should be considered ready only when notification delivery is observable.
- The backend should be considered ready only when restore operations are auditable.
- The backend should be considered ready only when migration from mock mode is reversible.
- The backend should be considered ready only when product behavior is documented.
Non-Goals For The Frontend Contract
- The frontend should not become a host command runner.
- The frontend should not own backend authorization decisions.
- The frontend should not own backend quota enforcement.
- The frontend should not own backend security scoring.
- The frontend should not own backend backup integrity checks.
- The frontend should not own backend restore correctness.
- The frontend should not own DNS conflict detection.
- The frontend should not own certificate validation.
- The frontend should not own database privilege truth.
- The frontend should not own email-routing truth.
- The frontend should not own package availability truth.
- The frontend should not own server health truth.
- The frontend should not own audit durability.
- The frontend should not own tenant isolation.
- The frontend should not own secret storage.
- The frontend should not own long-running job execution.
- The frontend should not own terminal execution policy.
- The frontend should not own infrastructure rollback policy.
- The frontend should not own compliance retention.
- The frontend should not own platform incident state.
Final Product Expectations
- CoaxysPanel should feel like one integrated hosting control center.
- The backend should make every visible tool meaningful.
- The backend should make every primary action traceable.
- The backend should make every dangerous action deliberate.
- The backend should make every permission boundary enforceable.
- The backend should make every long-running operation observable.
- The backend should make every validation failure actionable.
- The backend should make every support escalation easier to diagnose.
- The backend should make the frontend replace mock data without redesign.
- The backend should make future modules fit the same service pattern.
- The backend should make account, server, and reseller context explicit everywhere.
- The backend should make failures honest rather than decorative.
- The backend should make infrastructure state understandable to administrators.
- The backend should make security state understandable without exposing offensive capability.
- The backend should make backup and restore trust visible.
- The backend should make automation predictable.
- The backend should make notifications useful instead of noisy.
- The backend should make audit logs complete enough for accountability.
- The backend should make settings changes safe to preview and safe to save.
- The backend and frontend together should preserve the premium CoaxysPanel experience.