Imported from Vonage/vonage-video-android-app (AGENTS.md). Install upstream with npx skills add Vonage/vonage-video-android-app. Copyright stays with the author.

AGENTS.md

Module Map

Config-Driven Behavior (Critical)

• config/app-config.json is the single source of truth for feature toggles and baseApiUrl.
• Never hand-edit gradle/generated-config.properties — it is generated by ./gradlew generateVonageConfig.
• app/build.gradle.kts reads gradle/generated-config.properties and maps each property to both a BuildConfig field and a missingDimensionStrategy(...) flavor selection.
• Generated runtime constants: AppConfig under com.vonage.android.config (written to app/build/generated/source/jsonConfig/).
• generateVonageConfig is a hard dependency of all Kotlin and KSP compile tasks in app/build.gradle.kts; config changes must be regenerated before builds.
• Theme is generated from config/theme.json by com.vonage.theme-generator into vonage-video-ui-compose/src/main/java/com/vonage/android/compose/theme/. Do not edit generated theme files directly.
• BASE_API_URL can be set three ways (evaluated in order): local.properties key BASE_API_URL, environment variable BASE_API_URL, or replacing the placeholder directly in app-config.json. Emulator local backend: use 10.0.2.2.

Feature Toggle Pattern

• Optional modules use flavor dimensions with enabled/disabled product flavors (e.g., vonage-feature-chat/build.gradle.kts).
• Public contracts live in src/main; behavior implementations live in src/enabled and src/disabled. When changing a feature API, update both flavor source sets.
• vonage-meeting-room also accepts a runtime filter: MeetingRoomBuilder.enabledFeatures(Set<MeetingRoomFeature>). A feature is active only when its compile-time flavor is enabled AND it is present in the runtime set. You cannot enable a compile-time disabled feature at runtime.
• vonage-meeting-room has its own flavor dimensions for three features (archiving, captions, screensharing) with full names like archivingEnabled/archivingDisabled. The remaining features (chat, reactions, videofx, audiofx, settings) always resolve to enabled inside this module; runtime availability is via MeetingRoomFeature.

Architecture Notes

• Session bootstrap path: APIService.getSession() → SessionRepository → MeetingRoomViewModel.connect(...) → VonageVideoClient.initializeSession(...).
• BASE_API_URL propagates to three locations: Retrofit base URL (RetrofitModule.kt), deep links (AppNavHost.kt), and sharing links (util/navigateToShare.kt).
• Hilt DI is used in app/. vonage-meeting-room uses a manual MeetingRoomContainer — do not introduce Hilt into that module.
• Feature signal plugins (chat, reactions) are injected into VonageVideoClient via SdkModule.provideVonageVideoClient(...) in app/.
• vonage-meeting-room is under active refactoring: use cases are being introduced and Call.kt (~800 lines) is being split into focused collaborators. Consult the inline comments in that module before making changes there.
• Debug builds append .debug to applicationId and -DEBUG to versionName, allowing debug and release to co-exist on device.
• Firebase/Crashlytics plugins are only applied for release builds (guarded by isReleaseBuild check in app/build.gradle.kts).

Developer Workflows

# Required first-time setup: install pre-push Git hook
./gradlew installGitHooks

# After any config/app-config.json or theme.json edit
./gradlew generateVonageConfig

# Build and install debug
./gradlew installDebug

# All unit tests
./gradlew test

# Single module unit tests
./gradlew :vonage-meeting-room:test
./gradlew :vonage-video-core:test

# Instrumented tests (connected device/emulator)
./gradlew connectedAndroidTest

# Instrumented tests on Gradle Managed Device (no physical device needed)
./gradlew pixelDebugAndroidTest

# CI-equivalent quality gate (runs tests + coverage XML + detekt)
./gradlew clean koverXmlReportDebug detekt

# Local HTML coverage report
./gradlew koverHtmlReport

# Static analysis (also runs automatically on git push via pre-push hook)
./gradlew detekt

# Binary API compatibility check (runs in CI)
./gradlew apiCheck

Binary API Compatibility

• vonage-audio-selector and vonage-android-logger use the binary-compatibility-validator plugin with committed .api dump files.
• After changing the public API surface of either module, run ./gradlew apiDump and commit the updated .api files alongside the code change.
• ./gradlew apiCheck runs as a separate CI job and fails the build if the .api files are out of sync.

Snapshot Tests (vonage-video-ui-compose)

• Roborazzi (Robolectric-backed) snapshot tests live in vonage-video-ui-compose/src/test/.
• Golden PNGs are in vonage-video-ui-compose/src/test/snapshots/images/ and must be committed.
• Workflow when changing a component's visuals:
  1. Make the UI change.
  2. ./gradlew :vonage-video-ui-compose:recordRoborazziDebug — regenerates goldens.
  3. Review updated PNGs, then commit them alongside the code.
• Verify (CI-equivalent): ./gradlew :vonage-video-ui-compose:verifyRoborazziDebug
• Each test class needs @RunWith(RobolectricTestRunner::class) + @GraphicsMode(GraphicsMode.Mode.NATIVE) + @OptIn(ExperimentalRoborazziApi::class). Dark-mode variant needs @Config(qualifiers = "+night") on the method.
• For dialogs (separate composition root), use onAllNodes(isRoot())[1] instead of onRoot().

UI / Instrumented Test Conventions

• Pattern: ScreenObject (wraps SemanticsNodeInteractionsProvider) + ScreenTest (@HiltAndroidTest @RunWith(AndroidJUnit4::class)).
• TestTag constants go in the source *Route.kt file as an object <Screen>TestTags. Apply .testTag(TAG) first in the modifier chain.
• Rule ordering: HiltAndroidRule at order=0; if permissions needed, GrantPermissionRule at order=1; createComposeRule last.
• Always wrap setContent in VonageVideoTheme { ... }.
• Test naming: given_<precondition>_THEN_<expected_outcome>.
• Use assertDoesNotExist() when a node is absent from composition; assertIsNotDisplayed() when it exists but is off-screen.
• Screen actions data class: all lambda fields must default to {} (no-op).

Conventions

• Kotlin + Java 17 throughout (sourceCompatibility/targetCompatibility = VERSION_17).
• Compose lint is strict via detekt compose rules plugin (build-tools/detekt/detekt.yml). Run ./gradlew detekt before pushing (the pre-push hook does this automatically once installGitHooks is run).
• Branch from develop, not main; PRs target develop. Branch naming for internal contributors: DEVELOPERNAME/TICKETNUMBER-SHORTDESCRIPTION.
• Do not hardcode backend endpoints; use BuildConfig.BASE_API_URL or generated AppConfig.
• Do not add feature flags ad-hoc in app/ when a feature module boundary already exists.
• SDK version is in gradle/libs.versions.toml (opentokAndroidSdk); do not pin it elsewhere.
• Kover coverage excludes vonage-video-ui-compose, vonage-video-sdk, and vonage-config-idea-plugin (see root build.gradle.kts).