xamxam/docs/REPOSITORY_STRUCTURE_ANALYSIS.md

# Repository Structure Analysis

## Current Structure

```
posterg-website/                    (monorepo root)
├── front-backend/                  Public-facing site
│   ├── index.php                  Browse theses
│   ├── search.php                 Search feature
│   ├── memoire.php                View individual thesis
│   ├── Database.php               DB connection (reads ../formulaire/test.db)
│   ├── RateLimit.php              Rate limiting
│   ├── tests/                     Tests (Unit/Integration/Security)
│   ├── assets/                    CSS, images
│   └── inc/                       Header/footer templates
│
├── formulaire/                     Submission system (admin)
│   ├── index.php                  List submissions
│   ├── formulaire.php             Submission form
│   ├── edit.php                   Edit submissions
│   ├── Database.php               DB connection (different implementation!)
│   ├── assets/                    CSS, images
│   └── data/                      Upload storage
│
├── db/                             Shared database schemas
│   ├── schema.sql                 Database structure
│   ├── posterg.db                 Production database
│   └── README.md                  Documentation
│
├── justfile                        Deployment recipes
└── README.md
```

## Deployment Model

```bash
# front-backend → /var/www/html/          (root domain)
rsync ./front-backend/ server:/var/www/html/

# formulaire → /var/www/html/formulaire/  (subdomain or /formulaire path)
rsync ./formulaire/ server:/var/www/html/formulaire/
```

**URL Structure:**
- Public site: `https://posterg.example.com/`
- Admin/submission: `https://posterg.example.com/formulaire/`

## Issues with Current Structure

### ❌ Problems

1. **Inconsistent Database Access**
   - `front-backend/Database.php` points to `../formulaire/test.db`
   - `formulaire/Database.php` points to `../db/posterg.db` (production)
   - Different implementations, different paths

2. **Code Duplication**
   - Two separate `Database.php` files with different logic
   - No shared code between front-backend and formulaire

3. **Confusing Dependencies**
   - front-backend depends on formulaire for database location
   - Circular/unclear relationship

4. **Test Database Location**
   - Currently in `formulaire/test.db`
   - Should be in `db/` with schema

---

## Option Analysis

### Option A: Keep Monorepo, Improve Organization ⭐ RECOMMENDED

```
posterg-website/
├── apps/                          Application code
│   ├── public/                   Public-facing site (was front-backend)
│   │   ├── index.php
│   │   ├── search.php
│   │   ├── memoire.php
│   │   ├── assets/
│   │   ├── inc/
│   │   └── tests/
│   │
│   └── admin/                    Submission system (was formulaire)
│       ├── index.php
│       ├── formulaire.php
│       ├── edit.php
│       ├── assets/
│       └── data/
│
├── shared/                        Shared code
│   ├── Database.php              Single DB class used by both apps
│   └── RateLimit.php             Shared utilities
│
├── database/                      Database files (was db/)
│   ├── schema.sql
│   ├── posterg.db               Production database
│   ├── test.db                  Test database
│   └── README.md
│
├── justfile                       Deployment
├── composer.json                  Dependencies
└── README.md
```

**Pros:**
- ✅ Clear separation: public vs admin
- ✅ Shared code in one place (DRY)
- ✅ Single source of truth for database
- ✅ Professional naming (apps/, shared/, database/)
- ✅ Easy to add more apps later

**Cons:**
- ⚠️ Requires refactoring paths in all files
- ⚠️ Need to update deployment scripts

**Migration Effort:** Medium (2-3 hours)

---

### Option B: Promote front-backend to Root

```
posterg-website/                   (IS the public site)
├── index.php                     Public site files at root
├── search.php
├── memoire.php
├── Database.php
├── RateLimit.php
├── assets/
├── inc/
├── tests/
│
├── formulaire/                   Keep admin as subfolder
│   ├── index.php
│   ├── formulaire.php
│   └── ...
│
└── db/                           Shared database
    ├── schema.sql
    └── posterg.db
```

**Pros:**
- ✅ Simpler paths for main application
- ✅ Less nesting
- ✅ Minimal refactoring needed

**Cons:**
- ❌ Root directory becomes cluttered
- ❌ Mixed responsibilities (public site + monorepo management)
- ❌ Still have duplicate Database.php files
- ❌ Harder to add new applications
- ❌ Tests mixed with application code at root

**Migration Effort:** Low (30 mins)

---

### Option C: Flatten Everything

```
posterg-website/
├── public/                       Public site (was front-backend)
├── admin/                        Submission (was formulaire)
├── database/                     Schemas (was db)
├── shared/                       Shared code
├── tests/                        All tests
├── composer.json
└── justfile
```

