# Developer Guide - KK Jewel Admin (EJCAT Admin)

This guide provides technical instructions, coding standards, database workflows, and deployment procedures for developers contributing to the **KK Jewel Admin** application.

---

## Technical Overview & Stack Architecture

The application follows standard Symfony MVC (Model-View-Controller) architecture principles:

- **Controllers (`src/Controller/`)**: Handle HTTP requests, delegate business logic, query Doctrine repositories, and render Twig views or return JSON responses.
- **Entities (`src/Entity/`)**: Object-relational mapping (ORM) classes representing database tables.
- **Forms (`src/Form/`)**: Form types defining validation rules, fields, and options.
- **Commands (`src/Command/`)**: CLI commands executable via `php bin/console <command-name>`.
- **Event Subscribers (`src/EventSubscriber/`)**: Listen to framework lifecycle events (e.g., authorization, backup redirects).
- **Views (`templates/`)**: Twig templates organized by feature domain.

---

## Code Standards & Conventions

### PHP Guidelines
- Adhere to **PSR-12** coding standards.
- Class names must use `PascalCase` (e.g. `DesignsController`, `ProdTaggingType`).
- Method names and property names must use `camelCase` (e.g. `getDesignDetails()`, `$createdAt`).
- All controllers should specify explicit return types and route annotations where applicable.

### Controller Structure Example

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ExampleController extends AbstractController
{
    /**
     * @Route("/example", name="app_example")
     */
    public function index(): Response
    {
        return $this->render('example/index.html.twig', [
            'controller_name' => 'ExampleController',
        ]);
    }
}
```

---

## Working with Database & Doctrine ORM

### Creating or Updating Entities

To create or modify an entity, use Symfony Maker Bundle:

```bash
# Interactive entity creation/update
php bin/console make:entity

# Generate database migration
php bin/console make:migration

# Apply pending migrations
php bin/console doctrine:migrations:migrate
```

### Doctrine Annotations

Entities map to MySQL tables using Doctrine annotations:

```php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity(repositoryClass="App\Repository\CategoryRepository")
 * @ORM\Table(name="category")
 */
class Category
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=255)
     */
    private $name;

    // Getters and Setters ...
}
```

---

## Console Commands & Automated Tasks

Custom CLI commands are located under `src/Command/`.

### Automated Backup Command (`app:all-backup`)
The command `src/Command/AllBackupCommand.php` executes full database dumps and asset backups.

To execute manually:
```bash
php bin/console app:all-backup --force
```

---

## Static Assets & File Uploads Management

### Dynamic Asset Directories
The application dynamically handles uploaded media files and CSV imports. These directories are ignored by Git to preserve server privacy and prevent repository bloating:

- `/public/uploads/` - General file attachments
- `/public/bulk/` - Uploaded CSV batch files
- `/public/bulk-image/` - Uploaded bulk image zip/folder extractions
- `/public/designs/` - Design catalogue image assets
- `/public/emp_docs_photos/` - Employee photo & document attachments
- `/public/operation_images/` - Operation status photos

### Setting Directory Permissions on Production
Ensure the web server user (`www-data` or cPanel user) has write permissions on runtime and upload folders:

```bash
chmod -R 775 var/
chmod -R 775 public/uploads/ public/bulk/ public/designs/
```

---

## Git Workflow & Branching Strategy

### Configuration Rules
Always maintain the configured Git identity for project contributions:

```bash
git config user.name "mayavanmyn"
git config user.email "mayavan.maruthamuthu@ksit.tech"
```

### Main Branch
- Primary branch: `master`
- All stable production code resides in `master`.

### Pre-Commit Checklist
Before committing changes, ensure:
1. No `.env` or sensitive configuration files are staged:
   ```bash
   git check-ignore -v .env
   ```
2. Vendor folders (`vendor/`, `node_modules/`) and runtime cache (`var/`) are ignored.
3. Code changes do not contain hardcoded DB credentials or `var_dump()` / `die()` / `exit` debug calls.

---

## Deployment & Production Checklist

1. **Pull Code**:
   ```bash
   git pull origin master
   ```
2. **Install Production Dependencies**:
   ```bash
   composer install --no-dev --optimize-autoloader
   ```
3. **Clear & Warmup Cache**:
   ```bash
   php bin/console cache:clear --env=prod
   php bin/console cache:warmup --env=prod
   ```
4. **Dump Environment File (Optional for performance)**:
   ```bash
   composer dump-env prod
   ```
5. **Run Migrations**:
   ```bash
   php bin/console doctrine:migrations:migrate --no-interaction
   ```