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

# 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:

   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):

   mkdir -p apps/{public,admin}
   mkdir -p shared
   mkdir -p database/fixtures
   

2. Move applications:

   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:

   mv apps/public/RateLimit.php shared/
   

5. Reorganize database:

   mv db database
   mv apps/public/tests/Fixtures/CreateTestDatabase.php database/fixtures/
   

6. Update all require_once paths:

   // 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:

   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:

   [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:

    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:

   mkdir shared
   

2. Create unified Database.php in shared/:

   // 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/:

   mv front-backend/RateLimit.php shared/
   

4. Update both apps to use shared/:

   // 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:

   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?