**Pros:**
- ✅ Very clean root directory
- ✅ Professional structure
- ✅ Clear naming

**Cons:**
- ❌ Deployment scripts need updates
- ❌ All tests in one place (less clear ownership)

**Migration Effort:** Medium (2 hours)

---

### Option D: Keep Current Structure, Fix Issues

```
posterg-website/
├── front-backend/                Keep as-is
│   └── (no Database.php here)
│
├── formulaire/                   Keep as-is
│   └── (no Database.php here)
│
├── shared/                       NEW: Shared code
│   ├── Database.php              Single database class
│   └── RateLimit.php
│
└── db/                           Keep as-is
    ├── schema.sql
    ├── posterg.db
    └── test.db
```

**Pros:**
- ✅ Minimal changes
- ✅ Keeps familiar structure
- ✅ Fixes code duplication

**Cons:**
- ⚠️ Still nested (front-backend, formulaire)
- ⚠️ Names not professional (what does "front-backend" mean?)

**Migration Effort:** Low (1 hour)

---

## Detailed Recommendation: Option A

### Why Option A is Best

1. **Scalability** - Easy to add new apps:
   - `apps/api/` for REST API
   - `apps/import/` for batch imports
   - Each app is independent

2. **Professional** - Industry standard structure:
   - Clear naming (`public`, `admin`, `shared`)
   - Other developers understand immediately
   - Matches Laravel, Symfony conventions

3. **Maintainability**:
   - Single Database.php used by all apps
   - Shared utilities (RateLimit) in one place
   - Tests stay with their applications

4. **Deployment Clarity**:
   ```just
   deploy-public:
       rsync apps/public/ server:/var/www/html/

   deploy-admin:
       rsync apps/admin/ server:/var/www/html/formulaire/

   deploy-shared:
       rsync shared/ server:/var/www/html/shared/
   ```

### Proposed Structure Details

```
posterg-website/
│
├── apps/                                    Applications
│   ├── public/                             Public-facing site
│   │   ├── index.php                      Homepage (browse theses)
│   │   ├── search.php                     Search interface
│   │   ├── memoire.php                    Individual thesis view
│   │   ├── apropos.php, contact.php, licences.php
│   │   ├── assets/                        Public CSS, images
│   │   ├── inc/                           Templates (header, footer)
│   │   └── tests/                         Public site tests
│   │       ├── Unit/
│   │       ├── Integration/
│   │       ├── Security/
│   │       └── Fixtures/
│   │
│   └── admin/                              Admin/submission system
│       ├── index.php                      Dashboard (list theses)
│       ├── formulaire.php                 Submission form
│       ├── edit.php                       Edit submission
│       ├── import.php                     Bulk import
│       ├── list.php                       List view
│       ├── assets/                        Admin CSS
│       ├── data/                          File uploads
│       └── tests/                         Admin tests (optional)
│
├── shared/                                  Shared code (library)
│   ├── Database.php                        Single database class
│   ├── RateLimit.php                       Rate limiting
│   └── (future shared utilities)
│
├── database/                                Database files & schemas
│   ├── schema.sql                          Database structure
│   ├── migrations/                         Migration scripts (future)
│   ├── fixtures/                           Test data
│   │   └── CreateTestDatabase.php
│   ├── posterg.db                          Production database (gitignored)
│   └── test.db                             Test database (gitignored)
│
├── config/                                  Configuration (optional)
│   ├── database.php                        DB connection settings
│   └── paths.php                           Path constants
│
├── .gitignore                               Git exclusions
├── justfile                                 Deployment recipes
├── composer.json                            Dependencies
├── run-tests.php                            Test runner
└── README.md                                Documentation
```

### Migration Steps for Option A

1. **Create new structure** (no breaking changes yet):
   ```bash
   mkdir -p apps/{public,admin}
   mkdir -p shared
   mkdir -p database/fixtures
   ```

2. **Move applications**:
   ```bash
   mv front-backend/* apps/public/
   mv formulaire/* apps/admin/
   rmdir front-backend formulaire
   ```

3. **Create shared Database.php**:
   - Merge best parts of both Database.php files
   - Make database path configurable
   - Use production db by default

4. **Move shared utilities**:
   ```bash
   mv apps/public/RateLimit.php shared/
   ```

5. **Reorganize database**:
   ```bash
   mv db database
   mv apps/public/tests/Fixtures/CreateTestDatabase.php database/fixtures/
   ```

