231 lines
3.6 KiB
Markdown
231 lines
3.6 KiB
Markdown
# 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:
|
||
|
||
1. Connects to a Plesk instance
|
||
2. Retrieves subscriptions and domains
|
||
3. Updates records in Supabase
|
||
4. 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/<feature-name>
|
||
|
||
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.
|