# PROJECT_RULES.md

## Purpose
This file defines strict rules for AI agents working on the Eversatile Core project.

Always follow these rules. Do not override them unless explicitly instructed.

---

## 1. Core Principle
Build a **multi-tenant SaaS control panel (Eversatile Core)** that manages:
- tenants
- apps
- packages
- subscriptions
- billing (invoices, payments)
- users
- roles and permissions
- dashboards
- app access

This is NOT a product like Salon OS.
This is the platform that manages all products.

---

## 2. Scope Discipline (CRITICAL)

When given a task:
- Work on **ONLY the requested module**
- Do NOT modify unrelated files
- Do NOT rewrite architecture
- Do NOT rename core entities

If a change in another file is required:
- Explicitly state it first
- Keep it minimal

---

## 3. Stack Rules

Must use:
- Laravel 12
- MySQL
- Blade
- Tailwind CSS

Must NOT require:
- Docker
- Redis (optional only)
- Supervisor
- complex server setup

System must run on **cPanel hosting (Truehost)**.

---

## 4. Architecture Rules

- Monolith Laravel app (modular internally)
- No microservices for now
- No external dependencies that break shared hosting

Future apps must plug into this system without redesign.

---

## 5. Multi-Tenancy Rules

- Every user belongs to a tenant (except Super Admin)
- All tenant data must be isolated
- Always scope queries by `tenant_id` where required
- Never leak data across tenants

---

## 6. Database Rules

- Use ULID or ID consistently
- Use foreign keys and indexes
- Use soft deletes where useful
- Use clear status fields (enum or string)

Critical entities:
- tenants
- apps
- app_packages
- subscriptions
- invoices
- payments
- users
- roles
- permissions

---

## 7. Code Standards

Always:
- Use Form Requests for validation
- Use Policies or middleware for authorization
- Use service classes for complex logic
- Use DB transactions for critical flows

Never:
- Put business logic inside controllers
- Skip validation
- Hardcode values that should be configurable

---

## 8. Subscription Logic Rules

A subscription must:
- belong to tenant + app + package
- track:
  - start_date
  - end_date
  - trial_start
  - trial_end
  - status
  - amount

Statuses must include:
- trial
- active
- pending
- expired
- cancelled

---

## 9. Billing Rules

System must support:
- invoices
- invoice items
- payments
- transactions

Must track:
- amount
- currency
- reference
- receipt number
- status

Do NOT mix:
- invoice logic
- payment gateway logic

---

## 10. M-Pesa Rules

- Keep M-Pesa logic isolated in a service
- Always store raw callback payload
- Handle duplicate callbacks safely
- Use idempotent processing

---

## 11. UI Rules

- Use Blade + Tailwind
- Simple admin dashboards
- Tables for listings
- Forms for CRUD
- Avoid heavy frontend frameworks

---

## 12. File Change Rules

When generating code:
- Show file paths
- Show full code for affected files
- Do NOT show unchanged files

---

## 13. Prompt Execution Rules

For every task:
- Assume previous modules already exist
- Do NOT restate the entire system
- Do NOT generate unnecessary explanation
- Focus on implementation

---

## 14. Performance Rules

- Add indexes where needed
- Avoid N+1 queries
- Use eager loading where appropriate

---

## 15. Security Rules

- Validate all inputs
- Protect routes with auth and roles
- Never expose sensitive config
- Use CSRF protection

---

## 16. Deployment Rules

- Must work on cPanel
- Use Laravel scheduler via cron
- Use database queue if needed
- Keep setup simple

---

## 17. Naming Rules

Use consistent naming:
- Tenant
- App
- AppPackage
- Subscription
- Invoice
- Payment

Do NOT invent new naming conventions mid-project.

---

## 18. Final Rule

If unsure:
- choose simplicity
- choose maintainability
- choose cPanel compatibility