# Kashi Housing - Project Rules & Standards

> These rules MUST be followed throughout the entire development lifecycle.

---

## Table of Contents

1. [General Project Rules](#1-general-project-rules)
2. [Architecture & Structure Rules](#2-architecture--structure-rules)
3. [Performance Rules](#3-performance-rules)
4. [Security Rules](#4-security-rules)
5. [Database & Data Handling Rules](#5-database--data-handling-rules)
6. [SEO Rules](#6-seo-rules)
7. [Accessibility Rules](#7-accessibility-rules)
8. [Error Handling & Logging Rules](#8-error-handling--logging-rules)
9. [Testing Rules](#9-testing-rules)
10. [Deployment & Maintenance Rules](#10-deployment--maintenance-rules)
11. [Documentation Rules](#11-documentation-rules)
12. [Image Handling Rules](#12-image-handling-rules)
13. [Final Acceptance Rule](#13-final-acceptance-rule)

---

## 1. General Project Rules

| Rule | Description |
|------|-------------|
| ✅ Scalable | The project must be scalable, secure, and production-ready |
| ✅ Clean Code | Code must follow clean coding standards |
| ✅ Minimal | No unnecessary features, libraries, or plugins |
| ✅ Simple | The solution must be simple, efficient, and maintainable |
| ✅ Real Users | Assume the project will be used by real users at scale |

---

## 2. Architecture & Structure Rules

| Rule | Description |
|------|-------------|
| ✅ Folder Structure | Use proper folder and file structure |
| ✅ Separation | Separate frontend, backend, and database logic |
| ✅ MVC Pattern | Follow MVC or component-based architecture where applicable |
| ✅ No Hardcoding | Avoid hardcoding values; use configuration files or environment variables |
| ✅ Extensible | Ensure the project can be extended without rewriting existing code |

### Laravel Structure Standards

```
app/
├── Http/Controllers/     # Thin controllers, business logic in Services
├── Models/               # Eloquent models with relationships
├── Services/             # Business logic layer
├── Repositories/         # Data access layer (if needed)
└── Helpers/              # Utility functions

config/                   # All configuration files
resources/views/          # Blade templates organized by feature
routes/                   # Separate route files for web, api, admin
```

---

## 3. Performance Rules

| Rule | Description |
|------|-------------|
| ✅ Fast Load | Optimize for fast page load and low server response time |
| ✅ Image Optimization | Images must be optimized and compressed |
| ✅ Lazy Loading | Use lazy loading for images and heavy components |
| ✅ Minify Assets | Minimize CSS, JavaScript, and assets |
| ✅ Non-blocking | Avoid blocking scripts in the page load |
| ✅ Lightweight | Do not use heavy libraries if lightweight alternatives exist |
| ✅ Low-end Support | Ensure the website performs well on low-end devices and slow networks |

### Performance Targets

| Metric | Target |
|--------|--------|
| Page Load Time | < 2 seconds |
| First Contentful Paint | < 1.5 seconds |
| Time to Interactive | < 3 seconds |
| Image Size | < 200KB (compressed) |
| Total Page Size | < 2MB |

---

## 4. Security Rules

| Rule | Description |
|------|-------------|
| ✅ HTTPS | HTTPS (SSL) must be enforced |
| ✅ Input Validation | All user inputs must be validated and sanitized |
| ✅ Attack Protection | Protect against SQL Injection, XSS, CSRF, and file upload vulnerabilities |
| ✅ No Exposure | Sensitive data must never be exposed in frontend code |
| ✅ Auth Security | Use secure authentication and authorization mechanisms |
| ✅ Environment Secrets | Store secrets and credentials in environment variables only |
| ✅ Error Handling | Implement proper error handling without exposing system details |

### Laravel Security Implementation

```php
// Always use:
- CSRF tokens in forms
- Eloquent ORM (prevents SQL injection)
- Request validation classes
- Middleware for authentication
- Gate/Policy for authorization
- bcrypt for password hashing
- Rate limiting on forms
```

---

## 5. Database & Data Handling Rules

| Rule | Description |
|------|-------------|
| ✅ Optimized Queries | Use secure and optimized database queries |
| ✅ No Redundancy | Avoid redundant data storage |
| ✅ Indexing | Implement indexing where required |
| ✅ No N+1 | Prevent N+1 query problems (use eager loading) |
| ✅ Data Integrity | Ensure data integrity and validation at all layers |

### Query Optimization Checklist

```php
// ❌ Bad - N+1 Problem
$properties = Property::all();
foreach ($properties as $property) {
    echo $property->location->city;  // Separate query for each
}

// ✅ Good - Eager Loading
$properties = Property::with(['location', 'images'])->get();
```

---

## 6. SEO Rules

| Rule | Description |
|------|-------------|
| ✅ Semantic HTML | Use semantic HTML structure |
| ✅ Meta Tags | Pages must have proper title, meta description, and headings |
| ✅ Clean URLs | URLs must be clean, readable, and SEO-friendly |
| ✅ Alt Text | Images must include alt text |
| ✅ Crawlable | Website must be crawlable and indexable |

### SEO Implementation

```html
<!-- Every page must have -->
<title>{{ $metaTitle }}</title>
<meta name="description" content="{{ $metaDescription }}">
<meta name="robots" content="index, follow">
<link rel="canonical" href="{{ $canonicalUrl }}">

<!-- Open Graph -->
<meta property="og:title" content="{{ $metaTitle }}">
<meta property="og:description" content="{{ $metaDescription }}">
<meta property="og:image" content="{{ $ogImage }}">

<!-- Schema Markup for properties -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "RealEstateListing",
  ...
}
</script>
```

---

## 7. Accessibility Rules

| Rule | Description |
|------|-------------|
| ✅ Responsive | Website must be usable on mobile, tablet, and desktop |
| ✅ Contrast | Ensure proper color contrast and readable fonts |
| ✅ Keyboard | Navigation must be keyboard accessible |
| ✅ Forms | Forms must have proper labels and error messages |

### Breakpoints

| Device | Breakpoint |
|--------|------------|
| Mobile | < 640px |
| Tablet | 640px - 1024px |
| Desktop | > 1024px |

---

## 8. Error Handling & Logging Rules

| Rule | Description |
|------|-------------|
| ✅ Graceful | Handle errors gracefully without crashing the system |
| ✅ Logging | Log critical errors for debugging |
| ✅ No Stack Traces | Never expose stack traces or system paths to users |
| ✅ User-Friendly | Provide user-friendly error messages |

### Laravel Error Handling

```php
// Custom error pages
resources/views/errors/404.blade.php
resources/views/errors/500.blade.php
resources/views/errors/503.blade.php

// Logging
Log::error('Property not found', ['id' => $id, 'user' => auth()->id()]);
```

---

## 9. Testing Rules

| Rule | Description |
|------|-------------|
| ✅ Cross-Browser | Test on multiple browsers and devices |
| ✅ Form Validation | Validate all forms and user interactions |
| ✅ Load Testing | Check performance under load |
| ✅ No Dead Links | Ensure no broken links or dead pages |
| ✅ Bug-Free | Fix all critical bugs before deployment |

### Browser Testing Matrix

| Browser | Versions |
|---------|----------|
| Chrome | Latest 2 |
| Firefox | Latest 2 |
| Safari | Latest 2 |
| Edge | Latest 2 |
| Mobile Safari | iOS 14+ |
| Chrome Mobile | Latest |

---

## 10. Deployment & Maintenance Rules

| Rule | Description |
|------|-------------|
| ✅ Version Control | Use version control (Git) |
| ✅ Backups | Take backups before every deployment |
| ✅ Deployment Steps | Follow proper deployment steps |
| ✅ Rollback | Ensure rollback is possible |
| ✅ Maintenance | Plan regular maintenance and updates |

### Deployment Checklist

```bash
# Pre-deployment
- [ ] Run tests
- [ ] Backup database
- [ ] Backup files

# Deployment
- [ ] Pull latest code
- [ ] Install dependencies
- [ ] Run migrations
- [ ] Clear caches
- [ ] Optimize

# Post-deployment
- [ ] Verify functionality
- [ ] Check error logs
- [ ] Monitor performance
```

---

## 11. Documentation Rules

| Rule | Description |
|------|-------------|
| ✅ Setup Docs | Document setup, configuration, and deployment steps |
| ✅ Feature Docs | Explain key features and architecture |
| ✅ Developer Guide | Provide clear instructions for future developers |
| ✅ README | Maintain a clean and updated README file |

---

## 12. Image Handling Rules

> ⚠️ **IMPORTANT: All uploaded images must follow this naming convention**

### Image Naming Convention

| Scenario | Naming Pattern | Example |
|----------|----------------|---------|
| With Title | `{slugified-title}-{timestamp}.{ext}` | `residential-plot-babatpur-1705467600.webp` |
| Without Title | `{project-name}-{timestamp}.{ext}` | `kashihousing-1705467600.webp` |
| Multiple Images | `{slugified-title}-{index}-{timestamp}.{ext}` | `3bhk-flat-lanka-1-1705467600.webp` |

### Image Processing Rules

```php
// 1. Rename based on title or fallback to project name
$filename = $title 
    ? Str::slug($title) . '-' . time() . '.' . $extension
    : 'kashihousing-' . time() . '.' . $extension;

// 2. Compress images (max 200KB for web)
// 3. Convert to WebP format when possible
// 4. Generate thumbnails for listings
// 5. Always include alt text from title
```

### Image Sizes

| Usage | Dimensions | Max Size |
|-------|------------|----------|
| Thumbnail | 300x200 | 50KB |
| Listing Card | 600x400 | 100KB |
| Gallery | 1200x800 | 200KB |
| Hero/Banner | 1920x600 | 300KB |

### Storage Structure

```
storage/app/public/
├── properties/
│   ├── thumbnails/
│   ├── gallery/
│   └── original/
├── blog/
├── testimonials/
└── general/
```

---

## 13. Final Acceptance Rule

### ✅ Project Completion Criteria

The project will be considered complete **ONLY IF**:

| Criteria | Requirement |
|----------|-------------|
| 🎯 Performance | Meets performance benchmarks (< 2s load time) |
| 🔒 Security | Follows security best practices |
| 📈 SEO | Is SEO-friendly with proper meta tags & structure |
| 📐 Scalable | Is scalable and maintainable |
| 🚀 Production Ready | Is ready for real-world production use |

### Acceptance Checklist

```
[ ] All pages load under 2 seconds
[ ] No security vulnerabilities detected
[ ] All forms have validation
[ ] Mobile responsive on all devices
[ ] SEO meta tags present on all pages
[ ] Error handling implemented
[ ] Database queries optimized
[ ] Images compressed and properly named
[ ] Documentation complete
[ ] Cross-browser tested
[ ] Production environment configured
```

---

## Quick Reference

### Commands

```bash
# Development
php artisan serve
npm run dev

# Production Build
npm run build
php artisan optimize

# Cache Clear
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

### Environment Variables Required

```env
APP_NAME=KashiHousing
APP_ENV=production
APP_DEBUG=false
APP_URL=https://kashihousing.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=kashihousing
DB_USERNAME=
DB_PASSWORD=

MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=
MAIL_USERNAME=
MAIL_PASSWORD=
```

---

*Document Version: 1.0 | Created: January 17, 2026*  
*These rules are mandatory and must be followed throughout development.*