# Papa-Kind-Treff – Project Context

Updated: 2026-08-07

## Summary
Papa-Kind-Treff is a PHP-based platform for fathers. Core areas are local events, appointments, and meetups, a community forum, member profiles with optional child information, and a moderation/admin area.

## Key Product Decisions
- Main navigation remains intentionally compact: `Home`, `Event Search`, `Community`.
- `Events` is the primary product term across the UI.
- Secondary wording is used only in SEO and explanatory copy.
- The community is hierarchical: categories -> boards -> threads -> posts.
- Moderation is separated from the normal community frontend.
- Location features are important for local discovery.
- The existing `events` logic remains active for now, but future growth should move toward a broader listing, place, and occurrence model.
- Site admins get a dedicated system section for global operating and service flags.

## Account / Member Area
- The top-right profile menu only contains `Profile`, `Admin Settings` for authorized users, and `Logout`.
- The profile area contains personal information, children, own events, own places and event-style entries, cookie/account settings, and community information.
- The admin area is separated from the profile area and contains, depending on permissions, profile levels, categories, system settings, community moderation, and listing approvals.
- Admin subsections stay within the same dashboard layout. Listing approvals only show not-yet-published places and event-style entries and allow direct editing; community moderation only shows open applications and reports; roles and system levels live in User Management, while the community migration lives under System.
- Existing direct links to `Categories`, `Profile Levels`, and `System` are automatically assigned to the admin area.
- Children can be created, edited, and deleted.
- If a birth date is set, age is calculated automatically and updated later when needed.
- Account email is encrypted application-side and addressed through a separate HMAC lookup hash.
- Profile address can be completed via address search or browser-based location import.
- The `Events` area is limited again to real own events and event participations.
- The `Events` area now also provides a manual ICS export and a personal subscribable calendar feed for all own events and event participations.
- The `Events` area is now separated in the UI into `My Events`, `Calendar Sync`, and `Expired Events` so that active events, calendar tasks, and past items stay clearly separated.
- Inside `My Events`, the `Create New Event` button now lives directly in the upper tab row; the previous participation box is now labeled `Registered Events` and also includes a direct link to `Event Search`.
- Places and event-like entries were moved for now into a separate member-area section `Places & Events`.
- Inside `Places & Events`, users can create permanent places and time-limited event-style entries.
- New places and event-style entries stay in a pending state until an admin approves them for publication.
- Not-yet-published place and event-style suggestions can be edited directly by their creator inside the member area.
- Change and deletion wishes for published places and event-style entries always run through a reasoned moderation request.
- Pending new places and event-style entries can already be used as location suggestions for events while they are still under review.
- Duplicate submissions for places and event-style entries should be blocked server-side at least by name and address.
- The `Events` input flow should stay as simple as possible and therefore only shows fields relevant for real scheduled events.
- Own events now only require title, date, and the `with children` choice; the description is optional.
- Event locations now support the modes `place from database`, `event from database`, or `custom`.
- When a database-backed place or event is selected, the address and category are taken directly from that source entry.
- Database-backed event locations now use a real select field instead of free text; `place from database` only shows places, while `event from database` only shows currently active event-style entries inside their valid date window.
- Inside the own-event form, `valid until` and `recurrence` are hidden.
- When an own event uses a database-backed location, address and category are shown as informational values and are not edited directly.
- The own-event form now offers direct links into creating a new place or a new event-style listing.
- After that intermediate step, the user returns to the own-event form with the previous event input restored and the newly created place or event-style listing already selected.
- When `event from database` is selected, the event date must fall inside that source event's valid date window.
- Categories in the member area are handled via a search input with existing suggestions and automatic creation when needed.
- Own events support an optional description, a clear `with children` yes/no field, optional capacity, an optional image, and either a database-backed location or a custom address.
- `Profile Levels` is an owner-only area for community levels and the overview of system levels.
- Community levels are now editable through `system_settings.community_levels_json` and currently carry the rights `highlight helpful replies` and `apply for forum admin`.
- Inside `Profile Levels`, the owner can additionally search users and manually increase community points with a required reason.
- `Profile Levels` also includes a list of users who reached at least the rank `Pillar of the Fathers Community` within the last 30 days.
- System levels remain separate as the roles `Forum Admin`, `Site Admin`, and `SiteOwner`.
- `Forum Admin` can already confirm and merge categories as well as approve places and event-style entries.
- `SiteOwner` and `Site Admin` fully inherit those approval rights.
- System-level assignment in `Community Admin` now runs through user search instead of raw user IDs; site admins remain limited by the existing role rules.
- Categories no longer live under `System`, but in their own member-area section `Categories`; that area only shows newly created categories and merges them into existing database categories through a suggestion field.
- New categories remain visible there until an authorized user confirms them or merges them into an existing category.
- The `Categories` area also includes a search across existing categories so they can be found and merged directly.
- During merging, the category that should not be kept is removed completely and the view is reloaded fresh afterwards.
- Merged categories are additionally blocked internally through redirects so default seeding or later inputs cannot make them selectable again.
- During merging, it is now possible to explicitly choose which of the two categories should be kept.
- Community levels can now additionally carry the rights for category handling as well as place and event approvals.
- Existing stored community levels receive these two rights automatically in the fallback from 750 points upward, unless they were explicitly saved differently.

## Technical Frame
- External API keys are provided only through server environment variables or the local, unversioned `config/secrets.local.php` file outside the webroot.
- custom front controller in `public/index.php`
- templates under `partials/`
- business logic under `src/App/`
- global frontend mainly via `public/assets/js/app.js` and `public/assets/css/app.css`

## New Expansion Stage: Listings and Places
- New table base: `listing_places`, `listings`, `listing_occurrences`, `listing_prices`, `listing_benefits`, `listing_categories`
- Goal: later distinguish between own event, partner offer, general place, and editorial event entry
- In admin approvals, enabled place providers are searched server-side in parallel: OpenStreetMap/Nominatim, Google Places, and Azure Maps. An admin deliberately selects a match; links to multiple providers can be saved for one place. Google aggregate rating and rating count are loaded only after the selected Google link.
- The admin view for places and events has the sub-items `Approvals`, `Existing place editing` with a search field, and `Missing information`. The latter filters published entries by links missing from at least one currently enabled provider.
- After an external match is accepted, its temporary result list is removed. The Edit button is available in each of these subviews to check the name and address.
- Authorized admins can correct published places and events directly. If the full OSM query returns no match, simplified address and name-city queries are tried as well.
- A manual admin lookup sends the open entry's name and address data to enabled place providers; privacy and consent notices must be reviewed before enabling this in production.

## Deferred To-dos
- Large calendar-provider integrations should be added later in addition to the ICS feed, starting primarily with Google and Microsoft/Outlook.
- The target model is no reverse sync, but a user-side OAuth login through Papa-Kind-Treff followed by a direct calendar connection or event synchronization at the respective provider.

## Maintenance Note
- Whenever one of these files changes, the matching files in `Internal/de/` and `Internal/en/` must be kept aligned.
- The root `README.md` acts as the startup document for new chats and should be reviewed alongside major context changes.