arbeitsstunden/AGENTS.md

AGENTS

Stack And Entry Points

• This repo is a plain PHP app for Strato-style hosting. There is no Node, Composer, container, or build step.
• Live web root is httpdocs/.
• Main app entrypoint: httpdocs/index.php.
• First-time setup entrypoint: httpdocs/install.php.
• App wiring and request handling live in httpdocs/app/bootstrap.php.
• All HTML/UI rendering lives in httpdocs/app/views.php.

Deployment Reality

• Changes in this repo do nothing until the contents of httpdocs/ are uploaded to the server.
• If the user says “nothing changed”, verify whether the live site is serving the current workspace contents before changing logic again.
• The live site can be checked directly at http://arbeitsstunden.tc-ingelfingen.de.

Runtime Behavior

• The app supports two modes:
  • With DB: MySQL/MariaDB via DB_HOST, DB_NAME, DB_USER, DB_PASS.
  • Without DB: demo mode with in-code users from findUserByEmail() and in-code member/hour data from fetchUsers() / fetchLogs().
• index.php redirects to install.php only when a DB connection exists and no users are installed.
• install.php only works with a DB connection; without DB it only shows an error.

Roles And UI Rules

• Roles are member, editor, admin.
• member should only see their own hours on the dashboard.
• editor and admin should see their own hours plus all members in the dashboard table.
• Admin-only menu item is Vereinskonfiguration.
• Header should keep club name on the left and current user + logout on the right.
• Navigation is implemented as a left sidebar inside renderAppShell().

Persistence Gotchas

• Club settings are persisted in DB table settings and read into $config in bootstrap.php.
• If settings appear not to save, check DB mode first. In demo mode there is no DB persistence.
• Schema is created in initSchema() at runtime. Keep schema.sql aligned with runtime-created tables.
• schema.sql currently contains seed password hashes that may drift from runtime-generated demo passwords; trust runtime behavior in bootstrap.php over static SQL prose.

Session And Auth Gotchas

• Session handling is configured manually in bootstrap.php with session_set_cookie_params() before session_start().
• Login redirects to /?page=dashboard after setting $_SESSION['user'].
• If auth appears broken, inspect currentUser() and the session flow in bootstrap.php before changing UI conditionals.

Editing Guidance

• Most app behavior changes require editing httpdocs/app/views.php and sometimes httpdocs/app/bootstrap.php together.
• Prefer minimal inline changes over adding new abstractions; the app is intentionally small and file-local.
• When changing page layout, update only renderAppShell() unless the login or install flow is involved.

Verification

• There is no automated test suite in the repo.
• Best available verification is:
  • read the affected PHP files,
  • check role-gated branches in views.php and action handling in bootstrap.php,
  • optionally fetch the live URL to compare deployed output versus workspace output.