GoBD Logbook

Standalone logbook app aiming to be compliant with GoDB.

Goal

Offer a way for smaller companies to have a compliant logbook.

• Customers, projects, and invoices are read from InvoiceNinja and cached locally.
• Business trips can be manually written back as InvoiceNinja expenses.
• Vehicles, trips, photos, audit trail, period locks, and exports remain in the logbook.

Stack

• Laravel API
• Laravel Passport API Auth
• Spatie Laravel-Permission (RBAC)
• React/Ionic PWA shell
• Docker Compose with MariaDB and Redis
• Evidence-Exports as CSV/PDF/ZIP
• Restic/Borg-compatible backup concept

Key Features

• GoBD-Compliant Logging: Cryptographically secured audit trails, support for draft vs. finalized trips, and strict immutability rules.
• Tenant-aware Role-Based Access Control: Users can belong to multiple companies with a separate role per tenant; global super-admin access is kept separate from normal tenant memberships.
• InvoiceNinja Sync: Automated synchronization of customers and projects, with the ability to write back business trips as expenses.
• Mobile-Ready PWA: Modular React/Ionic frontend with customizable global themes, responsive layouts, and offline capabilities.
• Human-Reviewed Odometer OCR: Odometer photos can be analyzed for candidate readings, but users must inspect the crop/original image, correct if needed, and explicitly accept the value.
• Reliable Evidence Handling: Trip photos and expense receipts retain their original filename, MIME type, size and SHA-256 fingerprint. Admins can inspect protected previews in the dedicated Nachweise area without loading all binaries at once.
• Data Integrity: Soft deletions and validation workflows ensure historical records are preserved perfectly for tax audits.

Quick Start

Recommended: Dev Container

Install Docker and a Dev Containers-capable editor, then open this repository and choose Reopen in Container. The Dev Container starts the full Compose stack and provides PHP, Composer, Node and pnpm inside /workspace; nothing needs to be installed on the host. Dependencies are stored in Docker volumes.

Copy .env.example to .env before the first start and set the required passwords/admin values. The initial container setup installs dependencies. From its terminal, use commands directly, for example php artisan test or cd client && pnpm run lint.

To add editor- or agent-specific, local instructions without committing them, edit .devcontainer/docker-compose.local.yml after its first creation. Its tracked .example documents a read-only AGENT_CONFIG_DIR mount.

Docker Compose fallback

cp .env.example .env
# Set LOGBOOK_SUPER_ADMIN_NAME, LOGBOOK_SUPER_ADMIN_EMAIL and LOGBOOK_SUPER_ADMIN_PASSWORD in .env
docker compose up -d --build
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate
docker compose exec app php artisan app:ensure-bootstrap

Docker user mapping

If you run the containers on your host you may encounter file permission issues. The example .env contains WWWUSER and WWWGROUP (defaults: 1000). Set these in your .env to match your host user's UID/GID so files created by the containers have matching ownership. The Dockerfiles and docker-compose.yml pass these values as build args and set the service user accordingly.

The Dev Container is the reference environment because no PHP/Composer/Node is assumed on the host. Direct Docker Compose remains available as a fallback. By default, the stack starts without Traefik and binds ports directly to the host (8088 for API, 5178 for frontend, 8025 für Mailpit Web-UI).

Mail-Testing (Mailpit)

Die lokale Entwicklungsumgebung beinhaltet Mailpit als Test-Mail-Server:

• Web-UI: http://localhost:8025 (oder mail.<LOGBOOK_HOST> bei Traefik) zur Inspektion aller versendeten E-Mails
• SMTP-Port: 1025 (Container-intern über mailpit:1025)
• Alle versendeten System- und Erinnerungs-Mails (z. B. logbook:send-reminders, GoBD-Warnungen, Test-Mails) werden lokal abgefangen und können visuell geprüft werden.

Traefik Setup

If you are using Traefik as a reverse proxy:

1. Copy the override file: cp docker-compose.override.yml.example docker-compose.override.yml
2. Ensure you have a Traefik instance running and the external network exists (docker network create traefik-network).
3. Run docker compose up -d.

Security Tooling

The project has comprehensive static analysis and security scanning built-in. Since no local PHP/Composer/Node is assumed on the host, all tools can be run via Docker containers.

PHP Tooling: Run these commands via the app container:

docker compose exec app composer run psalm        # Static analysis
docker compose exec app composer run psalm:taint  # Taint analysis for security
docker compose exec app composer run phpstan      # Larastan analysis
docker compose exec app composer run phpcs        # Code style & security audit
docker compose exec app composer run security     # Runs all security checks

JS Tooling: Run these commands via the frontend container:

docker compose exec frontend pnpm run lint        # ESLint with security rules
docker compose exec frontend pnpm run format      # Prettier formatting

Git Hooks: To prevent accidental secret commits and formatting failures, install the Git hooks. The installer adds a Betterleaks pre-commit hook and a formatting pre-push hook that runs Pint and Prettier checks before CI does. By default, the script will try to use the betterleaks docker image if you don't have it installed natively. You can also explicitly force it to use Docker:

USE_DOCKER=1 ./scripts/install-hooks.sh

CI/CD Pipeline

The project's primary CI/CD engine is GitLab CI (.gitlab-ci.yml), executed 24/7 on a dedicated server runner with the Docker executor:

• Tier 1 (Branch Pushes): Fast developer loop (< 45s) running Laravel Pint, Prettier, OpenAPI validation, ShellCheck, PHPUnit, and Vitest.
• Tier 2 (Merge Requests): Quality & security gate running Larastan/PHPStan, Psalm taint analysis, ESLint security rules, PHPCS audit, Gitleaks secret detection, and dependency audits.
• Tier 3 (Scheduled & Releases): Weekly Trivy CVE scans, Syft SPDX SBOM generation, and production Docker container builds.
• Mirror Sync: GitLab CI automatically reports verified commit status back to the public mirror on OpenCommit via the Forgejo status API.

Legacy Forgejo Actions workflows remain in .forgejo/workflows/ with automatic triggers deactivated to avoid runner contention, but are available for manual execution.

See docs/security-ci.md for the complete pipeline reference, runner setup, and tool catalogue.

The bootstrap command creates the super-admin from .env only. Set LOGBOOK_SUPER_ADMIN_NAME, LOGBOOK_SUPER_ADMIN_EMAIL, and LOGBOOK_SUPER_ADMIN_PASSWORD before first boot; there are no built-in admin credentials. Demo-vehicle, Demo-trips and Demo-InvoiceNinja-references can be disabled with LOGBOOK_SEED_DEMO=false.

InvoiceNinja credentials are stored in the Sync tab. Multiple connections can be created, e.g. local-test and live; the active record is used for syncing. The API token is stored encrypted in the invoice_ninja_connections table.

Documentation

The maintained narrative documentation is currently written in German. Future English translations belong in docs/en/ with the same relative file name; the documentation hub & language guide describes the translation and synchronization convention.

Project Documentation

• Documentation Hub & Language Guide - Language policy, translation workflow, and documentation overview.

• Security & CI/CD Pipeline - Pipeline stages, trigger strategy, runner setup, and tool catalogue.

• Tax Compliance Report - GoBD compliance mechanisms.

• Audit & Immutability Specifications - Tamper-proofing details.

• InvoiceNinja Integration - REST API coupling details.

• Odometer OCR Review Workflow - Photo analysis, visual review, correction, and testing notes.

• Nachweise & Medienverwaltung - Upload, storage, inherited odometer evidence, protected previews, and admin review.

• Backup and Restore Guide - Disaster recovery guidelines.

• Production Deployment - Secret-file based deployment, ports, and first super-admin.

• API Reference - Endpoint sketches.

• Developer Onboarding Guide - Local setup, tests, and security scans.

• Administration & Optional Features - Admin navigation, tenant-scoped settings, ERP, allowances, locations, and display preferences.

• Onboarding für Nutzerinnen und Nutzer - Kurzanleitung für Fahrten, Spesen, Kilometerlücken und die Ersteinrichtung.

• Multi-Tenancy & RBAC - User identities, per-company memberships/roles, system tenant, and admin boundaries.

• Features & Test Coverage Report - Map of system features, API routes, and test coverage.

• Project Feature Roadmap - Multi-tenant isolation and ACL specs.

• Architecture Contract - Binding headless API, feature-gate, client-storage, and modularization decisions.

• Frontend Modularization Roadmap - PR sequence, acceptance criteria, merge gates, and implementation hand-off.

Disclaimer

The app provides technical evidence for a revision-proof logbook. The final tax acceptance must be made by a tax advisor/payroll office.