Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions .ai/docs/INDEX.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Documentation Index

**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards.

## Quick Reference

### Project Documentation
Project-level documentation covering vision, goals, architecture, and technology choices.

### Technical Standards
Coding standards, conventions, and best practices organized by domain.

---

## Project Documentation

Located in `\.ai/docs/project/`

### Vision (`project/vision.md`)
Hedvig Android project vision and purpose: insurance management app for Nordic customers, current state (v14.0.10, 7 years, 13,655 commits), goals for KMP migration, quality improvements, and feature expansion over the next 6-12 months.

### Roadmap (`project/roadmap.md`)
Development roadmap with prioritized enhancements: feature development and KMP migration (high), test coverage and ADRs (medium), KDoc coverage and resource cleanup (tech debt), and future considerations for full KMP and architecture documentation.

### Tech Stack (`project/tech-stack.md`)
Complete technology inventory: Kotlin 2.3.10, Jetpack Compose (100% Compose, no XML), Apollo GraphQL 4.4.1, Molecule 2.2.0 for MVI, Koin 4.1.1 for DI, Room 2.8.4, Ktor 3.4.0, Arrow 2.2.1.1, AGP 9.0.0, GitHub Actions CI/CD, Datadog and Firebase monitoring, ktlint formatting, and all dependency versions.

### Architecture (`project/architecture.md`)
System architecture: feature-based modular MVI with Molecule, 80+ modules across feature (27), data (13), core (14), Apollo (6), design system, and navigation layers. Strict module dependency rules (no cross-feature deps), data flow from Compose UI through ViewModel/Presenter to repositories and Apollo GraphQL, external integrations, and build configuration.

---

## Technical Standards

### Global Standards

Located in `\.ai/docs/standards/global/`

#### Coding Style (`standards/global/coding-style.md`)
Naming consistency, automatic formatting, descriptive names, focused functions, uniform indentation, dead code removal, DRY principle, avoiding unnecessary backward compatibility code. Project-specific: ktlint_official code style (2-space indent, 120 char lines, trailing commas, no wildcard imports, disabled rules), file and class naming conventions (PascalCase files, kebab-case modules, ViewModel/Presenter/Destination/UseCase naming), sorted dependencies via square/sort-dependencies plugin, centralized version catalog in libs.versions.toml.

#### Commenting (`standards/global/commenting.md`)
Self-documenting code practices, sparing comment usage, and avoiding changelog-style comments in code.

#### Development Conventions (`standards/global/conventions.md`)
Predictable file structure, up-to-date documentation, clean version control, environment variables, minimal dependencies, consistent reviews, testing standards, feature flags, and changelog maintenance. Project-specific: MVI with Molecule pattern (MoleculeViewModel/MoleculePresenter, CollectEvents, sealed interface Events/UiState), LoadIteration retry pattern, feature module isolation (no cross-feature deps, build-time enforced), internal visibility for feature module classes, module organization (suffixes, KMP layout, auto-discovery), convention plugin DSL (compose, apollo, serialization, androidResources), JVM 21 with Kotlin 2.2 (context parameters, expect-actual, when guards), Koin DI pattern with ProdOrDemoProvider.

#### Error Handling (`standards/global/error-handling.md`)
Clear user messages, fail-fast validation, typed exceptions, centralized handling, graceful degradation, retry with backoff, and resource cleanup. Project-specific: Arrow Either for error handling (Either<ErrorMessage, T>, either builder, safeExecute/safeFlow), Apollo GraphQL extensions and .graphql file naming, navigation destinations (@Serializable with Destination interface, navgraph/navdestination), use case pattern (interface with invoke + Impl class returning Either).

#### Minimal Implementation (`standards/global/minimal-implementation.md`)
Building only what is needed, deleting exploration artifacts, avoiding future stubs and speculative abstractions, reviewing before commit, and treating unused code as debt.

#### Validation (`standards/global/validation.md`)
Server-side validation, client-side feedback, early input checking, specific error messages, allowlists over blocklists, type/format checks, input sanitization, business rule validation, and consistent enforcement across entry points.

### Frontend Standards

Located in `\.ai/docs/standards/frontend/`

#### Accessibility (`standards/frontend/accessibility.md`)
Semantic HTML, keyboard navigation, color contrast, alt text and labels, screen reader testing, ARIA usage, heading structure, and focus management.

#### Components (`standards/frontend/components.md`)
Single responsibility, reusability, composability, clear interfaces, encapsulation, consistent naming, local state management, minimal props, and component documentation. Project-specific: Jetpack Compose only (no XML), Material 3 restriction (M2 banned via lint, M3 internal to design-system-internals), composable PascalCase naming, Destination composable pattern (internal @Composable with collectAsStateWithLifecycle delegating to private Screen), feature module directory structure (ui/navigation/di/data), accessibility checklist enforcement via PR template.

