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.

GoBD Compliance & Tamper-Proof Architecture

The application meets strict GoBD requirements (German tax compliance without mandatory cloud WORM) through four architectural pillars:

1. Cryptographic Integrity: SHA-256 hashing for all binaries (photos, receipts, PDFs) and chained event hashes (previous_hash Merkle chain) with an offline verification script (verify.py / validate.py).
2. Status Logic & Period Locks: Separation of Draft, Confirmed, and Locked periods. Closed periods cannot be mutated; corrections strictly follow the accounting reversal principle (Storno / cancel via PeriodAmendmentController).
3. Append-Only Audit Trail: audit_events and record_revisions protected by native database triggers (SIGNAL 45000 blocking all UPDATE/DELETE attempts).
4. Internal Control System (IKS) & Least Privilege: Dedicated roles (driver, admin, auditor). The database user can be restricted to SELECT, INSERT on immutable tables via php artisan evidence:runtime-grants.

👉 See Tax Compliance Report (DE) · Tax Compliance Report (EN) · Audit Specifications for full architecture details and diagrams.

Internationalization status / Internationalisierungsstatus

English disclaimer on translation status

The interface currently supports German, English, Turkish, Arabic, Polish and Spanish. Most non-German interface texts are machine- or AI-translated and have not yet received professional native-language review. They are therefore suitable for evaluation and day-to-day use with appropriate care, but should not yet be treated as linguistically verified product translations. The translation status does not change the application's technical data-protection measures. It is not, however, a legal assessment or certification of GDPR compliance. Separately, official tax and tax-advisor exports are generated in German when GoBD tax-compliance mode is active. We welcome native speakers, tax professionals and language reviewers who would like to help review and improve individual languages. At present the project is maintained by a single developer, and community review is the fastest path to offering reliably reviewed interfaces in additional languages.

Deutsche Hinweise zum Übersetzungsstatus

Die Oberfläche unterstützt derzeit Deutsch, Englisch, Türkisch, Arabisch, Polnisch und Spanisch. Die meisten nichtdeutschen UI-Texte sind maschinell bzw. KI-übersetzt und noch nicht professionell muttersprachlich geprüft. Sie eignen sich daher zur Erprobung und für die Nutzung mit angemessener Sorgfalt, gelten jedoch noch nicht als sprachlich verifizierte Produktübersetzungen. Der Übersetzungsstatus verändert die technischen Datenschutzmaßnahmen der Anwendung nicht. Er stellt jedoch keine rechtliche Bewertung oder Zertifizierung der DSGVO-Konformität dar. Davon getrennt werden amtliche Exporte und Exporte für Steuerberater bei aktivem GoBD-Steuerkonformitätsmodus auf Deutsch erstellt. Muttersprachler:innen, Steuerfachleute und Sprachprüfer:innen sind herzlich eingeladen, einzelne Sprachen fachlich zu prüfen und zu verbessern. Das Projekt wird derzeit von einem einzelnen Entwickler gepflegt; Community-Review ist der schnellste Weg zu verlässlich geprüften Oberflächen in weiteren Sprachen.

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 for Mailpit web UI).

Mail-Testing (Mailpit)

The local development environment includes Mailpit as a test mail server:

• Web UI: http://localhost:8025 (or mail.<LOGBOOK_HOST> with Traefik) to inspect all sent emails.
• SMTP Port: 1025 (container-internal via mailpit:1025).
• All sent system and reminder emails (e.g., logbook:send-reminders, GoBD warnings, test emails) are captured locally and can be visually verified.

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 pre-commit hook that auto-formats staged PHP and frontend files with Pint and Prettier, stages those formatting-only changes, and then runs the Betterleaks check. When a relevant frontend source, test, or dependency file is staged, it also runs the complete Vitest suite, so asynchronous test-teardown errors are caught before the commit is created. The pre-push hook remains a read-only Pint/Prettier safety net before CI does. This means formatting errors are normally corrected before the commit is created; no follow-up amend is needed. If a file is only partially staged, the hook stops without changing it so that unstaged hunks cannot accidentally enter the commit. 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/en/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 organized bilingually by ISO-639-1 language subdirectories: German authoritative documents reside in docs/de/, and English specifications and translations reside in docs/en/. The machine-readable OpenAPI 3.1 specification is maintained at docs/openapi.yaml. See the Documentation Hub (English Hub · Deutscher Hub) for translation and synchronization conventions.

Project Documentation

• Documentation Hub & Language Guide (English · Deutsch) - 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.
• Evidence & Media Management (Deutsch) - Upload, storage, inherited odometer evidence, protected previews, and admin review.
• S3-Archiv einrichten (Deutsch) - Hetzner provisioning, COMPLIANCE/GOVERNANCE, legal holds, provider acceptance and local SeaweedFS tests.
• Maps, Geocoding & Provider Pools (Deutsch) - Provider pools, limits, caching, map tiles, and tenant hierarchy.
• 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 (Deutsch) - Admin navigation, tenant-scoped settings, ERP, allowances, locations, and display preferences.
• User Onboarding Guide (Deutsch) - Quick start for trips, expenses, odometer gap handling, and initial setup.
• Multi-Tenancy & RBAC (Deutsch) - User identities, per-company memberships/roles, system tenant, and admin boundaries.
• Ionic UI Foundation (Deutsch) - Shared UI components, tokens, and mobile design rules.
• Mobile Route-Timeline UI (Deutsch) - Condensed mobile entry form concept and theme integration.
• Features & Test Coverage Report - Map of system features, API routes, and test coverage.
• Project Feature Roadmap - Multi-tenant isolation and ACL specs.
• Architecture Contract (Deutsch) - Binding headless API, feature-gate, client-storage, and modularization decisions.
• Frontend Modularization Roadmap (Deutsch) - 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.