michaelschiemer/docs/tasks.md

Improvement Tasks Checklist

This document lists actionable, logically ordered improvements for the project. Each task is prefixed with a checkbox for tracking. Tasks span architecture, quality, security, performance, testing, developer experience, and documentation.

Note: Some items reference existing files and modules to guide implementation. Execute tasks incrementally from top to bottom for best results.

Wichtigste Aufgaben (Top-Prioritäten – sofort angehen)

Die folgenden Punkte liefern den größten Nutzen und sollten priorisiert bearbeitet werden. Sie referenzieren die entsprechenden Abschnitte weiter unten.

• CI/CD Pipeline aufsetzen und härten (Lint, PHPStan, Tests, Composer Audit) – siehe „CI/CD Pipeline Hardening“ (Punkt 2). Blocking für Qualität und Sicherheit.
• Statische Analyse hochdrehen (strict_types prüfen, PHPStan-Level erhöhen, Baseline pflegen) – siehe „Static Analysis and Type Safety“ (Punkt 3). Schneller Qualitätsgewinn.
• Kritische Tests ergänzen: Sicherheitskomponenten/WAF und Integrationspfade (Auth, Persistence) – siehe „Testing Improvements“ (Punkt 14/15) und „Security Improvements“ (Punkt 7).
• CacheKey-Typo in CacheFeatureFlagRepository beheben und Negative-Caching-Strategie absichern – siehe „Feature Flags System“ (Punkt 11) und „Concrete Fixes“ (Punkt 20).
• HTTP-Layer Tests für HttpRequest/Query, Fehlerpfade und Middleware-Kette – siehe „HTTP Layer and Routing“ (Punkt 10).
• WAF/Rate Limiting verbessern, Regeln schärfen, Tests hinzufügen – siehe „Security Improvements > Enhance WAF functionality“ (Punkt 7/IntelligentRateLimitLayer).
• Konfiguration & Secrets zentralisieren (.env.example vervollständigen, Validierung beim Boot) – siehe „Configuration and Secrets Management“ (Punkt 5).
• Observability Basis schaffen: strukturierte Logs, Metriken (Hit/Miss/Errors), Tracing-Hooks – siehe „Error Handling and Observability“ (Punkt 6) und „Performance and Caching“ (Punkt 8).
• Datenbank-Quick-Wins: N+1 erkennen, Indexe ergänzen, Integrations-Tests für Repositories – siehe „Data Layer and Persistence“ (Punkt 9).
• Deployment/Operations stabilisieren: Healthchecks in Docker Compose, idempotente Deploy-Schritte – siehe „Deployment and Ops“ (Punkt 19).
• Developer-Docs aktualisieren (Getting Started, Troubleshooting) und ADRs für Schlüsselentscheidungen – siehe „Documentation“ (Punkt 17) und „Developer Experience“ (Punkt 16).