#### CSS (`standards/frontend/css.md`)
Consistent methodology (Tailwind/BEM/modules), working with the framework, design tokens, minimizing custom CSS, and production optimization.

#### Responsive Design (`standards/frontend/responsive.md`)
Mobile-first approach, standard breakpoints, fluid layouts, relative units, cross-device testing, touch-friendly targets, mobile performance, readable typography, and content priority.

### Backend Standards

*Not initialized for this project. If you need backend standards, you can:*
- *Add them manually using the docs-manager skill*
- *Run `/maister:standards-discover --scope=backend` to auto-discover*

### Testing Standards

Located in `\.ai/docs/standards/testing/`

#### Test Writing (`standards/testing/test-writing.md`)
Testing behavior over implementation, clear test names, mocking external dependencies, fast execution, risk-based testing, balancing coverage and velocity, critical path focus, and appropriate test depth. Project-specific: PR quality gates (4 parallel CI jobs: unit tests, Android lint, ktlint, debug build), Molecule presenter testing (presenter.test with molecule-test), AssertK assertion library (exclusively, no JUnit assertEquals or Google Truth), Turbine for test fakes (Turbine<Either<ErrorMessage, T>>), JUnit 4 with kotlinx.coroutines.test.runTest and TestLogcatLoggingRule, backtick-quoted test method names, test file locations (src/test/kotlin, src/androidTest/kotlin, -test modules).

---

## How to Use This Documentation

1. **Start Here**: Always read this INDEX.md first to understand what documentation exists
2. **Project Context**: Read relevant project documentation before starting work
3. **Standards**: Reference appropriate standards when writing code
4. **Keep Updated**: Update documentation when making significant changes
5. **Customize**: Adapt all documentation to your project's specific needs

## Updating Documentation

- Project documentation should be updated when goals, tech stack, or architecture changes
- Technical standards should be updated when team conventions evolve
- Always update INDEX.md when adding, removing, or significantly changing documentation
102 changes: 102 additions & 0 deletions .ai/docs/project/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# System Architecture

## Overview
Hedvig Android is a highly modular Android application with 80+ Gradle modules organized into distinct layers. The architecture follows a feature-based MVI pattern using Molecule for reactive state management, with strict module dependency enforcement.

## Architecture Pattern
**Pattern**: Feature-based Modular MVI with Molecule

The app enforces a layered architecture where feature modules are independent units that communicate through the data and core layers. Feature modules CANNOT depend on other feature modules — this is enforced at build time by the custom Gradle convention plugin.

**Data Flow**: User Action -> Event -> Presenter (Composable) -> UiState -> UI

## System Structure

### Feature Layer (27 modules)
- **Location**: `app/feature/feature-{name}/`
- **Purpose**: Self-contained user-facing features (home, chat, insurances, payments, claims, profile, etc.)
- **Pattern**: Each module follows `ui/ + navigation/ + di/` structure
- **Key constraint**: Features are isolated — no cross-feature dependencies

### Data Layer (13 modules)
- **Location**: `app/data/data-{domain}/`
- **Purpose**: Business logic, repositories, use cases, data access
- **Pattern**: Public/Android split (`-public` for interfaces, `-android` for implementation) or KMP single module with `commonMain`/`androidMain`
- **Key files**: Repository interfaces, Use cases, Apollo GraphQL operations

### Core Layer (14 modules)
- **Location**: `app/core/core-{name}/`
- **Purpose**: Shared utilities, common types, datastore, resources
- **Key modules**: `core-common-public`, `core-datastore-public`, `core-resources`

### Apollo/GraphQL Layer (6 modules)
- **Location**: `app/apollo/`
- **Purpose**: GraphQL client configuration, schema management, normalized caching
- **Backend**: Octopus API with response-based code generation

### Design System
- **Location**: `app/design-system/`
- **Purpose**: Reusable UI components, theming, Material 3 integration
- **Modules**: `design-system-api`, `design-system-hedvig`, `design-system-internals`

### Navigation
- **Location**: `app/navigation/`
- **Purpose**: Type-safe navigation with serializable destinations
- **Top-level graphs**: Home, Insurances, Forever, Payments, Profile

### Infrastructure Modules
- **Auth**: BankID integration, OAuth
- **Database**: Room database modules
- **Language**: Localization (KMP-compatible)
- **Logging/Tracking**: Timber, Datadog, Firebase analytics
- **Network**: Ktor client configuration, interceptors

## Data Flow

```
UI (Compose)
|
v (events)
ViewModel (MoleculeViewModel)
|
v (delegates)
Presenter (MoleculePresenter - @Composable)
|
v (calls)
Use Cases (business logic)
|
v (calls)
Repositories (data access)
|
v (queries/mutations)
Apollo GraphQL Client --> Octopus Backend
Room Database (local cache)
DataStore (preferences)
```

