actuel-inactuel/site/plugins/loop/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Structure

This is a Kirby CMS plugin that provides a feedback tool for web pages. The architecture consists of:

Backend (PHP):

• Kirby plugin structure with main entry point at index.php
• Core logic in src/App.php with database abstraction
• API routes in src/Routes.php for comment management
• Models in src/Models/ for Comment and Reply entities
• Database layer in src/Database.php

Frontend (Svelte):

• Svelte 5 component library in frontend/src/
• Builds to ES modules in assets/ directory
• Uses Vite for build process with custom element compilation
• State management via Svelte stores in frontend/src/store/

Development Commands

Frontend Development:

# Start development server
pnpm dev

# Build assets
pnpm build

# Type checking
pnpm --filter=frontend run check

PHP Development:

# Static analysis
vendor/bin/phpstan analyse

# PHP analysis level 8 with strict rules
# Configuration in phpstan.neon

Documentation: Use context7 to find out about Kirby CMS, Documentation for this plugin is placed in the docs/ folder.

Key Architecture Details

Plugin Integration:

• Auto-injects feedback component into all HTML pages via page.render:after hook
• Component snippet located at snippets/loop/app.php
• Requires authenticated users (see Middleware::auth())

API Endpoints:

• GET /loop/comments/{pageId} - Get comments for a specific page
• POST /loop/comment/new - Create new comment
• POST /loop/comment/reply - Reply to existing comment
• POST /loop/comment/resolve - Mark comment as resolved
• POST /loop/comment/unresolve - Mark comment as unresolved
• POST /loop/guest/name - Set guest name for non-authenticated users

Data Flow:

• Comments are tied to Kirby page ids
• Position tracking via CSS selectors and page coordinates
• Validation happens at model level before database operations

Translations

IMPORTANT: When adding new translatable text to the frontend:

1. Add translation key to PHP backend (index.php):

   'moinframe.loop.ui.component.key' => 'Default English text',
   

2. Add translation key to snippet (snippets/loop/app.php):

   'ui.component.key' => t('moinframe.loop.ui.component.key'),
   

3. Use translation in Svelte components:

   {t("ui.component.key", "Default fallback text")}
   

Translation Architecture:

• PHP translations defined in index.php under 'translations' key
• Frontend translations passed via snippets/loop/app.php
• Svelte components use t() function from store/translations.svelte.ts
• Always provide fallback text in components for development

Linting and Code Quality

• Biome for frontend linting (config in biome.json)
• PHPStan level 8 analysis with strict rules
• TypeScript checking via svelte-check