3.6 KiB
Project: Plesk Agency Portal
This project is a multi-tenant SaaS platform that allows agencies to manage multiple Plesk servers from a single dashboard.
The application synchronizes subscriptions and domains from Plesk instances and allows administrators to manage hosting accounts.
Technology Stack
Frontend
- Next.js (App Router)
- React
- TypeScript
Backend
- Next.js API routes
- Node runtime
Database
- Supabase Postgres
Authentication
- Supabase Auth (magic link)
External Integrations
- Plesk REST API
- Plesk CLI
- Stripe (future billing integration)
Development Tools
- Git
- Docker (for some services)
- Jenkins (future CI/CD)
Core Database Tables
agencies
agency_members
plesk_instances
plesk_subscriptions
plesk_domains
actions_log
billing_accounts
Multi-Tenant Model
Each user belongs to an agency.
Agency relationships:
user
→ agency_members
→ agencies
→ plesk_instances
→ plesk_subscriptions
→ plesk_domains
Row Level Security in Supabase ensures users can only access rows belonging to their agency.
Never bypass or remove RLS policies.
Plesk Integration
The system integrates with Plesk using both:
Plesk REST API
Plesk CLI
Common CLI commands used:
subscription --info
subscription --suspend
subscription --unsuspend
CLI output must always be parsed defensively because formatting can vary between Plesk versions.
Sync System
The platform supports manual synchronization of Plesk instances.
During sync the system:
- Connects to a Plesk instance
- Retrieves subscriptions and domains
- Updates records in Supabase
- Updates the dashboard
Future development will include background sync workers.
Dashboard Features
Current features include:
Connecting Plesk instances
Testing connections
Manual sync
Listing domains and subscriptions
Suspending subscriptions
Unsuspending subscriptions
Logging
Operational actions are written to:
actions_log
Examples include:
instance_connected
sync_started
sync_completed
subscription_suspended
subscription_unsuspended
Logging should never block primary workflows.
Development Rules
When implementing features:
Search the repository before modifying code.
Extend existing architecture rather than rewriting systems.
Avoid introducing breaking database schema changes.
Prefer small modular functions.
Keep API routes thin.
Place integration logic inside lib folders.
Git Workflow
Default branch:
master
All work must be done on feature branches.
Example:
git checkout master
git pull
git checkout -b feature/
Never commit directly to master.
Error Handling
External integrations must always fail gracefully.
If a single subscription fails during sync, the rest of the sync must continue.
All failures should be logged.
UI Safety
Dashboard components must:
Handle null values safely
Avoid crashing if API responses change
Use status badges instead of raw text for statuses
Future Roadmap
Upcoming development milestones include:
CL4 – Subscription status ingestion via CLI
CL5 – Action logging and retry queue
CL6 – Automatic sync worker
CL7 – Stripe billing enforcement
CL8 – Instance health monitoring
CL9 – Observability and audit improvements
AI Agent Instructions
Before modifying code:
Search the repository for related implementations.
Avoid rewriting working systems.
Implement minimal safe modifications.
Always verify that existing features continue working.
If unsure about a change, prefer logging rather than failing.