## External Integrations
| Integration | Technology | Purpose |
|---|---|---|
| Octopus Backend | Apollo GraphQL 4.4.1 | Primary data source |
| Firebase | Crashlytics, Analytics, Messaging | Monitoring, push notifications |
| Datadog | SDK 3.6.0 | RUM, logs, analytics |
| BankID | Custom auth modules | Swedish digital identity authentication |
| Lokalise | Gradle plugin | Translation management |
| Play Store | GitHub Actions workflow | Production distribution |
| Firebase App Distribution | GitHub Actions workflow | Staging/internal distribution |

## Configuration
- **Build types**: Debug (dev), Staging, Release — each with different backend and application ID
- **Gradle convention plugins**: Custom DSL (`hedvig { compose(); apollo("octopus") }`) for consistent module setup
- **Feature flags**: Managed through `featureflags` module
- **Demo mode**: `Provider<T>` pattern with `ProdOrDemoProvider` for conditional implementations

## Module Dependency Rules
1. Feature modules CANNOT depend on other feature modules (enforced by build plugin)
2. Feature modules depend on data, core, navigation, and design-system modules
3. Data modules expose public interfaces in `-public` modules
4. Core modules provide shared utilities available to all layers
5. Type-safe project accessors (`projects.coreCommonPublic`) used for all inter-module dependencies

---
*Based on codebase analysis performed 2026-04-07*
29 changes: 29 additions & 0 deletions .ai/docs/project/roadmap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Development Roadmap

## Current State
- **Version**: 14.0.10
- **Key Features**: Insurance management, claims filing, chat support, payments, referral program (Forever), profile management
- **Architecture**: 80+ modules (27 feature, 14 core, 13 data, 6 Apollo, design system, navigation, auth, database)

## Planned Enhancements

### High Priority
- [ ] **Feature Development** — Continue expanding insurance product offerings and user-facing capabilities
- [ ] **KMP Migration** — Migrate remaining modules to Kotlin Multiplatform (currently 54% coverage)

### Medium Priority
- [ ] **Code Quality** — Improve test coverage reporting in CI/CD pipeline
- [ ] **Documentation** — Add Architecture Decision Records (ADRs) for key decisions
- [ ] **Performance** — Establish performance testing workflows for critical user journeys

### Technical Debt
- [ ] **KDoc Coverage** — Add documentation comments to public API modules (data layer, use cases)
- [ ] **Resource Cleanup** — Automate unused resource detection (currently manual workflow)

## Future Considerations
- **Full KMP**: Complete migration of all eligible modules to Kotlin Multiplatform
- **Architecture Documentation**: Visual module dependency diagrams in main documentation
- **Scalability**: Performance profiling and optimization for growing feature set

---
*Assessment based on project analysis performed 2026-04-07*
132 changes: 132 additions & 0 deletions .ai/docs/project/tech-stack.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# Technology Stack

## Overview
This document describes the technology choices for Hedvig Android — a production mobile app built with Kotlin, Jetpack Compose, and Apollo GraphQL on a highly modular architecture (80+ Gradle modules).

## Languages

### Kotlin (2.3.10)
- **Usage**: 100% of codebase (1,189 Kotlin files)
- **Rationale**: Official Android development language with excellent Compose and coroutines support
- **Key Features Used**: Coroutines, Flow, Serialization, Multiplatform (KMP in 43 modules)

## Frameworks

### UI & Presentation
| Technology | Version | Usage |
|---|---|---|
| Jetpack Compose | 2026.01.01 BOM | All UI — 100% Compose, no XML layouts |
| Material 3 | Latest via BOM | Design system theming (internal to design-system-internals) |
| Coil | 3.3.0 | Image loading (SVG, GIF, PDF support) |
| Accompanist | 0.37.3 | Permissions handling |
| ExoPlayer (Media3) | 1.9.2 | Video playback |

### State Management & Architecture
| Technology | Version | Usage |
|---|---|---|
| Molecule | 2.2.0 | Reactive MVI pattern (Composable presenters) |
| Kotlin Coroutines | 1.10.2 | Async operations |
| Arrow | 2.2.1.1 | Functional programming (Either, Option) |

### Data & Networking
| Technology | Version | Usage |
|---|---|---|
| Apollo GraphQL | 4.4.1 | Primary data source (Octopus backend), normalized caching |
| Ktor Client | 3.4.0 | HTTP client with custom interceptors |
| OkHttp | 5.3.2 | Network layer |
| kotlinx.serialization | 1.10.0 | JSON serialization |

### Dependency Injection
| Technology | Version | Usage |
|---|---|---|
| Koin | 4.1.1 BOM | Service locator/DI with modular configuration |

## Database

