xamxam/docs/MIGRATION_GUIDE.md

# Repository Restructure Migration Guide

This guide explains how to migrate the Post-ERG repository to a standard idiomatic PHP structure.

## 📋 Overview

### Current Structure
```
posterg-website/
├── apps/
│   ├── public/       # Public website
│   └── admin/        # Admin panel
├── shared/           # Shared PHP libraries
└── database/         # Database files
```

### New Structure (Standard PHP)
```
posterg-website/
├── index.php         # Public root
├── *.php             # Public PHP files
├── admin/            # Admin panel
├── lib/              # Shared libraries (renamed from shared/)
├── inc/              # Templates (header/footer)
├── assets/           # Static files
├── database/         # Database files
└── vendor/           # Third-party code (gitignored)
```

---

## 🎯 Benefits

✅ **Standard PHP structure** - Follows community conventions  
✅ **Flatter hierarchy** - Easier navigation  
✅ **Simpler paths** - Less `../../` in code  
✅ **Cleaner deployment** - Single rsync command  
✅ **Live reload** - Auto-refresh during development  

---

## 🚀 Migration Steps

### Step 1: Review the Plan

Read the restructure plan:
```bash
cat docs/RESTRUCTURE_PLAN.md
```

### Step 2: Commit Current State

**Important:** Commit all your current work first!

```bash
git add -A
git commit -m "Pre-migration checkpoint"
```

### Step 3: Run Migration Script

```bash
./migrate-structure.sh
```

This will:
- Move `apps/public/*` to root
- Move `apps/admin/` to `admin/`
- Rename `shared/` to `src/`
- Update all `require` paths automatically
- Remove `apps/` directory
- Update `.gitignore`

### Step 4: Test Locally

```bash
# Setup development environment
just setup-dev

# Test public site (with live reload!)
just serve-public

# Test admin panel
just serve-admin
```

Visit:
- http://localhost:8000 - Public site
- http://localhost:3000 - Admin panel

### Step 5: Verify Changes

```bash
# Check syntax
just check-public

# Run database tests
just stats-public

# View structure
tree -L 2 -I 'node_modules|.git|vendor'
```

### Step 6: Update Justfile

```bash
# Backup old justfile
mv justfile justfile.old

# Use new justfile
mv justfile.new justfile
```

### Step 7: Commit Migration

```bash
git add -A
git commit -m "Restructure to idiomatic PHP layout

- Moved apps/public to root
- Moved apps/admin to admin/
- Renamed shared/ to lib/
- Added php-live-reload for local dev
- Updated all require paths
- Simplified deployment"
```

### Step 8: Deploy to Production

```bash
# Deploy everything
just deploy

# Or deploy separately
just deploy-public
just deploy-admin
```

---

## 📝 What Changed

### File Movements

| Old Path | New Path |
|----------|----------|
| `apps/public/index.php` | `index.php` |
| `apps/public/memoire.php` | `memoire.php` |
| `apps/public/assets/` | `assets/` |
| `apps/public/inc/` | `inc/` |
| `apps/admin/` | `admin/` |
| `shared/Database.php` | `src/Database.php` |
| `shared/config.php` | `src/config.php` |
| `shared/cache/` | `src/cache/` |

### Path Updates

All PHP files automatically updated:

**Root files:**
```php
// Before
require_once __DIR__ . '/shared/Database.php';

// After
require_once __DIR__ . '/lib/Database.php';
```

**Admin files:**
```php
// Before
require_once __DIR__ . '/../../shared/Database.php';

// After
require_once __DIR__ . '/../lib/Database.php';
```

**Config file:**
```php
// Before
define('DB_ROOT', __DIR__ . '/..');

// After (stays the same)
define('DB_ROOT', __DIR__ . '/..');
```

### Justfile Changes

**Before:**
```bash
just serve-public  # Basic PHP server
```

**After:**
```bash
just setup-dev     # One-time: Install php-live-reload
just serve-public  # PHP server with live reload!
```

**Before:**
```bash
# Deploy in multiple steps
rsync apps/public/ posterg:/var/www/html/
rsync apps/admin/ posterg:/var/www/html/formulaire/
rsync shared/ posterg:/var/www/html/shared/
```

**After:**
```bash
# Deploy in one command
just deploy
```

---

## 🔄 PHP Live Reload

### What It Does

Automatically refreshes your browser when you save PHP files!

### Setup (One Time)

```bash
just setup-dev
```

This clones https://github.com/ryantate13/php-live-reload to `vendor/php-live-reload/` (gitignored).

### Usage

```bash
# Start with live reload
just serve-public  # or serve-admin

# Edit PHP files
# Browser auto-refreshes on save! 🎉
```

### How It Works

- Monitors PHP files for changes
- Sends reload signal via WebSocket
- Browser reloads automatically
- No browser extension needed
- Only for local development
- Never deployed to production

