pp-planer/AGENTS.md

ChurchService presenter software show creator

Description

There is tool (churchtools - called cts from now on) to plan a church service, that contains all parts of the service (information, songs, sermon, prayer, etc.).

Use CTS API for services: https://api.church.tools/package-CT.ChurchService.html.

All the wording in the frontend and communication has to be in German with Du, not Sie.

TechStack

• Laravel (Vue+Inertia) App, with Sqlite (switchable to MySQL)
• use DB for caching the API data and just "Update" the DB from the API
• use CTS API with existing env CTS_API_TOKEN (.env for LIVE, .env.example with same content for you) for auth - ONLY DO READS, NO WRITES OR CHANGES ARE ALLOWED

General

• Login should be done via OAUTH for all churchtools users (https://churchtools.academy/de/help/system-einstellungen/oauth-login-systemeinstellungen/oauth-zwischen-zwei-churchtools-systemen/) and linked to an automatically created local user.
• There should be Button in the Top Bar, to refresh the Data from the CTS API and a timestamp with the latest refresh.
• LoggedIn User should be visible in the Top Bar
• every action should be immediately persistent, no separate "save" button required, unless explicitly described.
• ProPresenter .pro file parser/generator is implemented as a separate composer package (propresenter/parser) linked via path repository

The Plan

We use the data from the API, to create a form to finalize the service setup and to create a file for the presenter software at the end.

1. Show all today or future services in a list, with details (Title, Preacher, 'beamer technican', qty of songs, last changed, finalized_at) and state of the setup (No or Yes at...):

   • x/y songs found and mapped
   • x/y songs verified arrangement
   • sermon slides uploaded
   • X info slides uploaded
   • finalized at

2. for every service, show Action Buttons:

   • if finalized: ReOpen and Download
   • if NOT finalized: Edit and Finalize
3. • ReOpen and Finalize just change the status of the service
   • Edit shows a form, with these Blocks to edit (details of these blocks are below)
     • information
     • moderation
     • sermon
     • songs

Form Blocks

Block: Information

• show list of thumbnails for all uploaded slides with a muted upload date field with uploader name, and a prominent Expiredate field
• each thumbnail could be delete (softdelete) or can inline change the date with a datepicker
• add big plus icon/area for drag'n'drop or click for fileupload new files with a datepicker for a date, that was added to all files as expire date
• automatically show these files to all future services, till the expire date is after the service date

Block: Moderation

Same features as Block Information but without the datepicker and only relevant for this service.

Block: Sermon

Same features as Block Moderation.

Block: Songs

• Show all songs (Name, CCLI ID, has Translation ..) from the service in the right order.
• on every update from the CTS API, try to match the song with the CCLI-ID to an existing song from the DB
  • if NOT matched
    • show a button "request creation", which causes an EMAIL to a configured mail address, with the song and the CCLI Id and the ask for create the song
    • and show a searchable select field of all songs in the DB (CCLI ID included and searchable) to manually assign a song from the DB to this service song
  • if song found:
    • if song is translated, show checkbox (default:true) for use the version with translation
    • every song has a body for the arrangement selection/configuration
      • select field with all existing arrangements
      • "add" Button to create a new arangmengt (clone from master order) and ask for a name
      • "clone" Button to clone the selected arragenement and ask for a name
      • show the groups of the arrangement and make possible to rearange or add a group to the arrangement via drag'n'drop, like rev/form-song-arangment-config.jpg
• every song with a selected arrangement ("normal" should selected always as default) should have two buttons:
  • preview: show the text of the song in the order of the arrangement configuration, prominent highlighted which textpart was with group
  • download: download the preview as a nice pdf with header/footer and copyright footer from the Song DB.

File Upload

• could be a zip file, contained multiple other files of types below, handle as mass upload
• could me multiple files, so handle each one as a single file for types below
• could be an image file (png, jpg, jpeg) -> always convert to jpg 1920x1080 (dont cut parts of an image, keep orientation and ratio)
• could be a ppt or pptx (powerpoint) -> convert to multiple JPG with 1920x1080 (see jpg convert)

SongDB Import

There should be a menu item for songDB in the Top.

• it shows all songs from the DB, with created, last update, ccliID, last_used_in_service every song has a delete (soft_delete), download, translate and an edit button
• edit: shows a popup with Name, CCLI and copyright text (all that is available from song metadata) and the arrangement configurator from the service->song block
• download: download generated .pro file from the songDB for this song
• translate: allow add a full text or an URL to the Full text, and then start an editor, that shows two columns for every slide of every group. Left the original text, right a texteditor, with the imported text - always the same line qty of text from the original is used from the given translated text. Save this as translation for this song, and mark it as with translation.
• UploadArea for drag'n'drop and click for upload, to upload a .pro file, a zip file with multiple .pro files, or a bunch of .pro files, which should be parsed (this module was integrated later, so show an Exception here till this was finalized) and added into the song DB.

---

CCLI Import

Songs can be imported from CCLI SongSelect via a paste-based flow (no server-side scraping — ToS-compliant).

How it works

1. User opens a song on songselect.ccli.com in their browser (must be logged in with their CCL account)
2. User copies the full page text (Ctrl+A → Ctrl+C)
3. User clicks "Aus CCLI importieren" in the SongDB or service form, pastes the text, clicks "Vorschau", then "Importieren"

Alternatively, install the browser bookmarklet from Settings → CCLI Import. The bookmarklet automates step 2-3 in two clicks.

Key files

File	Purpose
app/Services/CcliPasteParser.php	Pure-PHP parser: extracts title/author/CCLI-Nr/year/sections from pasted text
app/Services/CcliImportService.php	Upserts Song + Arrangement + Labels + Slides; handles duplicates and soft-delete restore
app/Services/CcliTranslationPairingService.php	Auto-pairs CCLI sections with local song labels for translation import
app/Support/CcliLabels.php	Section-label regex + EN↔DE name mapping (Verse↔Strophe, Chorus↔Refrain, etc.)
app/Http/Controllers/CcliPasteController.php	POST /api/ccli/preview + POST /api/songs/import-from-ccli-paste (3 modes)
app/Http/Controllers/BookmarkletController.php	GET /bookmarklets/ccli-import.js — serves the bookmarklet JS
resources/js/Components/CcliPasteDialog.vue	Modal: textarea → preview → import buttons (surface-aware)
resources/js/Pages/Songs/ImportFromCcliPaste.vue	Bookmarklet redirect landing page
tests/Fixtures/ccli/	22 synthetic CCLI-format fixture files for parser tests

Test coverage

• tests/Feature/CcliPasteParserTest.php — parser against all 22 fixtures
• tests/Feature/CcliImportServiceTest.php — upsert, duplicate, restore, transaction
• tests/Feature/CcliTranslationPairingServiceTest.php — label pairing, line distribution
• tests/Feature/CcliPasteControllerTest.php — API endpoints, auth, throttle
• tests/e2e/ccli-paste-import.spec.ts — SongDB import flow
• tests/e2e/ccli-bookmarklet.spec.ts — bookmarklet endpoint + Settings page
• tests/e2e/ccli-translation-pairing.spec.ts — Translate.vue prefill

Maintenance note

If SongSelect changes their HTML structure, update the bookmarklet DOM selectors in resources/js/bookmarklet/ccli-import.ts (or the inline JS in BookmarkletController.php). The server-side parser (CcliPasteParser.php) is independent of SongSelect's HTML — it only parses the plain-text lyrics format.

---

KeyVisual & Background

Each service export can carry a key-visual image (shown as a standalone fallback slide) and a background image (rendered as a media layer behind every song/sermon slide).

Resolution is lazy and happens at export time:

1. Per-service column (key_visual_filename / background_filename on the services table)
2. Global default from Settings (current_key_visual / current_background)
3. None (slide omitted / no background layer)

When a service is finalized, the resolved filenames are snapshotted into the per-service columns so the export is stable even if the global default changes later.

Export naming contract (portable bundles)

On export the key-visual and background images are embedded into the archive under fixed names and referenced bundle-relative inside the .pro file (never by absolute path), so exports are portable to the presenter PC:

Image	Embedded filename + .pro reference
Key-visual	KEY_VISUAL.jpg
Background	BACKGROUND.jpg

The fixed names are defined as ServiceImageResolver::KEY_VISUAL_EXPORT_NAME / ServiceImageResolver::BACKGROUND_EXPORT_NAME. The slideData['background'] array carries 'path' => '<FIXED_NAME>' with 'bundleRelative' => true; the image bytes are added to the archive's embedded/media files under that same name (deduplicated per archive). Applies to .proplaylist (PlaylistExportService) and .probundle (ProBundleExportService). The bare single-song .pro download has no service context and carries no background.

Key files

File	Purpose
app/Services/ServiceImageResolver.php	Lazy resolution: per-service column → global Setting → null
app/Http/Controllers/ServiceImageController.php	POST /services/{service}/key-visual + POST /services/{service}/background; scope dialog ("Nur für diesen Service" / "Als Standard setzen")
app/Services/FileConversionService.php	Added convertImageCover() for COVER-mode 1920×1080 conversion
app/Services/PlaylistExportService.php	Injects keyvisual fallback slides and sermon sequence (keyvisual → nametag → slides)
app/Services/ProExportService.php	Adds background media layer on song/sermon slides
resources/js/Components/ServiceImagePanel.vue	Upload panel with scope dialog; used on the service Edit page
resources/js/Pages/Services/Edit.vue	Image panels rendered at the top of the edit form
resources/js/Pages/Settings.vue	Global default key-visual and background fields

Settings keys

Key	Purpose
current_key_visual	Global default key-visual filename
current_background	Global default background filename

Routes

Method	Route	Name
POST	/services/{service}/key-visual	services.key-visual.store
POST	/services/{service}/background	services.background.store

Parser package changes (commit 582ef85)

• New slideData['background'] contract: background-layer media action on any slide
• New slideData['imageOnly'] flag: image-only slide (no text layer)
• New Slide read accessors: hasBackgroundMedia(), getBackgroundMediaUrl(), getBackgroundMediaFormat()

---

NameTag (Namenseinblender)

A name-tag slide is injected into the sermon sequence (between the key-visual and the sermon slides) to display the moderator and/or preacher name on screen.

The slide is only generated when the Namenseinblender macro is fully configured in Settings. It renders plain white text and optionally triggers a ProPresenter macro.

Name resolution order

1. moderator_name / preacher_name_override columns on the services table (manual override set via Edit form)
2. Responsible person from the CTS responsible JSON field matching the configured role
3. None (slide omitted)

Key files

File	Purpose
app/Services/NameTagResolver.php	Resolves moderator/preacher name: responsible JSON → CTS role → manual override
app/Services/NameTagSlideBuilder.php	Builds slideData for the nametag slide (plain white text + optional macro)
app/Http/Controllers/ServiceController.php	PATCH /services/{service}/name-overrides — saves manual name overrides
resources/js/Pages/Services/Edit.vue	Name override input fields in the edit form
resources/js/Pages/Settings.vue	Namenseinblender submenu with macro name/UUID/collection fields

Settings keys

Key	Purpose
namenseinblender_macro_name	ProPresenter macro name
namenseinblender_macro_uuid	ProPresenter macro UUID
namenseinblender_macro_collection_name	Macro collection name
namenseinblender_macro_collection_uuid	Macro collection UUID

Routes

Method	Route	Name
PATCH	/services/{service}/name-overrides	services.name-overrides.update

---

Repository Structure

Two git repositories, both local (no remote):

Repo	Path	Branch	Purpose
pp-planer	/Users/thorsten/AI/pp-planer	cts-presenter-app	Laravel app (main codebase)
propresenter	/Users/thorsten/AI/propresenter	propresenter-parser	ProPresenter .pro/.proplaylist parser (composer path dependency)

The parser is linked via composer.json path repository: "url": "../propresenter".

Build, Test, Lint Commands

pp-planer (Laravel App)

Local dev runs in DDEV (Docker). Site URL: https://pp-planer.ddev.site.

# Easy onboarding wrappers (no DDEV knowledge required):
./start_dev.sh          # ddev start + spawns dev workers in background
./stop_dev.sh           # stops workers and DDEV (use --keep-ddev to leave DDEV running)

# Or use DDEV directly:
ddev start              # composer install, key:generate, migrate, npm install, npm run build
ddev dev                # queue + log tail + vite HMR (foreground)
ddev stop               # stop the project

# Open a shell inside the web container
ddev ssh

# Frontend
ddev npm run build
ddev npm run dev

# Run ALL PHP tests (clears config cache first)
ddev composer test
ddev exec php artisan test

# Single test file
ddev exec php artisan test tests/Feature/ServiceControllerTest.php

# Single test method
ddev exec php artisan test --filter=test_service_kann_abgeschlossen_werden

# Test suite
ddev exec php artisan test --testsuite=Feature
ddev exec php artisan test --testsuite=Unit

# PHP formatting (Laravel Pint, default preset — no pint.json)
ddev exec ./vendor/bin/pint
ddev exec ./vendor/bin/pint --test   # check only

# E2E tests (requires `ddev start` running; baseURL is https://pp-planer.ddev.site)
npx playwright test
npx playwright test tests/e2e/service-list.spec.ts

# Migrations
ddev exec php artisan migrate

propresenter (Parser Module)

cd /Users/thorsten/AI/propresenter

# Run all tests (230 tests)
./vendor/bin/phpunit

# Single test file
./vendor/bin/phpunit tests/ProFileReaderTest.php

Architecture

pp-planer/
  app/Http/Controllers/     # Inertia controllers (Inertia::render or JSON)
  app/Models/               # Eloquent models (factories in database/factories/)
  app/Services/             # Business logic (ChurchToolsService, ProExportService, etc.)
  app/Jobs/                 # Queue jobs (PowerPoint conversion)
  app/Mail/                 # Mailable classes (German content)
  resources/js/Pages/       # Vue page components (mapped via Inertia::render)
  resources/js/Components/  # Reusable Vue components
  resources/js/Composables/ # Vue composables (useAutoSave)
  resources/js/Layouts/     # AuthenticatedLayout, GuestLayout
  tests/Feature/            # Pest v4 / PHPUnit feature tests
  tests/e2e/                # Playwright browser tests (TypeScript)

propresenter/
  src/                      # ProFileReader, ProFileGenerator, ProPlaylistGenerator, Song, Group, Slide, Arrangement
  tests/                    # PHPUnit 11 tests with #[Test] attributes
  ref/                      # .pro fixture files for testing

Code Style -- PHP

• Formatter: Laravel Pint (default Laravel preset, no custom config)
• Imports: Fully qualified, one per line, alphabetical. App\ first, then Illuminate, then external.
• Constructors: Promoted properties with private readonly. Empty body: {} on same line.

  public function __construct(
      private readonly SongMatchingService $songMatchingService,
  ) {}
  

• Return types: Always present. Use union types for multiple returns: Response|JsonResponse.
• String concat: No spaces around . operator: 'Fehler: '.$e->getMessage()
• Null safety: Nullsafe ?-> and null coalescing ??. Never suppress with @.
• Models: $fillable array (never $guarded). casts() method (never $casts property). Typed relationship returns (HasMany, BelongsTo). Attribute::get() for computed accessors.
• Migrations: Anonymous class: return new class extends Migration {. Methods: up(): void, down(): void.
• Error messages: German, Du-form. Flash: ->with('success', '...'). JSON: 'message' key.
• Validation: Inline $request->validate([...]) with Rule::in() for enums.
• Transactions: DB::transaction(function () use (...): void { ... }) for multi-step writes.
• Constants: private const NAME = [...] for fixed value sets.

Code Style -- Vue / Frontend

• Vue 3 Composition API only. Always <script setup>. No Options API.
• Props: defineProps({ name: { type: Type, default: value } })
• Emits: defineEmits(['kebab-case-event'])
• Model: defineModel({ type: String, required: true }) for v-model binding.
• Imports: @/ alias for resources/js/. Vue from 'vue', Inertia from '@inertiajs/vue3'.
• Functions: Prefer function name() {} declarations (not const name = () => {}).
• State: ref() for reactive, computed() for derived, watch() for side effects.
• Routing: route('name', params) via Ziggy. router.post/get/delete from Inertia with { preserveScroll: true }.
• Styling: Tailwind CSS v4 utility classes inline. <style scoped> only when necessary (e.g. drag-and-drop).
• Test IDs: data-testid="..." on interactive elements for Playwright.
• All UI text: German, Du-form (not Sie).

Code Style -- Tests

PHP Tests (Pest v4 + PHPUnit)

Both styles are used:

• Function-based Pest: test('snake_case german description', function () { ... }); with beforeEach
• Class-based: final class NameTest extends TestCase { use RefreshDatabase; public function test_snake_case(): void {} }
• Auth: $this->actingAs(User::factory()->create())
• Vite: Call $this->withoutVite() before Inertia page render tests
• Time: Carbon::setTestNow('2026-03-01 10:00:00') for deterministic dates
• Inertia assertions: $response->assertInertia(fn ($page) => $page->component('...')->has('...')->where('...'))
• DB: In-memory SQLite (phpunit.xml: DB_CONNECTION=sqlite, DB_DATABASE=:memory:)
• Helper functions: Define at file level for shared test setup (e.g. function makePngUpload(...))
• Storage: Storage::fake('public') in beforeEach for file upload tests

ProPresenter Parser Tests (PHPUnit 11)

• Uses #[Test] attribute (not test_ prefix)
• setUp()/tearDown() for temp directory management
• Fixtures in ref/ directory, loaded via dirname(__DIR__, 2).'/ref/...'
• Strict mode: failOnRisky, failOnWarning, beStrictAboutOutputDuringTests

E2E Tests (Playwright)

• TypeScript in tests/e2e/, baseURL https://pp-planer.ddev.site (HTTPS, ignoreHTTPSErrors: true set in playwright.config.ts)
• Auth via auth.setup.ts (XSRF token + /dev-login endpoint, saves state to .auth/user.json)
• Selectors: page.getByTestId('...'), page.getByText('...'), page.getByRole('...')
• German text assertions: await expect(page.getByText('Mit ChurchTools anmelden')).toBeVisible()

Key Constraints

• CTS API is READ-ONLY -- never write/modify data via ChurchTools API
• Immediate persistence -- all user actions save instantly (no separate save button)
• German locale -- APP_LOCALE=de, all UI text German Du-form
• File uploads -- images convert to JPG 1920x1080 (maintain aspect, no crop); PPT/PPTX to multiple JPGs
• Named routes -- all routes have names, use route('name') everywhere
• No type suppression -- never use as any, @ts-ignore, @ts-expect-error in frontend
• SoftDeletes -- used on Song and Slide models; use whereNull('deleted_at') in manual queries