# AI_DEVELOPMENT_GUIDE.md

## Extending the Application

### 1. Adding a New Property Field
1. Open `prisma/schema.prisma`.
2. Add the new column to the `Property` model, e.g.
   ```prisma
   model Property {
     // ... existing fields
     newField String?   // optional field
   }
   ```
3. Run the migration:
   ```bash
   npx prisma migrate dev --name add-new-field
   ```
4. Regenerate the client:
   ```bash
   npx prisma generate
   ```
5. The new field will be available via `prisma.property` in your TypeScript code.

### 2. Adding a New Contract Merge Tag
1. Locate the contract template (e.g., `templates/lease.html`).
2. Insert the placeholder using double curly braces, e.g. `{{new_tag}}`.
3. In `src/lib/contractBuilder.ts` (or wherever you generate PDFs), add the data mapping:
   ```ts
   const data = {
     // existing mappings
     new_tag: contractData.newTagValue,
   };
   ```
4. Ensure the value is populated when creating the contract record.

### 3. Prompting a Free AI (Gemini / DeepSeek)
```ts
import { GenerativeModel, GoogleGenerativeAI } from "@google/genai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

export async function generateDescription(tags: string): Promise<string> {
  const prompt = `Write a compelling real‑estate description in English and Arabic using these tags: ${tags}`;
  const result = await model.generateContent(prompt);
  const text = await result.response.text();
  return text;
}
```
Replace `process.env.GEMINI_API_KEY` with the API key stored in the `settings` table (managed via the Super‑Admin panel).

### 4. Debugging with AI
- Copy the faulty function into a prompt:
  ```
  /**
   * Explain why this function throws an error and propose a fix.
   */
  ```
- Paste the code and ask the AI to suggest a corrected version.
- Review the AI output, apply changes, and run your tests.

## File Structure Overview
```
project-root/
├─ prisma/
│  ├─ schema.prisma          # DB schema
│  ├─ config.ts             # Prisma client instance
│  └─ migrations/           # SQL migration files
├─ src/
│  ├─ pages/                # Next.js pages & API routes
│  ├─ components/           # React components
│  └─ styles/theme.css      # Tailwind CSS with CSS variables
├─ public/                    # Static assets (QR codes, images)
├─ .env                      # Environment variables
└─ ...
```

Use this guide to quickly modify or extend any part of the system without deep diving into the entire codebase.