# Project Development Guide

This guide describes development practices, code styles, and procedures to follow when working on the **Khandan (خاندان)** application.

## 1. Code Style and Conventions

### PHP Guidelines
- Write clean, standard PHP 8.x code.
- Avoid external packages or composer dependencies. Utilize PHP's rich built-in functions.
- Format PHP files with standard readability, indentation (4 spaces), and meaningful naming conventions (e.g., camelCase for functions, snake_case for database columns).
- Always include `declare(strict_types=1);` at the top of crucial logic files.
- Put security and helper functions inside `src/includes/functions.php`.

### Database Querying
- Always use Prepared Statements for SQLite operations using PDO:
  ```php
  $stmt = $pdo->prepare("SELECT * FROM users WHERE id = :id");
  $stmt->execute(['id' => $userId]);
  $user = $stmt->fetch();
  ```
- Do not concatenate user inputs directly into query strings (prevention of SQL injection).

### Front-End Guidelines (HTML/CSS/JS)
- **HTML:** Write semantic HTML5 structure. Every interactive element must have a unique `id` or descriptive `class` for clean selection.
- **CSS:** Do not use utility frameworks (like Tailwind). Write organized CSS stylesheets in `public/css/style.css`.
  - Use CSS variables for layout spacing, fonts, and colors to simplify theme updates.
  - Implement smooth transitions (`transition: all 0.3s ease`) on interactive actions.
- **JavaScript:** Write clean, modular ES6+ Javascript. Use clear event handlers and separate layout manipulation from backend API calls.
  - Use API endpoints (like `src/index.php?api=xyz`) returning JSON strings for dynamic frontend fetching.

---

## 2. Security Best Practices

### Output Encoding (XSS Prevention)
- Never echo raw variables in HTML blocks. Use the escape helper function:
  ```php
  // Defined in src/includes/functions.php
  function e($value) {
      return htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8');
  }
  
  // Usage in views:
  <h2><?= e($user['full_name']) ?></h2>
  ```

### Cross-Site Request Forgery (CSRF)
- Forms modifying data must embed a CSRF token:
  ```html
  <input type="hidden" name="csrf_token" value="<?= $_SESSION['csrf_token'] ?>">
  ```
- The backend must validate the token before processing any POST requests:
  ```php
  if ($_POST['csrf_token'] !== $_SESSION['csrf_token']) {
      die("CSRF validation failed.");
  }
  ```

### Upload Sanitization
- When uploading photos, audio, or video:
  - Generate a secure, randomized filename (e.g., UUID or `bin2hex(random_bytes(16))`) combined with the file's extension.
  - Do not keep the user's original filename to prevent directory traversal attacks.
  - Validate MIME types server-side (only allow specific image, audio, or video types).

---

## 3. Database Updates and Seeders
- Keep schema adjustments registered inside `src/database/schema.sql`.
- Add test users, default relationships, mock funds, and posts inside a seeding script (e.g., `src/database/seed.php`) to easily reset and recreate the SQLite test database locally.

---

## 4. Deployment via Custom FTP Skill
The project utilizes a Python-based deployment tool to sync files directly to the staging/production server.
- Running deployment:
  ```powershell
  python .agents/skills/ftp-deploy/scripts/deploy.py
  ```
- Command parameters:
  - `--dry-run`: Scans for modified files and lists them without uploading.
  - `--force`: Uploads all workspace files, ignoring previous hashes.