1. Establish a Baseline and Governance

   • Define and document the minimum supported PHP version and runtime requirements (extensions) in README and composer.json (platform).
   • Align coding standards across the codebase (PHP CS Fixer rules and .editorconfig) and enforce via CI.
   • Introduce a clear versioning strategy (SemVer), CHANGELOG, and release process.
   • Audit .gitignore to ensure build artifacts, caches (var/, storage/cache/, vendor/* docs), and generated files are excluded from VCS.

2. CI/CD Pipeline Hardening

   • Add CI jobs: lint (php-cs-fixer dry-run), static analysis (phpstan), unit/integration tests (Pest), security scan (composer audit).
   • Add optional coverage reporting with Xdebug (XDEBUG_MODE=coverage) and a minimum threshold.
   • Add Docker image build/test job and push to a registry for deployment.
   • Introduce pre-commit hooks (lint, phpstan, pest) via Husky or CaptainHook for local dev.

3. Static Analysis and Type Safety

   • Enable strict_types everywhere (verify headers and add missing declarations).
   • Raise PHPStan level progressively to target a high level (e.g., 8/9) and generate/update baseline responsibly.
   • Add Psalm or PHPStan-specific rules for DDD boundaries and unsafe patterns (mixed usage, array shape validation).
   • Replace magic arrays with value objects or DTOs where appropriate; document contracts.

4. Dependency Injection and Module Boundaries

   • Document and formalize module boundaries (src/Application, src/Domain, src/Framework, src/Infrastructure) with allowed dependency directions.
   • Add architectural tests (Pest plugin or custom) to enforce dependency rules.
   • Review service wiring/discovery (DiscoveryServiceBootstrapper) and replace reflection-heavy or dynamic patterns with explicit configuration where it improves clarity/perf.
   • Ensure constructors favor interfaces; introduce missing interfaces for concrete dependencies.

5. Configuration and Secrets Management

   • Centralize configuration (env/config/*.php) and document defaults and overrides.
   • Validate config at boot (fail-fast with actionable errors).
   • Ensure secrets are sourced from environment/secret stores, not committed; add examples to .env.example.
   • Add configuration schema tests (ensuring required keys and types).

6. Error Handling and Observability

   • Standardize exception hierarchy and error codes across modules; avoid silent failures.
   • Add structured logging with context IDs (correlation, request, user) and log levels policy.
   • Introduce metrics for key operations (HTTP, cache, DB, queue) and expose Prometheus endpoint securely.
   • Add tracing hooks (OpenTelemetry) for critical paths; document propagation.

7. Security Posture

   • Perform a security audit against OWASP Top 10; document findings and remediation plan.
   • Harden WAF (src/Framework/Waf): review rules, rate limiting strategies, false positive handling, and add tests.
   • Ensure input validation and output encoding in View processors; review IfProcessor and templating for SSR XSS vectors.
   • Enforce HTTPS, secure cookies, CSRF tokens, and security headers (CSP, HSTS) in HTTP module and Nginx config.
   • Add dependency vulnerability scanning in CI (e.g., symfony/security-checker replacement via Composer audit).

8. Performance and Caching

   • Review and document cache strategy (Cache, MultiLevelCache, Async caches) and TTL policies per domain entity.
   • Add cache metrics (hit/miss/evictions) and logs to analyze effectiveness.
   • Implement cache warming for critical data at boot or via worker.
   • Resolve known cache correctness issues (e.g., negative caching keys, serialization safety).
   • Validate cache key naming with a central builder; enforce namespacing to avoid collisions.

9. Data Layer and Persistence

   • Review repositories for N+1 queries and missing indexes; add DB migrations and schema docs.
   • Create integration tests for critical repositories.
   • Introduce transaction boundaries and retry strategy where needed.
   • Add database health checks and readiness probes for Docker composition.

10. HTTP Layer and Routing

    • Increase test coverage for HttpRequest, Query, route resolution, middleware chain, and error responses.
    • Validate query parsing edge cases (duplicate keys, encodings) and add regression tests.
    • Normalize header casing and ensure PSR-7 compatibility where applicable.
    • Add request/response size limits and timeouts; document defaults.

11. Feature Flags System

    • Define a canonical FeatureFlag repository interface contract and behaviors (null vs. NOT_FOUND semantics).
    • Add integration tests for CacheFeatureFlagRepository and FileFeatureFlagRepository, including negative cache behavior.
    • Fix typing/typos in cache key creation (CacheKey vs Cachekey) and ensure cache stores only serializable, immutable objects.
    • Add an admin endpoint/UI hardening with authorization checks in FeatureFlagController.

12. Search Module

    • Validate SearchRequest input constraints and canonicalize parameters.
    • Add tests for SearchController behavior (pagination, empty results, errors).
    • Document search adapter contracts and index lifecycle.

13. View and Templating

    • Review Processors (e.g., IfProcessor) for safety and predictable evaluation semantics.
    • Add template linting step and cached view invalidation strategy.
    • Ensure compiled view cache is not committed and is purged on deploy; update .gitignore if necessary.

14. Queue and Async Processing

    • Define interfaces and contracts for queue-worker; add retry and backoff strategies.
    • Add idempotency guards for jobs and visibility timeouts.
    • Provide metrics and DLQ handling documentation.

15. Testing Strategy (Pest)

    • Standardize test namespaces and file layout; ensure Tests mirror src structure.
    • Add factories/fixtures for common entities and a Faker-based generator.
    • Add integration tests for critical flows (auth, payments, persistence).
    • Add browser/E2E tests (Cypress/Selenium) for top user journeys (optional but recommended).
    • Establish coverage thresholds per package and enforce in CI.

16. Developer Experience

    • Update Getting Started docs and ensure Docker build.sh and docker-compose flows are reliable across platforms.
    • Provide make targets or composer scripts for common tasks (cs, cs-fix, phpstan, pest, reload).
    • Create troubleshooting docs for Docker/DNS/cache issues; link from README.
    • Add local development data seeding scripts and reset commands.

17. Documentation

    • Consolidate scattered docs and backups (backups/docs-backup-*/), migrate relevant content into docs/.
    • Add architecture decision records (ADRs) for key choices (DI, caching, WAF, templating).
    • Auto-generate API docs where feasible and publish via the existing /api/docs endpoints.
    • Keep README concise and link to deeper docs; add contribution guidelines cross-links.

18. Code Hygiene and Consistency

    • Eliminate dead code, unused classes, and outdated experimental files; add CI check for unused symbols if possible.
    • Normalize naming (English vs. German in code identifiers; German is fine for test names per guidelines).
    • Ensure immutability/read-only where appropriate (readonly, final) and avoid incidental mutation.
    • Replace ad-hoc string constants with enums/ValueObjects where it improves safety.
    • Ensure all public APIs have PHPDoc where types can’t fully express intent.

19. Deployment and Ops

    • Review deploy.sh steps for idempotency and error handling; add rollback steps.
    • Add health checks to Docker Compose (web, php, db, redis) and readiness/liveness probes.
    • Parameterize environment-specific config (staging/production) and secrets injection.
    • Ensure asset build and cache warmups are part of deployment pipeline.

20. Concrete Fixes Identified During Review

    • Fix Cache key class typo in CacheFeatureFlagRepository::getCacheKey (use CacheKey, not Cachekey) and add a unit test to catch it.
    • Verify negative caching marker ('NOT_FOUND') doesn’t collide with real values; prefer a dedicated NullObject or sentinel ValueObject.
    • Audit src/Framework/View/cache/* and similar generated artifacts into .gitignore and remove from repo if committed.

21. Monitoring and Alerting

    • Add basic alerting for error rates, latency, and resource saturation.
    • Create runbooks for on-call responses and link them from docs/operations.

22. Accessibility and Internationalization (Optional but Valuable)

    • Add A11y checks for rendered views and components.
    • Formalize i18n/l10n strategy for user-facing content.

23. Risk Register and Backlog Grooming

    • Maintain a living risk register (security, data loss, availability) and mitigation tasks.
    • Review this checklist quarterly and update priorities.