### Room (2.8.4)
- **Type**: SQLite-based relational database
- **Usage**: Local persistence for caching and offline data
- **Modules**: Dedicated `database/` modules

### DataStore (1.2.0)
- **Type**: Key-value preferences
- **Usage**: Encrypted preferences storage

## Build Tools & Package Management

### Gradle (8.11+)
- **Android Gradle Plugin**: 9.0.0
- **Convention Plugins**: Custom `hedvig.gradle.plugin` with DSL for Compose, Apollo, Room, Serialization
- **Module Discovery**: Automatic — any directory with `build.gradle.kts` under `/app` is auto-discovered
- **Dependency Versions**: Centralized in `gradle/libs.versions.toml` (150+ entries)
- **BOM Strategy**: Compose BOM, Firebase BOM, OkHttp BOM, Koin BOM

### Build Optimization
| Feature | Status |
|---|---|
| Gradle Configuration Cache | Enabled |
| Parallel Builds | Enabled |
| Build Cache | Enabled (Gradle Develocity 4.3.2) |
| JVM Memory | 8GB heap |

## Infrastructure

### CI/CD — GitHub Actions
| Workflow | Purpose |
|---|---|
| pr.yml | PR checks (lint, test, build) |
| staging.yml | Staging builds via Firebase App Distribution |
| upload-to-play-store.yml | Production releases to Play Store |
| graphql-schema.yml | Apollo schema sync |
| strings.yml | Lokalise translation sync |
| unused-resources.yml | Resource cleanup checks |
| umbrella.yml | Comprehensive validation |

### Monitoring & Analytics
| Technology | Version | Usage |
|---|---|---|
| Datadog | 3.6.0 | RUM, logs, analytics |
| Firebase Crashlytics | Latest via BOM | Crash reporting |
| Firebase Analytics | Latest via BOM | Usage analytics |
| Firebase Messaging | Latest via BOM | Push notifications |

## Development Tools

### Linting & Formatting
| Tool | Configuration |
|---|---|
| ktlint | `ktlint_official` style, 2-space indent, 120 char max, trailing commas |
| Android Lint | Custom rules in `hedvig-lint` module |
| Sort Dependencies | Plugin for consistent dependency ordering |

### Code Generation
| Tool | Usage |
|---|---|
| Apollo Codegen | GraphQL type-safe Kotlin from `.graphql` files |
| KSP (2.3.2) | Annotation processing for Room, etc. |

## Testing
| Technology | Version | Usage |
|---|---|---|
| JUnit 4 | 4.13.2 | Unit test framework |
| Turbine | 1.2.1 | Flow testing |
| AssertK | 0.28.1 | Fluent assertions |
| Robolectric | 4.16.1 | Android test support |
| TestParameterInjector | 1.21 | Parameterized testing |
| Molecule Test Utils | 2.2.0 | Presenter testing |

## Localization
| Technology | Usage |
|---|---|
| Lokalise | Translation management platform |
| lokalise-gradle-plugin | Automated translation download |

## Version Management
- All dependency versions centralized in `gradle/libs.versions.toml`
- BOMs used for framework version alignment (Compose, Firebase, OkHttp, Koin)
- Type-safe project accessors for inter-module dependencies
- `dependencyAnalysis` plugin (3.5.1) for dependency health monitoring

---
*Last Updated*: 2026-04-07
*Auto-detected*: All technologies and versions detected from `gradle/libs.versions.toml`, `build.gradle.kts` files, and source code analysis
21 changes: 21 additions & 0 deletions .ai/docs/project/vision.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Project Vision

## Overview
Hedvig Android is a production mobile application that provides insurance management for Hedvig customers on the Android platform.

## Current State
- **Age**: 7 years (since 2019)
- **Status**: Active development (v14.0.10, 13,655 commits)
- **Users**: Hedvig insurance customers in Nordic markets
- **Tech Stack**: Kotlin 2.3.10, Jetpack Compose, Apollo GraphQL, Molecule MVI, Koin

## Purpose
Hedvig Android enables customers to manage their insurance lifecycle entirely from their phone — from purchasing policies and viewing coverage details, to filing claims and managing payments. The app serves as the primary touchpoint between Hedvig and its mobile users.

## Goals (Next 6-12 Months)
- **Feature Development**: Continue expanding functionality with new insurance products and user-facing features
- **Quality & Stability**: Improve app stability, performance, and overall code quality
- **KMP Migration**: Continue migrating modules to Kotlin Multiplatform (currently 43/80+ modules, ~54%)

## Evolution
The project has evolved from its initial architecture to a highly modular monorepo with 80+ modules, adopting modern patterns like Molecule for reactive state management, 100% Jetpack Compose UI (no XML), and progressive KMP adoption. The architecture enforces strict module boundaries — feature modules cannot depend on other feature modules — ensuring clean separation of concerns at scale.
Loading