mirror of
https://github.com/Theodor-Springmann-Stiftung/kgpz_web.git
synced 2025-10-30 01:25:30 +00:00
231 lines
9.4 KiB
Markdown
231 lines
9.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
KGPZ Web is a Go-based web application for serving historical newspaper data from the KGPZ (Königsberger Gelehrte und Politische Zeitung) digital archive. The application combines server-rendered HTML with HTMX for progressive enhancement, providing a modern web interface for browsing historical content.
|
|
|
|
## Architecture
|
|
|
|
The application follows a modular Go architecture:
|
|
|
|
- **Main Application**: `kgpz_web.go` - Entry point and application lifecycle management
|
|
- **App Core**: `app/kgpz.go` - Core business logic and data processing
|
|
- **Controllers**: Route handlers for different content types (issues, agents, places, categories, search)
|
|
- **View Models**: Data structures for template rendering with pre-processed business logic (`viewmodels/`)
|
|
- **XML Models**: Data structures for parsing source XML files (`xmlmodels/`)
|
|
- **Providers**: External service integrations (Git, GND, XML parsing, search)
|
|
- **Templating**: Custom template engine with Go template integration and helper functions
|
|
- **Views**: Frontend assets and templates in `views/` directory
|
|
|
|
### Key Components
|
|
|
|
1. **Data Sources**: XML files from Git repository containing historical newspaper metadata
|
|
2. **Search**: Full-text search powered by Bleve search engine
|
|
3. **External Integrations**: GND (Gemeinsame Normdatei) for person metadata, Geonames for place data
|
|
4. **Template System**: Custom engine supporting layouts and partials with embedded filesystem and helper functions
|
|
|
|
## Development Commands
|
|
|
|
### Go Backend
|
|
```bash
|
|
# Run the application in development mode
|
|
go run kgpz_web.go
|
|
|
|
# Build the application
|
|
go build -o kgpz_web kgpz_web.go
|
|
|
|
# Run tests
|
|
go test ./helpers/xsdtime/
|
|
|
|
# Format code
|
|
go fmt ./...
|
|
|
|
# Check for issues
|
|
go vet ./...
|
|
```
|
|
|
|
### Frontend Assets (from views/ directory)
|
|
```bash
|
|
cd views/
|
|
|
|
# Development server with hot reloading
|
|
npm run dev
|
|
|
|
# Build production assets
|
|
npm run build
|
|
|
|
# Build CSS with Tailwind
|
|
npm run tailwind
|
|
|
|
# Build CSS with PostCSS
|
|
npm run css
|
|
|
|
# Preview built assets
|
|
npm run preview
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The application uses JSON configuration files:
|
|
- `config.dev.json` - Development configuration (if exists)
|
|
- `config.json` - Default configuration (fallback)
|
|
|
|
Key configuration options:
|
|
- `git_url`: Source repository URL for data
|
|
- `git_branch`: Branch to use for data
|
|
- `webhook_endpoint`: GitHub webhook endpoint for auto-updates
|
|
- `debug`: Enable debug mode and logging
|
|
- `watch`: Enable file watching for template hot-reloading
|
|
|
|
## Data Flow
|
|
|
|
1. **Startup**: Application clones/pulls Git repository with XML data
|
|
2. **Parsing**: XML files parsed into structured models (agents, places, works, issues)
|
|
3. **Enrichment**: External APIs (GND, Geonames) enrich metadata
|
|
4. **Indexing**: Full-text search index built using Bleve
|
|
5. **Serving**: HTTP server serves templated content with HTMX interactions
|
|
|
|
## Key Dependencies
|
|
|
|
- **Web Framework**: Fiber (high-performance HTTP framework)
|
|
- **Search**: Bleve (full-text search engine)
|
|
- **Git Operations**: go-git (Git repository operations)
|
|
- **Frontend**: HTMX + Tailwind CSS for progressive enhancement
|
|
- **Build Tools**: Vite for asset bundling, PostCSS for CSS processing
|
|
|
|
## Template Structure
|
|
|
|
Templates are embedded in the binary:
|
|
- **Layouts**: `views/layouts/` - Base page structures
|
|
- **Routes**: `views/routes/` - Page-specific templates
|
|
- **Assets**: `views/assets/` - Compiled CSS and static files
|
|
|
|
The template system supports nested layouts and automatic reloading in development mode when `watch: true` is enabled.
|
|
|
|
## Views Directory Structure
|
|
|
|
The `views/` directory contains all frontend templates, assets, and build configuration:
|
|
|
|
### Directory Layout
|
|
```
|
|
views/
|
|
├── layouts/ # Base templates and layouts
|
|
│ ├── components/ # Shared layout components (_header, _footer, _menu)
|
|
│ └── default/ # Default layout (root.gohtml)
|
|
├── routes/ # Page-specific templates
|
|
│ ├── akteure/ # Agents/People pages (body.gohtml, head.gohtml)
|
|
│ ├── ausgabe/ # Issue pages with components
|
|
│ │ └── components/ # Issue-specific components (_inhaltsverzeichnis, _bilder, etc.)
|
|
│ ├── components/ # Shared route components (_akteur.gohtml)
|
|
│ ├── datenschutz/ # Privacy policy
|
|
│ ├── edition/ # Edition pages
|
|
│ ├── kategorie/ # Category pages
|
|
│ ├── kontakt/ # Contact pages
|
|
│ ├── ort/ # Places pages
|
|
│ ├── search/ # Search pages
|
|
│ └── zitation/ # Citation pages
|
|
├── assets/ # Compiled output assets
|
|
│ ├── css/ # Compiled CSS files
|
|
│ ├── js/ # JavaScript libraries and compiled scripts
|
|
│ ├── fonts/ # Font files
|
|
│ ├── logo/ # Logo and favicon files
|
|
│ └── xslt/ # XSLT transformation files
|
|
├── public/ # Static public assets
|
|
├── transform/ # Source files for build process
|
|
│ ├── main.js # Main JavaScript entry point
|
|
│ └── site.css # Source CSS with Tailwind directives
|
|
└── node_modules/ # NPM dependencies
|
|
```
|
|
|
|
### Template System
|
|
|
|
**Layout Templates** (`layouts/`):
|
|
- `default/root.gohtml`: Base HTML structure with head, HTMX, Alpine.js setup
|
|
- `components/_header.gohtml`: Site header with navigation
|
|
- `components/_footer.gohtml`: Site footer
|
|
- `components/_menu.gohtml`: Main navigation menu
|
|
|
|
**Route Templates** (`routes/`):
|
|
Each route has dedicated `head.gohtml` and `body.gohtml` files following Go template conventions:
|
|
- Pages use German naming: `akteure` (agents), `ausgabe` (issues), `ort` (places), etc.
|
|
- Component partials prefixed with `_` (e.g., `_akteur.gohtml`, `_inhaltsverzeichnis.gohtml`)
|
|
- HTMX-powered interactions for dynamic content loading
|
|
|
|
**Template Features**:
|
|
- Go template syntax with custom functions from `templating/engine.go`
|
|
- Block template inheritance system
|
|
- HTMX integration for progressive enhancement
|
|
- Conditional development/production asset loading
|
|
- Template helper functions for UI components (PageIcon, BeilagePageIcon)
|
|
- Pre-processed view models to minimize template logic
|
|
|
|
### Frontend Assets
|
|
|
|
**JavaScript Stack**:
|
|
- **HTMX**: Core interactivity and AJAX requests
|
|
- **Alpine.js**: Lightweight reactivity for UI components
|
|
- **Custom Extensions**: HTMX plugins for response targets, client-side templates, loading states
|
|
- **Build Tool**: Vite for module bundling and development server
|
|
|
|
**CSS Stack**:
|
|
- **Tailwind CSS v4**: Utility-first CSS framework
|
|
- **PostCSS**: CSS processing pipeline
|
|
- **RemixIcon**: Icon font library
|
|
- **Custom Fonts**: Typography setup in `assets/css/fonts.css`
|
|
|
|
**Build Process**:
|
|
- **Source**: `transform/main.js` and `transform/site.css`
|
|
- **Output**: Compiled to `assets/scripts.js` and `assets/style.css`
|
|
- **Vite Config**: Production build targeting ES modules
|
|
- **PostCSS Config**: Tailwind CSS processing
|
|
|
|
### Asset Loading Strategy
|
|
|
|
The root template conditionally loads assets based on environment:
|
|
- Development: Uses dev favicon, enables hot reloading
|
|
- Production: Optimized assets, production favicon
|
|
- Module imports: ES6 modules with `setup()` function from compiled scripts
|
|
- Deferred loading: HTMX and Alpine.js loaded with `defer` attribute
|
|
|
|
## Template Architecture & Best Practices
|
|
|
|
### View Model Philosophy
|
|
The application follows a **logic-in-Go, presentation-in-templates** approach:
|
|
|
|
- **View Models** (`viewmodels/issue_view.go`): Pre-process all business logic, calculations, and data transformations
|
|
- **Templates**: Focus purely on presentation using pre-calculated data
|
|
- **Helper Functions** (`templating/engine.go`): Reusable UI components and formatting
|
|
|
|
### Key View Model Features
|
|
- **Pre-calculated metadata**: Page icons, grid layouts, visibility flags
|
|
- **Grouped data structures**: Complex relationships resolved in Go
|
|
- **Template helpers**: `PageIcon()`, `BeilagePageIcon()` for consistent UI components
|
|
|
|
### Template Organization
|
|
**Ausgabe (Issue) Templates**:
|
|
- `body.gohtml`: Main layout structure with conditional rendering
|
|
- `components/_inhaltsverzeichnis.gohtml`: Table of contents with pre-processed page data
|
|
- `components/_newspaper_layout.gohtml`: Newspaper page grid with absolute positioning
|
|
- `components/_bilder.gohtml`: Simple image gallery fallback
|
|
- Interactive highlighting system with intersection observer and scroll detection
|
|
|
|
### JavaScript Integration
|
|
- **Progressive Enhancement**: HTMX + Alpine.js for interactivity
|
|
- **Real-time Highlighting**: Intersection Observer API with scroll fallback
|
|
- **Page Navigation**: Smooth scrolling with visibility detection
|
|
- **Responsive Design**: Mobile-optimized with proper touch interactions
|
|
|
|
## Development Workflow
|
|
|
|
1. Backend changes: Modify Go files, restart server
|
|
2. Template changes: Edit templates in `views/`, automatic reload if watching enabled
|
|
3. CSS changes: Run `npm run css` or `npm run tailwind` in views directory
|
|
4. JavaScript changes: Edit `transform/main.js`, run `npm run build`
|
|
5. Full rebuild: `go build` for backend, `npm run build` for frontend assets
|
|
|
|
### Adding New Template Logic
|
|
1. **First**: Add business logic to view models in Go
|
|
2. **Second**: Create reusable template helper functions if needed
|
|
3. **Last**: Use pre-processed data in templates for presentation only |