Hermes

A Flutter application demonstrating GitHub user search with infinite scroll pagination, built using clean architecture and the Flux pattern.

Features

• 🔍 GitHub User Search - Search for GitHub users using the GitHub GraphQL API
• 📜 Infinite Scroll - Automatic pagination when scrolling to the bottom
• 🌐 Internationalization - Japanese language support with slang
• 🎨 Material Design 3 - Modern UI with custom theming
• 🏗️ Flux Architecture - Clean separation of concerns with Actions, Stores, and ViewModels
• 🔄 Reactive State Management - Riverpod with hooks for efficient state updates
• 🧩 Monorepo Structure - Organized with Melos for scalable development

Table of Contents

• Prerequisites
• First Time Setup
• Code Generation (Important!)
• Running the Application
• Development Workflow
• Project Structure
• Architecture

Prerequisites

Before you begin, ensure you have the following installed:

1. Flutter SDK

• Install Flutter SDK (version 3.35.7 or later)
• Visit Flutter Getting Started
• Verify installation: flutter doctor

2. Development Tools

• VS Code (recommended): https://code.visualstudio.com/
  • Install Flutter extension
  • Install Dart extension

3. Platform Setup

• iOS Development (macOS only): iOS Setup Guide
  • Xcode
  • CocoaPods
• Android Development: Android Setup Guide
  • Android Studio
  • Android SDK

4. Melos (Monorepo Management)

This project uses Melos to manage multiple packages. Install it globally:

dart pub global activate melos

Add Dart global packages to your PATH (add to ~/.zshrc or ~/.bashrc):

export PATH="$PATH:$HOME/.pub-cache/bin"

Reload your shell:

source ~/.zshrc  # or source ~/.bashrc

Verify installation:

melos --version

First Time Setup

Follow these steps in order:

1. Clone the Repository

git clone <repository-url>
cd hermes

2. Bootstrap the Workspace

This will get dependencies for all packages:

melos bootstrap

3. Configure Environment Variables

Configure your GitHub API token for authentication:

1. Open packages/core/.env
2. Set your GitHub token:

   GITHUB_BASE_URL=https://api.github.com/graphql
   GITHUB_TOKEN=ghp_YourActualTokenHere
   

Creating a GitHub Personal Access Token:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token" (classic)
3. Give it a descriptive name (e.g., "Hermes Development")
4. Select scopes: public_repo (for searching users)
5. Click "Generate token"
6. Copy the token and paste it into your .env file

⚠️ Important: Never commit your .env file to git. It's already in .gitignore.

4. Generate Required Code ⚠️ IMPORTANT

Generated files are NOT committed to git. You MUST generate them locally:

melos run build_runner --no-select

This generates:

• Riverpod providers (*.g.dart)
• Freezed models (*.freezed.dart)
• i18n strings (strings*.g.dart)

Without this step, the project will not compile!

Code Generation (Important!)

When to Regenerate Code

You MUST regenerate code in these situations:

1. After cloning the repository (first time)
2. After pulling changes that affect:
   • Models with @freezed annotation
   • Providers with @riverpod annotation
   • i18n JSON files
3. When switching branches with code generation changes
4. After modifying any files that use code generation

Regeneration Commands

One-time generation:

melos run build_runner --no-select

Watch mode (auto-regenerates on file changes):

melos run build_runner:watch --no-select

Press Ctrl+C to stop watch mode.

Troubleshooting Code Generation

If you encounter build errors:

1. Clean and regenerate:

   melos clean
   melos bootstrap
   melos run build_runner --no-select

2. Force regeneration:

   melos exec -- flutter clean
   melos bootstrap
   melos run build_runner --no-select

Running the Application

Using VS Code

1. Open the project in VS Code
2. Press Command + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)
3. Type "Flutter: Select Device" and choose your device/emulator
4. Press F5 or click "Run and Debug" in the sidebar
5. Select "Flutter" from the debug configurations

Using Command Line

# List available devices
flutter devices

# Run on a specific device
flutter run -d <device-id>

# Run in debug mode (default)
flutter run

# Run in profile mode (for performance testing)
flutter run --profile

# Run in release mode (optimized)
flutter run --release

Development Workflow

Common Commands

# Get dependencies for all packages
melos run get

# Run code generation
melos run build_runner --no-select

# Format all code
melos run format

# Analyze code (linting)
melos run analyze

# Clean all packages
melos run clean

Project Structure

hermes/
├── lib/                           # Main app entry point
│   ├── main.dart                 # App initialization
│   └── router/                   # App routing
├── packages/
│   ├── core/                     # Core functionality
│   │   ├── flux/                # Flux architecture (Dispatcher, EventStore, ActionCreator)
│   │   └── env/                 # Environment configuration
│   ├── data/                     # Data layer
│   │   ├── graphql/             # GraphQL queries
│   │   ├── graphql_client.dart  # GraphQL client setup
│   │   └── links/               # GraphQL links (auth, error handling)
│   ├── ui/                       # Shared UI components
│   │   └── theme/               # App theme (colors, typography)
│   └── feature/
│       └── home/                # GitHub search feature
│           ├── action/          # Flux actions and action creators
│           ├── store/           # Flux stores for state management
│           ├── viewmodel/       # ViewModels (Input/Output interface)
│           ├── view/            # UI pages
│           ├── model/           # Data models
│           ├── repository/      # Data access layer
│           └── i18n/            # Internationalization

Architecture

Flux Pattern

This project uses the Flux architecture pattern for unidirectional data flow:

User Input → ViewModel → ActionCreator → Dispatcher → Store → State Update → ViewModel → UI

Key Components:

1. Actions (action/)

   • Immutable data classes extending EventAction
   • Represent user intents (e.g., SearchUsersAction, LoadMoreUsersAction)

2. Action Creators (action/)

   • Create and dispatch actions to the Dispatcher
   • Example: GitHubSearchActionCreator

3. Stores (store/)

   • Extend EventStore and manage feature state
   • Listen to actions from Dispatcher via onAction()
   • Use Freezed for immutable state
   • Example: GitHubSearchStore with GitHubSearchState

4. ViewModels (viewmodel/)

   • Implement Input/Output interface pattern
   • Watch store state and provide it to UI
   • Delegate user actions to action creators
   • Example: GitHubSearchViewmodel

5. Views (view/)

   • UI components using StatefulHookConsumerWidget
   • Watch viewmodel for state updates
   • Call viewmodel methods for user interactions

State Management

• Riverpod for dependency injection
• Freezed for immutable state classes
• Hooks for lifecycle management

Features

GitHub User Search

• Search GitHub users by username
• Display user profile with avatar, bio, stats, and top repositories
• Infinite scroll pagination (loads more when scrolling to bottom)
• Error handling with user-friendly messages

Internationalization

• Japanese language support using slang
• Base locale: ja (Japanese)
• Easy to add more languages by adding JSON files

Code Generation

The project uses several code generators:

• riverpod_generator: Generates provider code
• freezed: Generates immutable model classes
• slang_build_runner: Generates i18n translations

Contributing

When contributing to this project:

1. Follow the Flux architecture pattern
2. Use Freezed for all state classes
3. Add i18n keys for all user-facing strings
4. Implement proper error handling
5. Write defensive null-safe code
6. Run melos run analyze before committing
7. Ensure all generated files are up to date

License

[Add your license here]