4.0 KiB
System Architecture
This document describes the architecture of the Plesk Agency Portal SaaS platform.
The platform allows agencies to connect multiple Plesk servers and manage hosting subscriptions from a single dashboard.
High Level Components
The system consists of the following components:
Frontend Dashboard
Backend API
Supabase Database
Plesk Servers
Future Worker Services
Future Billing Integration
At a high level, users interact with the Frontend Dashboard, which sends authenticated requests to the Backend API (Next.js API routes). The backend reads and writes persistent state in Supabase, and executes remote operations against connected Plesk servers via API/CLI integrations. Future worker services will run asynchronous sync and retry workflows, while future billing integration will enforce plan limits and subscription state.
Frontend
The frontend is a Next.js application using the App Router.
Responsibilities include:
User authentication
Dashboard interface
Displaying domains and subscriptions
Triggering sync operations
Sending management actions (suspend / unsuspend)
The frontend communicates with backend API routes.
Backend
The backend uses Next.js API routes.
Responsibilities include:
Handling authenticated requests
Connecting to Supabase
Executing Plesk API and CLI commands
Processing sync operations
Writing operational logs
Business logic should be implemented in reusable modules inside the lib directory.
Database
Supabase Postgres is used for persistent storage.
Key tables include:
agencies
agency_members
plesk_instances
plesk_subscriptions
plesk_domains
actions_log
billing_accounts
Relationship overview:
agenciesis the tenant root.agency_membersassociates users to agencies and roles.plesk_instancesstores connected remote Plesk endpoints per agency.plesk_subscriptionsstores subscription-level records linked to instances.plesk_domainsstores domain-level records linked to subscriptions/instances.actions_logstores operational/audit events.billing_accountsstores plan/subscription billing state per agency.
The multi-tenant model is enforced using Supabase Row Level Security policies so users can only read/write rows that belong to their agency.
Plesk Integration
The platform communicates with remote Plesk servers.
Integration methods:
Plesk REST API
Plesk CLI commands
Typical operations include:
Listing subscriptions
Retrieving domain data
Suspending subscriptions
Unsuspending subscriptions
CLI parsing must be defensive due to formatting differences between Plesk versions.
Sync System
The system supports synchronization of Plesk servers.
Manual sync is triggered from the dashboard.
During sync:
The backend connects to a Plesk instance
Subscription and domain data are retrieved
Records are updated in Supabase
The dashboard displays updated data
Future development will add automated background sync workers.
Logging System
Operational actions are recorded in the actions_log table.
Examples:
instance_connected
sync_started
sync_completed
subscription_suspended
subscription_unsuspended
Logging supports debugging and auditability.
Future Worker Architecture
Future versions of the system will include background workers for:
Automatic instance synchronization
Retry queues
Monitoring tasks
Workers may run as:
Cron jobs
Queue processors
Dedicated worker services
Billing Architecture (Future)
Stripe will be integrated for SaaS billing.
Billing responsibilities will include:
Agency subscription plans
Usage limits
Payment handling
Billing enforcement will eventually control:
Number of connected Plesk instances
Number of managed domains
Development Philosophy
The system prioritizes:
Stability
Security
Multi-tenant isolation
Safe integrations with external systems
Developers should extend existing systems rather than rewriting them.