docs: add ai project context for development agents

docs/ai-project-context.md

@@ -0,0 +1,230 @@
+# 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.