Pretix Check-in Client

Cross-platform check-in client for Pretix events. A Flutter-based application for high-performance guest check-in management, supporting multiple platforms and offline synchronization.

Features

• Cross-Platform: Native support for Windows, Linux, macOS, Android, iOS, and Web (WASM).
• Architecture Aware: First-class support for both x86_64 (Intel/AMD) and ARM64 (Apple Silicon, Snapdragon, Pine64).
• Secure by Design: Sensitive API keys and auth tokens are stored in the system's Secure Storage (Keychain, Keystore, or Secret Service).
• OTA Updates: Built-in update service that automatically detects new GitHub releases and launches target-specific installers.
• Offline First: Full local database synchronization with Pretix, allowing for seamless check-ins even with intermittent internet connectivity.
• Privacy Focused: Opt-in error tracking via Sentry.
• Hardware Integration: High-performance QR scanning on desktop (Windows/Linux) using custom frame processing.

Supported Platforms & Artifacts

Platform	Architecture	Distribution Format
Windows	x64, ARM64	Native Installer (.exe)
Linux	x64, ARM64	AppImage (.AppImage)
macOS	Universal (x64+ARM64)	Disk Image (.dmg)
Android	Universal	Android Package (.apk)
iOS	ARM64	iOS App Bundle (.ipa)
Web	-	WASM Deployment

Architecture & Design Patterns

This project follows Clean Architecture and MVVM (Model-View-ViewModel) design principles, ensuring a strict separation of concerns, testability, and maintainability. A detailed architectural breakdown is available in the Architecture Guide and the Offline Strategy Guide.

Below is a brief summary of how core frontend engineering concepts are implemented in this codebase:

State Management & Reactive Data Flow

State management is built on the Provider + ChangeNotifier pattern, establishing a clear and reactive data flow:

• Feature-scoped state: ViewModels (extending BaseViewModel in base_view_model.dart) manage UI-specific state, notifying views of updates without exposing native platform elements.
• Global reactive services: Global states (like authentication, themes, and screen lock) are managed by dedicated notifier singletons (e.g., AuthNotifier in auth_notifier.dart), exposing state changes reactively across the widget tree.
• Event Bus: Decoupled features communicate asynchronously via an event stream bus (SyncEvents in sync_events.dart).

API Integration & Service Layers

All network interactions are decoupled and abstracted into dedicated HTTP and service layers:

• API Client: Built on top of Dio, managing global interceptors, base configurations, and token validation (located in api_client.dart).
• Strictly Typed Routes: Endpoints are mapped to explicit request and response models (located in lib/src/data/api/routes/).
• Service Layer delegation: Business logic is entirely contained within dedicated service classes (e.g., OrderService or CheckinService). ViewModels consume these services instead of calling network operations directly, keeping components lightweight and testable.

Asynchronous Operations & Offline Synchronization

Managing loading indicators, network latency, and network loss is critical for high-concurrency door management:

• Loading states: Handled centrally within the BaseViewModel via an isLoading notifier state, preventing UI freezes during network operations.
• Offline queueing: If a network operation fails during check-in, the operation is queued locally in the database (failed_checkins table) and retried automatically once connectivity is restored, managed by FailedCheckinsHelper in failed_checkins_helper.dart.
• Atomic Operations: Local database writes are wrapped in Drift transactions to prevent partial sync anomalies.

Getting Started

Prerequisites

• Flutter SDK: >=3.44.0 <4.0.0
• Dart SDK: >=3.12.0 <4.0.0
• Platform Specifics:
  • Windows: Visual Studio 2022 + "Desktop development with C++"
  • Linux: clang, cmake, ninja-build, pkg-config, libgtk-3-dev, libsecret-1-dev
  • macOS / iOS: Xcode 15+ & CocoaPods

Installation & Setup

1. Clone the repository:

   git clone https://github.com/VzFaK/checkin.git

2. Install dependencies:

   flutter pub get

3. Apply default branding configurations (required to compile platform-specific files):

   APP_BRAND=oss dart run scripts/apply_branding.dart

4. Generate localized strings and local database access classes:

   flutter gen-l10n
   dart run build_runner build --delete-conflicting-outputs

5. Run the application:

   flutter run -d windows  # or linux, macos, ios, android, chrome

Running Tests

Verify code correctness by running the automated test suite:

flutter test

Building for Production

CI/CD (Recommended)

This project uses GitHub Actions for automated builds. Every push to main or a new tag triggers a multi-platform build pipeline that produces architecture-specific installers and AppImages.

Web Container Package

The Build Web Container workflow builds the Flutter web app with the repository Dockerfile and publishes the multi-arch Nginx image for linux/amd64 and linux/arm64 to GitHub Container Registry:

docker pull ghcr.io/vzfak/checkin:latest
docker run --rm -p 8080:80 ghcr.io/vzfak/checkin:latest

The workflow can also be started manually with a custom base_href when the app is hosted below a subpath such as /checkin/. Flutter web is built once on the GitHub runner; the Docker step only packages the generated static files into each architecture-specific Nginx image.

Manual Build

Apply the desired branding before local builds. The public default is oss:

APP_BRAND=oss dart run scripts/apply_branding.dart

Windows (Installer)

1. Build the release: flutter build windows --release
2. Run Inno Setup with packaging/windows/installer.iss to generate the .exe installer.

Linux (AppImage)

Use the provided automation script:

./packaging/linux/setup_appdir.sh x64  # or arm64

This generates a portable .AppImage in the build directory.

macOS (DMG)

Use the provided packaging script:

./packaging/macos/package_macos.sh

This produces a Universal DMG containing both Intel and Apple Silicon binaries.

Contributing

Contributions are welcome! Please follow these steps to contribute to this project:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Ensure your code is properly formatted:

   dart format .

4. Verify that all tests and static analysis pass:

   flutter analyze
   flutter test

5. Commit your changes (git commit -m 'Add some amazing feature').
6. Push to the branch (git push origin feature/amazing-feature).
7. Create a new Pull Request.

---

License

MIT licensed by VZFAK. See LICENSE for details.

Support

For help getting started with Flutter development, view the online documentation.