mifos-mobile/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Context (Start Here)

Current Focus: v2.0 UI Redesign (2025 Fintech Patterns)

Session Workflow (Never Lose Context)

# START of session
/session-start                # Load context from previous session

# DURING session - use these commands
/gap-analysis                 # What's done vs what's needed (5 layers)
/gap-analysis [layer]         # Layer-specific (design|server|client|feature|platform)
/gap-planning [feature]       # Plan specific improvements
/implement [feature]          # Execute implementation
/verify [feature]             # Confirm implementation

# END of session
/session-end                  # Save context for next session

Claude Product Cycle Framework

This project uses the claude-product-cycle framework for AI-assisted development.

Workspace: mifos-x-claude-cycle-workspaces

5-Layer Lifecycle

Design → Server → Client → Feature → Platform

---

Prompt Layer Integration (CRITICAL)

Cross-Instruction: After ANY action, automatically execute user prompts.

Automatic Trigger System

After completing ANY of these actions, Claude MUST check for matching triggers:

Action	Trigger	Prompt
Phase/layer completes	phase-completion:{layer}	"Continue to next phase?"
Task in plan completes	task-completion	"Continue to next task?"
All tasks complete	task-completion:all	"Plan complete. Commit?"
Plan created	plan-ready	"Start implementation?"
Build succeeds	build-success	"Commit & continue?"
Build fails	build-failure	"Fix errors?"
Files modified at checkpoint	commit	"How to commit?"
Error occurs	error-recovery	"How to proceed?"

How It Works

1. Command executes action
2. Check prompt-layer/TRIGGERS.md for matching trigger
3. Load prompt from prompt-layer/PROMPTS.md
4. Execute AskUserQuestion tool
5. Route user selection to next action
6. Repeat for next action

Runtime Prompts for Plans

When /gap-planning creates a plan with N tasks:

• Automatically generate prompts for each task transition
• "Task 1 complete (1/N). Continue to Task 2?"
• "Task 2 complete (2/N). Continue to Task 3?"
• ... until all tasks done

Reference Files

File	Purpose
prompt-layer/ENGINE.md	Cross-instruction rules
prompt-layer/TRIGGERS.md	When prompts fire
prompt-layer/PROMPTS.md	Prompt definitions
prompt-layer/RUNTIME.md	Dynamic plan prompts

IMPORTANT: Do NOT hardcode prompts in commands. Let the engine handle them automatically.

---

Project Overview

Mifos Mobile is a Kotlin Multiplatform (KMP) application for the MifosX Self-Service platform, enabling end-users to view/transact on their accounts and loans. It targets Android, iOS, Desktop (JVM), and Web (Kotlin/JS + WASM).

Build Commands

# Build the project
./gradlew build

# Run all pre-push checks (recommended before creating PR)
./ci-prepush.sh

# Individual checks
./gradlew check -p build-logic                     # Verify build-logic configuration
./gradlew spotlessApply --no-configuration-cache   # Apply code formatting
./gradlew dependencyGuardBaseline                  # Generate dependency-guard baseline
./gradlew detekt                                   # Run static analysis

# Run tests
./gradlew testDebug                                # Run debug unit tests
./gradlew :core:data:test                          # Run tests for a specific module

# Lint checks
./gradlew :cmp-android:lintRelease                 # Run lint on Android app

# Android builds
./gradlew :cmp-android:assembleDemoDebug           # Build demo debug APK
./gradlew :cmp-android:assembleProdRelease         # Build production release APK

Architecture

Module Structure

Platform Entry Points:

• cmp-android/ - Android application module
• cmp-ios/ - iOS application (uses CocoaPods via cmp-shared)
• cmp-desktop/ - Desktop (JVM) application
• cmp-web/ - Web application (Kotlin/JS)
• cmp-shared/ - Shared KMP module compiled for all platforms
• cmp-navigation/ - Cross-platform navigation with Compose Navigation

Core Modules (core/):

• data/ - Repository implementations, connects network to UI
• network/ - Ktorfit-based API services and HTTP client
• model/ - Domain models shared across features
• datastore/ - Local data persistence (DataStore)
• database/ - Room database (KMP)
• ui/ - Shared UI components
• designsystem/ - Design tokens, theme, common composables
• common/ - Shared utilities
• qrcode/ - QR code generation/scanning

Core Base Modules (core-base/): Platform-abstracted implementations shared across the template system.

Feature Modules (feature/): Each feature is a separate KMP module containing screens, ViewModels, and navigation. Features include: auth, home, accounts, loan-account, savings-account, beneficiary, transfer-process, etc.

Library Modules (libs/): Internal libraries like country-code-picker, mifos-passcode, material3-navigation.

Key Patterns

Dependency Injection: Koin for all platforms. Each module defines a Koin module in its di/ package.

Navigation: Uses Jetbrains Compose Navigation. Navigation graphs defined in cmp-navigation/:

• ROOT_GRAPH → AUTH_GRAPH → PASSCODE_GRAPH → MAIN_GRAPH

Network Layer: Ktorfit (Retrofit-like for Ktor) with services in core/network/services/. Base URL: https://tt.mifos.community/fineract-provider/api/v1/self/

State Management: ViewModels with StateFlow/SharedFlow. Features use ScreenState<T> pattern for loading/success/error states.

Convention Plugins

Custom Gradle plugins in build-logic/convention/ standardize module configuration:

• mifos.android.application - Android app configuration
• org.convention.cmp.feature - KMP feature module (applies Compose, Koin, core dependencies)
• org.convention.kmp.library - KMP library module
• mifos.kmp.room - Room database setup for KMP
• mifos.spotless.plugin, mifos.detekt.plugin - Code quality

Build Flavors

Android has two product flavors:

• demo - Development/testing
• prod - Production

Development Notes

• JDK 21 required (see build-logic/convention/build.gradle.kts)
• Pull requests target the development branch
• Commit message format: <type>(<scope>): <subject> (feat, fix, docs, refactor, test, chore)
• Demo credentials: Instance gsoc.mifos.community, Username maria, Password password

Git Commit & PR Guidelines

• Always use feature branches: NEVER push directly to development branch
  • Create a feature branch: git checkout -b feature/[description]
  • Push to feature branch: git push origin feature/[description]
  • Create PR targeting development branch
• No Claude references: Do NOT add Claude attribution, co-author lines, or "Generated with Claude Code" footers to commits or PRs
• Keep commit messages clean and focused on the changes made
• PR descriptions should only contain relevant technical information