# 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.