xamxam/docs/ANALYSIS_STRUCTURE_REORG.md

Analysis: Proposed PHP Structure Reorganization

Summary

The proposed structure is a standard Laravel/Symfony-inspired architecture, but overengineered for this project's scale and conflicts with existing architectural decisions.

Key Issues

1. Redundant Separation

The project already has good separation of concerns:

• Controllers in src/ (14 focused classes)
• Templates in templates/
• Data in storage/ (outside web root)
• Organized tests

2. Conflicts with Existing Decisions

• docs/orm-assessment.md explicitly decided against Doctrine/ORM → Proposed src/Model/ entities contradict this
• No Composer in current project → Proposed structure requires PSR-4 autoloading
• App.php already does the job → Adding Core/AppKernel.php is redundant

3. Overengineering

• Repository + Service + Model layers for a ~15 page SQLite app creates 3x the code
• ThesisCreationService, AuthService, ExportService split logic that's currently cohesive
• Config/Settings.php replaces working config/bootstrap.php for no clear benefit

What Actually Makes Sense

High Value, Low Cost:

1. .env for secrets → Replace hardcoded credentials pattern
2. Single entry point → Move to public/index.php routing (requires nginx config changes)
3. Keep logic out of public/ → Already partially achieved

Medium Value:

4. Consolidate src/ classes → Group into subdirectories without full MVC overhaul
5. Move test.db from root → Into storage/ where it belongs

Low Value (Skip):

• Entity classes (conflicts with ORM assessment)
• Repository pattern (SQLite direct access is fine)
• Service layer over-splitting
• Composer integration (unless you need PHP packages)

Recommendation

Do NOT adopt the full proposed structure.

Instead, make incremental improvements:

1. Add .env support
2. Consolidate to single entry point
3. Organize src/ into logical subdirectories
4. Move stray files to proper locations

This achieves 80% of the benefits at 20% of the cost.

Questions to Consider

1. Are you planning to add external PHP dependencies? (If yes, Composer makes sense)
2. Do you expect multiple developers to work on this simultaneously? (Justifies stricter structure)
3. Is the current codebase difficult to maintain? (If no, restructure is premature optimization)