Totem Client

Guided introspection groups at totem.org

🧭 Overview

Totem is a space for guided group introspection. This Flutter app is the official open-source mobile client for the Totem platform. It connects people through structured group sessions and authentic conversations, powered by a thoughtfully crafted UI and backend.

This client targets both iOS and Android, using Flutter and Riverpod for a fast, modern, and scalable development experience.

---

📦 Installation

Make sure you have Flutter installed and configured.

git clone https://github.com/totem-technologies/totem_app.git
flutter config --enable-swift-package-manager
cd totem_app
flutter pub get
make githooks  # Install git hooks for code formatting

Note

You must setup firebase locally. ⚠️ You must run flutterfire configure to generate firebase_options.dart and add your own Firebase config files (google-services.json, GoogleService-Info.plist) locally. These files are not committed to the repo. Learn more

📲 Running on Devices

For development:

flutter run -d android    # Android
flutter run -d ios        # iOS
flutter run -d chrome --web-browser-flag "--disable-web-security" --wasm     # Web (temporary testing)

If testing on an iOS device, ensure you're using macOS and have Xcode installed.

You can use the --flavor option to build for staging or production (default).

On android, When reattaching, use:

adb logcat "*:S" flutter:V
flutter attach

or

flutter run --use-application-binary=build\app\outputs\apk\debug\app-debug.apk

🧪 Testing

Run all tests:

flutter test

Coming soon: Widget tests and CI-integrated integration tests.

Deep Linking

To test deep linking, you can use the following commands:

For Android:

adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://totem.org/spaces/event/doa689fvb"' org.totem.app

For iOS:

xcrun simctl openurl booted "https://totem.org/spaces/event/doa689fvb"

Local Server

To run the app with a local server, you can set the TOTEM_API_URL environment variable at the .env file in the root directory of the project. This allows you to connect to a local instance of the Totem API.

API_URL="http://localhost:8000/"
MOBILE_API_URL="http://localhost:8000/"

✍️ Project Structure

lib/
├── api/             # API clients & models (generated with Retrofit)
├── auth/            # Auth flow: login, profile setup, state
├── core/            # Config, theme, services, errors
├── features/        # Feature modules (spaces, profile, video_sessions, etc.)
├── navigation/      # Centralized routing and guards
├── shared/          # Reusable widgets
└── main.dart        # Entry point, app root

🔔 Notifications

Notifications are handled using Firebase Cloud Messaging (FCM). In the notification data, one may include a path key to specify the route to navigate to when the user taps on the notification. Check all the available routes here.

🚢 Release (for developers)

The release process is automated via a Dart script that handles versioning, tagging, and pushing to the repository.

Prerequisites

Before creating a release, ensure:

• You are on the main branch
• Your working tree is clean (no uncommitted changes)
• Your local main branch is up-to-date with origin/main

Creating a Release

Run the release command:

make release

The script will:

1. Display the current version from pubspec.yaml
2. Suggest a default version (increments patch and build number)
3. Prompt you to enter a new version

👥 Community

Join the Totem movement at totem.org. To discuss development or get involved, feel free to open an issue or pull request.

✨ Built with care by the Totem Technologies team ✨