Theodor-Springmann-Stiftung/lenz-web
1
0
Fork 0
mirror of https://github.com/Theodor-Springmann-Stiftung/lenz-web.git synced 2025-10-28 08:45:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
lenz-web/CLAUDE.md
Simon Martens 9bfebe5828 CLAUDE
2025-09-17 11:38:18 +02:00

6.6 KiB
Raw Permalink Blame History

CLAUDE.md

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

Project Overview

Lenz-Web is a Go web application that serves digitized historical letters. It's built with:

  • Go 1.24 using Fiber web framework
  • Custom templating engine with hot reload for development
  • Git-based content management (clones/updates from remote repository)
  • XML parsing for letter metadata and content
  • Static asset serving with compression and ETags

Development Commands

Build and Run

go build                    # Build the application
./lenz-web                  # Run the built binary
go run .                    # Build and run directly

Docker

docker-compose up           # Run with Docker (exposes port 8085)
docker build .              # Build Docker image

Testing

The project does not currently have automated tests. Check for *_test.go files before assuming test frameworks.

Architecture

Main Application Flow (lenz.go:30-69)

  1. Loads configuration from JSON files and environment variables
  2. Clones/opens Git repository containing letter data
  3. Parses XML models from the repository
  4. Sets up templating engine with custom functions
  5. Configures Fiber web server with routes and middleware
  6. In debug mode, enables file watchers for hot reload

Core Components

Configuration (config/)

  • config.go: Configuration management with JSON files, environment variables, and defaults
  • Uses KGPZ_ prefix for environment variables
  • Default config file: config.dev.json

Templating (templating/)

  • Custom template engine with layout and route registries
  • WebSocket-based hot reload in debug mode
  • Template functions for XML data processing

Controllers (controllers/)

  • Route handlers for web endpoints
  • routes.go: Route registration and URL constants
  • Main routes: /, /briefe, /brief/:letter, static pages

XML Models (xmlmodels/)

  • Parses historical letter data from XML files
  • Provides template functions for data access
  • Core models: Library, Letter, Traditions, References

File Watching (watcher.go)

  • Custom file watcher with debouncing (300ms)
  • Two watch modes:
    • REFRESH_CHANGES: ./views/assets (clears cache, sends refresh signal)
    • RESET_CHANGES: ./views/layouts, ./views/routes (clears cache, reloads templates)

Key Directories

  • views/: Frontend templates, layouts, and static assets
  • helpers/: Utility functions and middleware
  • server/: Fiber server configuration and caching
  • git/: Git repository management

Configuration

Configuration is loaded in order: JSON files → environment variables → defaults

Key settings:

  • debug: Enables hot reload and verbose logging
  • git_url: Repository URL for letter content
  • base_dir: Cache directory (default: _cache)
  • port: Server port (default: 8085)
  • webhook_secret: GitHub webhook integration

Environment variables use KGPZ_ prefix (e.g., KGPZ_DEBUG=true).

Views Directory Structure

The views/ directory contains all frontend templates and assets:

views/
├── assets/           # Static files (CSS, JS, fonts, images)
├── layouts/          # Base layout templates
│   ├── components/   # Reusable layout components (_header, _footer, _menu, etc.)
│   └── default/      # Default layout (root.gohtml)
└── routes/           # Page-specific templates
    ├── brief/        # Individual letter view (head.gohtml, body.gohtml)
    ├── briefe/       # Letter listing view
    ├── components/   # Page components (_letterhead, _letterlist, _lettertrad)
    ├── datenschutz/  # Privacy page
    ├── edition/      # Edition info pages
    └── kontakt/      # Contact page

Template System Architecture

Build-Time Embedding vs Development

  • Production: Templates embedded via //go:embed directives in views/embed.go
  • Development: Direct filesystem access via views/embed_dev.go (when built with -tags dev)
  • File watchers enable hot reload in debug mode

Template Structure Each route directory contains:

  • head.gohtml: <head> section content for the page
  • body.gohtml: Main page content

Layout System (templating/engine.go)

  • Base layout: views/layouts/default/root.gohtml
  • Uses Go template blocks: {{ block "head" . }}, {{ block "body" . }}, etc.
  • Layout registry loads and caches layouts with template functions
  • Template registry loads route-specific templates

Template Functions Available Core functions (templating/engine.go:118-131):

  • Safe: Render HTML without escaping
  • Today: Current date
  • GetMonth: Month name from number
  • Minus: Subtraction for template math

XML Data Functions (added from xmlmodels/library.go):

  • Person: Get person data by reference ID
  • Place: Get location data by reference ID
  • ParseGeneric: Parse and render letter text with markup

Template Data Flow

  1. Controllers pass fiber.Map data to templates
  2. Engine merges with GlobalData (debug flags, etc.)
  3. Layout loaded and cloned from registry
  4. Route templates added to layout clone
  5. Combined template executed with merged data

Hot Reload System

  • WebSocket server on port 9000 for live reload in debug mode
  • File watchers trigger different actions:
    • ./views/assets changes: Clear cache + browser refresh signal
    • ./views/layouts, ./views/routes changes: Clear cache + reload templates
  • 300ms debounce to prevent excessive reloads

Working with Templates

Template Syntax

  • Standard Go template syntax with custom functions
  • Variables: {{ $model := . }} for cleaner references
  • Conditionals: {{ if .isDev }}...{{ end }}
  • Loops: {{ range $item := .items }}...{{ end }}
  • Components: {{ template "_letterhead" .meta }}

Debugging Templates

  • Enable debug mode in config: "debug": true
  • Templates reload automatically on file changes
  • Browser refreshes automatically via WebSocket
  • Console shows reload notifications

Letter Data Templates Letter pages have access to rich XML data:

  • .meta: Letter metadata (dates, persons, places)
  • .text: Parsed letter content with markup
  • .prev/.next: Navigation to adjacent letters
  • Navigation uses custom functions like Person and Place to resolve references

Development Notes

  • File watchers only active in debug mode
  • Templates are cached; use debug mode for development
  • Static assets served with compression and ETags
  • Git repository is cloned to base_dir/git_path on startup
  • WebSocket endpoint available for live reload in debug mode
  • Template files use .gohtml extension for proper syntax highlighting