mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 19:19:19 +02:00
Major refactor
- update the structure to have monolithic setup - updated deployments - added live-reloading for devops
This commit is contained in:
Théophile Gervreau-Mercier
534
docs/REPOSITORY_STRUCTURE_ANALYSIS.md
Normal file
534
docs/REPOSITORY_STRUCTURE_ANALYSIS.md
Normal file
@@ -0,0 +1,534 @@
|
||||
# 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__ . '/../database/test.db')) {
|
||||
return __DIR__ . '/../database/test.db';
|
||||
}
|
||||
return __DIR__ . '/../database/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**:
|
||||
```
|
||||
/database/*.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?
|
||||
Reference in New Issue
Block a user