---

## 🧪 Testing

### Before Deploying

1. **Syntax check:**
   ```bash
   just check-public
   ```

2. **Test database:**
   ```bash
   just stats-public
   ```

3. **Test public site:**
   ```bash
   just serve-public
   # Visit http://localhost:8000
   ```

4. **Test admin:**
   ```bash
   just serve-admin
   # Visit http://localhost:3000
   ```

5. **Check file permissions:**
   ```bash
   ls -la | head -n 20
   ls -la admin/ | head -n 20
   ls -la lib/
   ```

### After Deploying

1. **Test public site:**
   ```bash
   curl -I https://posterg.erg.be/
   ```

2. **Test CSS loading:**
   ```bash
   curl -I https://posterg.erg.be/assets/posterg.css
   ```

3. **Test admin:**
   ```bash
   curl -I https://posterg.erg.be/admin/
   ```

---

## 🔙 Rollback (If Needed)

If something goes wrong:

```bash
# Revert the migration
git reset --hard HEAD~1

# Or restore from backup
git checkout HEAD~1 -- .
```

---

## 📚 New Directory Structure

```
posterg-website/
├── index.php             # Public site root
├── memoire.php           # Thesis detail page
├── search.php            # Search page
├── apropos.php           # About page
├── contact.php           # Contact page
├── licences.php          # Licenses page
├── test_db.php           # Database test script
│
├── assets/               # Static files
│   ├── posterg.css      # Main CSS
│   ├── normalize.css    # CSS reset
│   ├── fonts/           # Custom fonts
│   └── icons.svg        # Icon set
│
├── inc/                  # Page templates
│   ├── header.php       # Site header
│   └── footer.php       # Site footer
│
├── lib/                  # Shared libraries (was shared/)
│   ├── Database.php     # Database class
│   ├── RateLimit.php    # Rate limiting
│   ├── config.php       # Configuration
│   └── cache/           # Cache files
│
├── admin/                # Admin panel (was apps/admin/)
│   ├── index.php        # Admin dashboard
│   ├── list.php         # Thesis list
│   ├── edit.php         # Edit thesis
│   ├── formulaire.php   # Add thesis
│   ├── import.php       # Import tool
│   └── data/            # Upload directories
│
├── database/             # Database files & schema
│   ├── schema.sql       # Database schema
│   ├── test.db          # Test database
│   ├── fixtures/        # Test data generators
│   └── *.md             # Documentation
│
├── vendor/               # Third-party code (gitignored)
│   └── php-live-reload/ # Live reload tool
│
├── nginx/                # Server configuration
├── docs/                 # Documentation
├── tests/                # Tests (future)
│
├── justfile              # Task runner
├── .gitignore            # Git ignore rules
└── README.md             # Project readme
```

---

## ❓ FAQ

### Q: Will the migration break the deployed site?

**A:** No. The migration only affects your local repository. Deploy only after testing locally.

### Q: Do I need to update the database?

**A:** No. The database structure doesn't change. Only file paths change.

### Q: What about nginx configuration?

**A:** Nginx config doesn't need to change. It still serves from `/var/www/html/`.

### Q: Will git history be preserved?

**A:** Yes. Git tracks file movements. Use `git log --follow filename.php` to see history.

### Q: Can I undo the migration?

**A:** Yes. Use `git reset --hard HEAD~1` before committing.

### Q: Does php-live-reload work on all platforms?

**A:** Yes. Works on Linux, macOS, and Windows (with PHP installed).

### Q: Will php-live-reload be deployed?

**A:** No. It's in `vendor/` which is gitignored and excluded from deployment.

---

## 🆘 Troubleshooting

### Migration script fails

**Check you're in the repo root:**
```bash
pwd
ls -la apps shared
```

**Make script executable:**
```bash
chmod +x migrate-structure.sh
```

### PHP can't find lib/ files

**Check paths were updated:**
```bash
grep -r "require.*lib/" . --include="*.php" | head -n 5
```

**Manually fix a file:**
```bash
# Edit the file and change:
require_once __DIR__ . '/shared/Database.php';
# To:
require_once __DIR__ . '/lib/Database.php';
```

### Live reload doesn't work

**Check vendor directory:**
```bash
ls -la vendor/php-live-reload/
```

**Re-run setup:**
```bash
just setup-dev
```

### Site works locally but not on server

**Check file permissions on server:**
```bash
ssh posterg "ls -la /var/www/html/ | head -n 20"
```

**Re-run deployment:**
```bash
just deploy
```

---

## 📞 Need Help?

1. **Check the plan:** `cat docs/RESTRUCTURE_PLAN.md`
2. **Review justfile:** `cat justfile`
3. **Check git status:** `git status`
4. **Test locally first:** `just serve-public`

---

**Ready to migrate?**

```bash
./migrate-structure.sh
```

Good luck! 🚀