# Zabibu Residence — Installation Guide

## Requirements
- PHP 8.1+ (recommended 8.3)
- MySQL 8.0+ or MariaDB 10.6+
- Apache/Nginx with mod_rewrite enabled
- Composer (optional, no external packages required)
- PHP Extensions: PDO, PDO_MySQL, mbstring, gd, fileinfo, openssl

---

## 1. Setup Steps

### Clone / Extract
Extract the project to your web server root:
```
/var/www/html/zabibu-residence/
```
Or for XAMPP/WAMP:
```
C:/xampp/htdocs/zabibu-residence/
```

### 2. Configure the Database

1. Open **phpMyAdmin** or your MySQL client.
2. Create a new database:
```sql
CREATE DATABASE zabibu_residence CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
3. Import the schema:
```
database/zabibu_residence.sql
```

### 3. Configure the Application

Open `config/config.php` and update:
```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'zabibu_residence');
define('DB_USER', 'root');
define('DB_PASS', 'your_password');
define('APP_URL', 'http://localhost/zabibu-residence/public');
```

### 4. Configure Apache (Virtual Host or .htaccess)

The `.htaccess` file is in `public/`. Your DocumentRoot should point to the `public/` folder.

**Apache VirtualHost:**
```apache
<VirtualHost *:80>
    ServerName zabibu.local
    DocumentRoot /var/www/html/zabibu-residence/public
    <Directory /var/www/html/zabibu-residence/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

**For XAMPP (no VirtualHost):** Access via:
```
http://localhost/zabibu-residence/public/
```

### 5. Set File Permissions
```bash
chmod -R 755 public/uploads/
chmod -R 755 public/assets/
```

Create upload directories:
```bash
mkdir -p public/uploads/{properties,avatars,documents,logos}
```

### 6. Configure Nginx (Alternative)
```nginx
server {
    listen 80;
    server_name zabibu.local;
    root /var/www/html/zabibu-residence/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

---

## Default Login Credentials

| Role | Email | Password |
|------|-------|----------|
| Super Admin | admin@zabiburesidence.co.tz | admin123 |
| Property Owner | owner@zabiburesidence.co.tz | owner123 |
| Property Manager | manager@zabiburesidence.co.tz | manager123 |
| Accountant | accountant@zabiburesidence.co.tz | account123 |
| Receptionist | receptionist@zabiburesidence.co.tz | recept123 |
| Tenant | tenant@zabiburesidence.co.tz | tenant123 |

> **⚠️ Change all passwords immediately after first login!**

---

## Directory Structure
```
zabibu-residence/
├── app/
│   ├── Controllers/        # MVC Controllers
│   │   └── Api/            # REST API Controllers
│   ├── Helpers/            # Utility helpers
│   ├── Models/             # Data models
│   └── Views/              # HTML views & layouts
├── config/
│   └── config.php          # Main configuration
├── core/
│   ├── Controller.php      # Base controller
│   ├── Database.php        # PDO singleton
│   ├── Model.php           # Base model
│   └── Router.php          # URL router
├── database/
│   └── zabibu_residence.sql  # Full schema + seed data
├── public/
│   ├── assets/             # CSS, JS, images
│   ├── uploads/            # User uploads (writable)
│   ├── .htaccess           # URL rewriting
│   └── index.php           # Front controller
└── routes/
    ├── api.php             # API routes
    └── web.php             # Web routes
```

---

## Payment Gateway Configuration

In `config/config.php`, configure Tanzania payment gateways:
```php
define('MPESA_PAYBILL',    '123456');
define('MPESA_API_KEY',    'your_key');
define('AIRTEL_MERCHANT',  '0767000000');
define('TIGOPESA_NUMBER',  '0717000000');
```

---

## Tanzania M-Pesa Integration Notes
- Register on **Safaricom Developer Portal** for API credentials
- Use the `PaymentController::mpesaCallback()` route for STK push callbacks
- The system supports: M-Pesa, Airtel Money, Tigo Pesa, Halotel, Bank Transfer, Cash

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| 404 on all pages | Enable mod_rewrite, check .htaccess |
| DB connection error | Verify `config.php` credentials |
| File upload fails | Check `public/uploads/` permissions (755) |
| Blank white page | Set `APP_DEBUG = true` in config.php |
| Session errors | Ensure PHP session.save_path is writable |

---

## Support
Contact: support@zabiburesidence.co.tz | +255 700 000 000