6. **Update all `require_once` paths**:
   ```php
   // In apps/public/index.php
   require_once __DIR__ . '/../../shared/Database.php';
   require_once __DIR__ . '/../../shared/RateLimit.php';

   // In apps/admin/index.php
   require_once __DIR__ . '/../../shared/Database.php';
   ```

7. **Update Database.php to use config**:
   ```php
   class Database {
       private function __construct() {
           // Determine database path
           $dbPath = $this->getDatabasePath();

           $this->pdo = new PDO('sqlite:' . $dbPath);
           // ...
       }

       private function getDatabasePath() {
           // Check environment
           if (file_exists(__DIR__ . '/../storage/test.db')) {
               return __DIR__ . '/../storage/test.db';
           }
           return __DIR__ . '/../storage/posterg.db';
       }
   }
   ```

8. **Update justfile**:
   ```just
   [group('deploy')]
   deploy-public:
       rsync -vur --progress \
         --exclude 'tests/' \
         --exclude '*.md' \
         apps/public/ posterg:/var/www/html/
       rsync -vur shared/ posterg:/var/www/html/shared/

   [group('deploy')]
   deploy-admin:
       rsync -vur --progress \
         --exclude 'tests/' \
         apps/admin/ posterg:/var/www/html/formulaire/

   [group('deploy')]
   deploy: deploy-public deploy-admin
   ```

9. **Update .gitignore**:
   ```
   /storage/*.db
   /apps/*/cache/
   /shared/cache/
   *.log
   ```

10. **Test everything**:
    ```bash
    php run-tests.php
    ```

---

## Alternative: Quick Fix (Option D)

If you don't want major refactoring right now:

### Minimal Changes to Current Structure

1. **Create shared/ directory**:
   ```bash
   mkdir shared
   ```

2. **Create unified Database.php in shared/**:
   ```php
   // shared/Database.php - works for both apps
   class Database {
       private function __construct() {
           // Smart path detection
           if (file_exists(__DIR__ . '/../db/test.db')) {
               $dbPath = __DIR__ . '/../db/test.db';
           } else {
               $dbPath = __DIR__ . '/../db/posterg.db';
           }

           $this->pdo = new PDO('sqlite:' . $dbPath);
           // ... rest of implementation
       }
   }
   ```

3. **Move RateLimit.php to shared/**:
   ```bash
   mv front-backend/RateLimit.php shared/
   ```

4. **Update both apps to use shared/**:
   ```php
   // In front-backend/index.php
   require_once __DIR__ . '/../shared/Database.php';

   // In formulaire/index.php
   require_once __DIR__ . '/../shared/Database.php';
   ```

5. **Delete duplicate Database.php files**:
   ```bash
   rm front-backend/Database.php
   rm formulaire/Database.php
   ```

**Result:**
```
posterg-website/
├── front-backend/         (uses shared/)
├── formulaire/            (uses shared/)
├── shared/                NEW: shared code
│   ├── Database.php
│   └── RateLimit.php
└── db/                    (existing)
```

---

## Comparison Matrix

| Criteria | Option A (Restructure) | Option B (Root) | Option C (Flatten) | Option D (Quick Fix) | Current |
|----------|----------------------|-----------------|-------------------|---------------------|---------|
| **Professional** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| **Scalable** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| **Clear Separation** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **Ease of Migration** | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | N/A |
| **Code Reuse** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐ |
| **Maintainability** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |

---

## Final Recommendation

### Short Term: Option D (Quick Fix)
- Takes 1 hour
- Fixes code duplication immediately
- Minimal risk
- Keeps familiar structure

### Long Term: Option A (Full Restructure)
- Plan for when you have 2-3 hours
- Professional, scalable structure
- Industry standard conventions
- Future-proof

### Do NOT: Option B (Promote to Root)
- Creates more problems than it solves
- Clutters root directory
- Doesn't fix core issues

---

## Questions to Consider

1. **How often do you modify both apps?**
   - Often → Option A (shared code helps)
   - Rarely → Option D is fine

2. **Will you add more applications?**
   - Yes (API, mobile backend, etc.) → Option A
   - No → Option D

3. **Team size?**
   - Solo → Option D ok
   - Team → Option A for clarity

4. **Timeline?**
   - Urgent → Option D
   - Can wait → Option A

---

## My Recommendation

**Start with Option D (Quick Fix), migrate to Option A later.**

**Immediate (30 mins):**
1. Create `shared/` directory
2. Move Database.php and RateLimit.php to shared/
3. Update both apps to use shared/
4. Test and deploy

**When you have time (Option A):**
- Better names (`apps/public/`, `apps/admin/`)
- Professional structure
- Industry conventions

Would you like me to help implement either approach?