hyttahub 0.1.55

A serverless Flutter framework for building applications with an event-sourced architecture, shared site management, and built-in compliance.

A serverless Flutter framework designed as a solid starting point for new casual applications, demonstrated with an example app.

Warning

Note: Under construction; breaking changes may occur.

Built-in Features

• Service Management
  • Service Status & Forced Upgrades: The ability to set a minimum required application version or disable the service for maintenance, and smoothly communicate this to users.
  • Service Administrators: Manage the users who can maintain policies and service status.
  • Beta/Authorized Users: Limit application access to a predefined set of regular users.
• GDPR and App Store Compliance
  • Terms of Service & Privacy Policy: A complete flow for presenting and requiring user acceptance of legal terms, including versioning for updates.
  • Account Deletion: A clear, user-accessible path for account deletion.
  • User Data Access: Since all the event source data is cached on the client, the user can export their data at any time. The application just needs to provide an export feature (e.g., copying events to the clipboard). If the application supports media, then it can provide a way to export the media as well (according to its terms of service).
• App Appearance & Personalization
  • Localization: Support for multiple languages.
  • Theming: Dynamic light and dark mode support.
• Collaboration & Core Features
  • Shared Site (Resource) Management: Supports the common use case of members sharing a resource, or "site" (such as a set of photo albums, a calendar, etc.). The framework manages adding and removing site members, as well as self-removal. Site members can be assigned administrative roles. Backend security rules ensure site data privacy.
• Event Sourcing Framework Replay on the Client
  • This eliminates the common practice of having separate models for UI forms, network marshalling, database storage, and business logic. This reduces boilerplate code and removes the need for app logic on the server side. Events are persisted on the client, significantly reducing service queries. Note: Backend logic (e.g., Cloud Functions or database hooks) is used to assist with cleanup upon account deletion.
  • Event and Replay Views: Service, account, and site events (and their resulting replays) can be viewed directly in the UI, assisting with debugging without needing to access the backend services.
  • Persistence-Agnostic: The framework is designed to support various storage providers (e.g., Firebase, PocketBase) and allows switching between them at runtime. Built-in memory and local file storage are also supported out of the box.

Usage

The repository includes examples of using the library. Follow the instructions below.

Prerequisites

• Install Flutter with Chrome support.
• Run flutter --version to check your version. Ensure it is at least 3.32.1.
• Run flutter devices to check that Chrome is listed as an available device.

Installation & Setup

git clone [e-mail]:bjorge/hyttahub.git
cd hyttahub
flutter pub get
flutter test

Running the Application

cd example/template
flutter run -d chrome

Persistence Registration

HyttaHub is persistence-agnostic and uses a dynamic registration system.

Please see PERSISTENCE.md for details on how to register and use multiple storage providers.

FAQ

I want to make some changes to the language files, how do I compile them?

After updating the .arb files, run:

flutter gen-l10n

How do I run the example app with a local backend?

HyttaHub supports multiple backends. To run the example with a local emulator:

• For Firebase:
  • Install Docker or Podman.
  • Follow the instructions in packages/hyttahub_firebase/tool/firebase_emulator/README to start the Firebase emulator.
  • In the app, select "Firebase" as the storage implementation.
• For PocketBase:
  • Follow the instructions in packages/hyttahub_pocketbase/tool/pocketbase_emulator/README to start the Go-based PocketBase emulator.
  • In the app, select "PocketBase (local)" as the storage implementation.

How do I tag a new release?

git tag v0.1.53
git push origin --tags

How do I compile the protocol buffer files?

Protocol buffer files can be compiled for both Dart (Flutter) and TypeScript (Cloud Functions) using Podman or Docker. See the README in the tool/protobuf-compiler directory for instructions.

Is any server-side code required for this project?

The project requires no long-running server-side code. Backend logic (Cloud Functions for Firebase or Go hooks for PocketBase) is used sparingly—only when necessary to provide access to parts of the system that are inaccessible to the client due to security rules. For example, when a site admin removes a member, a backend process will securely add a "remove" event to that member's account stream (which the admin cannot access directly). This logic is also used for housekeeping tasks, such as removing abandoned site data when the last member leaves a site.

How is shared member data kept private?

Storage-specific security rules are designed to ensure member data privacy. For Firebase, these are defined in firestore.rules and storage.rules. For PocketBase, these same rules are implemented in the Go backend logic. In both cases, only site members are permitted to access site data, and only site administrators can add new members. Likewise, only the owner of an account can modify their account settings, and only a service administrator can update the global service status.

Can I add social authentication, such as Google or Apple logins?

The current implementations use email addresses as keys for member management and security rules. Any authentication provider that reliably retains and verifies the user's email will work natively. For Apple sign-ins, since users can choose to anonymize their email via a relay, updates would be required in the framework to accommodate that specific case.