P4 project readability audit: codebase, naming, hierarchy, and navigability

[dominikletica]

Codebase Readability, Naming, And Navigation Audit

This issue tracks an ongoing project-wide audit for readability, deterministic naming, navigability, documentation usefulness, and structural coherence across PHP, JavaScript, CSS, Twig, tests, and developer-facing maps.

The goal is a codebase that feels intentionally designed, easy to navigate, easy to document, and consistent across domains. It should not read like an accumulated patchwork of feature slices or agent-generated naming drift.

Audit Scope

PHP Classes And Namespaces

• Review class names for consistent, deterministic, readable naming.
• Check whether namespace hierarchy supports navigation and domain ownership.
• Re-evaluate broad namespaces such as Core: do all classes there truly belong there, or should some move into clearer domain-owned namespaces?
• Identify free-floating classes/namespaces that would be easier to discover under a clearer hierarchy.
• For each relevant class, review constants, properties, variables, methods, public callables, route/API operation names, event names, and extension points for:
  • self-explanatory naming
  • stable domain ownership
  • easy documentation
  • predictable discoverability
  • consistency with nearby code

Class Map Documentation

• Review dev/CLASSMAP.md as an actual contributor lookup tool.
• Check whether entries are grouped clearly by domain and responsibility.
• Verify that relevant callables are present, obsolete entries are removed, and test references are useful.
• Improve structure where the map is hard to scan or no longer reflects current architecture.

JavaScript

• Review JS file names, module boundaries, function names, controller names, and local structure.
• Check whether JS naming and hierarchy align semantically with the PHP/domain structure where applicable.
• Identify duplicated helpers, unclear controller responsibilities, or inconsistent naming patterns.

CSS

• Review token names, selectors, utility abstractions, and file organization.
• Check whether CSS classes follow project naming rules and domain/component ownership.
• Check whether custom abstractions can also be accomplished by applying tailwind utility classes or scoped CSS variables instead.
• Improve ordering, grouping, comments, and discoverability where styles have become hard to reason about.

Twig

• Review template hierarchy, block names, variable names, component names, includes, and macros.
• Check whether templates are easy to navigate from route/controller to rendered UI.
• Identify naming drift, unclear partial boundaries, or repeated markup that should become a component/helper.

Modularization And Centralization

• Identify classes, templates, JS modules, or CSS files that have grown too large or mixed responsibilities.
• Look for duplicated logic that could be centralized behind small, readable helpers.
• Prefer modularity where it improves responsibility boundaries, documentation, testing, and reviewability.

Tests

• Review whether tests are all still necessary and behavior-focused.
• Identify redundant tests that can be merged without losing coverage.
• Find assertions on unstable values such as exact rendered DOM structure, incidental translations, version strings, ordering, or names where a more stable assertion would better express the behavior.
• Look for opportunities to speed up the full suite without reducing confidence.
• Identify expensive setup patterns, duplicated fixtures, or avoidable broad integration coverage.

Usage

This issue can be used in two ways:

1. Full-scale audit passes across the repository or a major domain.
2. PR-readiness checks for feature branches where naming, hierarchy, documentation, or test structure may have drifted.

PRs do not need to solve the entire issue. They should use this checklist to catch local drift early and either fix small issues directly or record larger follow-ups.

Desired Outcome

A codebase that is:

• consistently named
• easy to navigate
• easy to document
• modular without being fragmented
• structured by clear domain ownership
• predictable for contributors and reviewers
• stable under full-suite testing
• visibly intentional rather than accumulated