This guide is for people (and coding agents) who change the app in stacknoise/haac-android. It explains how the project is built and checked, and the rules every change has to follow: packages by topic, the factory pattern, error codes, the generated code index and the CI checks.
It is a practical summary. The specification is concept.md; the rules below are concept chapters 16 and 17. If this guide and the concept disagree, the concept wins. CLAUDE.md is the short version for coding agents.
The companion integration lives in stacknoise/haac-bridge and has its own guide (development.md there). This repository contains no Python code.
Requirements:
- JDK 21 (the one bundled with Android Studio works) and the Android SDK (
compileSdk37,targetSdk37,minSdk28). The SDK levels are set only inbuild-logic(AndroidSdk), never in a module. - Android Studio, or the Gradle wrapper on the command line. The SDK path goes into
local.properties(not committed).
./gradlew assembleDebug # both flavors: play and sideload
./gradlew test # unit tests (JUnit 5)
./gradlew lint detekt # Android Lint and Detekt
./gradlew codeIndex # regenerate docs/code-index.md and docs/error-codes.md
./gradlew codeIndexCheck # fail if those files are outdated or a KDoc summary is missing
python3 scripts/build_dependencies.py --check # fail if docs/review is outdated (CI runs it)
python3 scripts/build_code_doku.py --check # fail if docs/code-doku is outdated (CI runs it)
./gradlew -p build-logic test # tests of the code index generator
python3 scripts/build_dependencies.py # regenerate docs/review/ with every code change (dependency map; Python 3, no packages needed)
python3 scripts/build_code_doku.py # regenerate docs/code-doku/ with every code change (code documentation; Python 3, no packages needed)Before every pull request this must pass:
./gradlew assembleDebug lint detekt test codeIndexCheckNotes:
:core:security:testDebugUnitTestfails on a development machine (Android Keystore,IOExceptioninTokenFiles.kt); it is green in CI. Use--continueto see all other results, and read Detekt errors from lines likee: …MaxLineLengthin the output.- On Windows, stop the Gradle daemons after a build (
./gradlew --stop); a running daemon locks files inbuild/and the next build fails with "The process cannot access the file". - The
playandsideloadflavors differ only in how the app is distributed (concept 14.4). The release APK is signed from environment variables (section 10).
app/ Application, MainActivity, navigation graph; wires all modules together
core/common shared helpers, theme (HaacTheme), dispatchers, time
core/error ErrorCode, HaacException hierarchy, ErrorFactory, ErrorReporter
core/security keystore, crypto, biometrics
core/network HTTP, WebSocket, login, bridge channel, LAN discovery, address selection
core/database Room database, DAOs, entities (schemas in core/database/schemas)
feature/onboarding server entry, login
feature/instance instances, switching
feature/layout homes, levels (floors), rooms
feature/entities picker, room grid, controls, detail, history, sync, deactivating, switch guard
feature/notifications notification list incl. errors
feature/schedules schedule list, editor (repeat rules, preview), detail, sync, run log
feature/settings settings, about, licenses
build-logic/ convention plugins and the code index generator
config/detekt/ Detekt overrides
gradle/libs.versions.toml all versions; modules never declare versions themselves
docs/ concept.md, code-index.md, error-codes.md, mockups, icons, screenshots
docs/review/ GENERATED dependency map (dependencies.html, dependency-graph.html) by scripts/build_dependencies.py
docs/code-doku/ GENERATED code documentation (index.html) by scripts/build_code_doku.py
.github/workflows/ ci.yml, release.yml, codeql.yml
Dependency rules:
- A feature module depends on
core:commonandcore:error(added by its convention plugin) and on the othercore:*modules it needs. Features never depend on each other. Code two features need goes into acore:*module; they talk through interfaces defined there. :appdepends on everything. It holds the wiring plus the app-wide parts that need every feature: the lock (concept 5.5), the start routing (4.1), shortcuts (4.4) and the crash marker. Packages ofcoremodules may be split by sub-topic without the layer folders (app review K-06).
The root package is com.stacknoise.haac. Packages are organised by topic first, then by layer:
com.stacknoise.haac.<core|feature>.<topic>.<ui|domain|data|di>
For example com.stacknoise.haac.feature.layout.domain. A class lives in exactly one topic. ui holds screens, ViewModels and Compose; domain the pure rules and models; data repositories, database and network access; di the Hilt modules.
A module's build.gradle.kts only applies a convention plugin and lists dependencies; it contains no Android or Kotlin settings.
| Plugin | Use |
|---|---|
haac.android.application |
:app: flavors, signing from environment variables |
haac.android.library |
any library module: SDK levels, Kotlin options (warnings are errors), JUnit 5, Detekt |
haac.android.compose |
Compose (BOM) and Material 3 |
haac.android.feature |
a :feature:* module: library + Compose + Hilt + core:common + core:error |
haac.hilt |
Hilt and KSP |
To add a module: include(":feature:<topic>") in settings.gradle.kts, a build.gradle.kts with id("haac.android.feature"), and implementation(project(":feature:<topic>")) in app/build.gradle.kts. The namespace is derived from the Gradle path.
Rule: whenever the kind of an object depends on a type or on runtime data, a factory creates it. Outside a factory no code branches on the entity domain or the key type to construct objects. This keeps the places that need a change when Home Assistant gets a new domain down to one.
A factory is an interface with a default implementation, bound by Hilt, so tests can replace it with a fake:
/** Builds the controls of an entity from its domain, supported features and attributes. */
interface EntityControlFactory {
/** The control of [entity]'s tile in [state], or null if it has none. */
fun create(entity: ExposedEntity, state: EntityState): EntityControl?
}
/** [EntityControlFactory] for switch, sensor (no controls) and climate. */
class DefaultEntityControlFactory @Inject constructor() : EntityControlFactory {
override fun create(entity: ExposedEntity, state: EntityState): EntityControl? =
when (entity.domain) { // the only `when (domain)` that builds controls
EntityDomains.SWITCH -> toggle(state)
EntityDomains.CLIMATE -> ClimateControls(entity.supportedFeatures, state).targetTemperature()
else -> null
}
}
/** Bindings of the entities feature. */
@Module
@InstallIn(SingletonComponent::class)
abstract class EntitiesModule {
/** The controls of concept 8. */
@Binds
abstract fun bindEntityControlFactory(factory: DefaultEntityControlFactory): EntityControlFactory
}(Shortened from feature/entities/.../domain/EntityControlFactory.kt and .../di/EntitiesModule.kt.)
The factories of the app:
| Factory | Creates |
|---|---|
EntityControlFactory |
control model per entity domain (switch, sensor, climate) |
TileFactory |
tile spec with default size per domain |
HistoryChartFactory |
history query (states or statistics) and chart kind per entity |
ServiceCallFactory |
typed haac_bridge/call_service requests, checked against supported_features; only services and service_data keys of the bridge's list (concept 11.4) |
BridgeMessageFactory |
WebSocket commands with message IDs |
HaWebSocketFactory |
WebSocket to /api/websocket of one address |
KeyFactory / CipherFactory |
Keystore keys and ciphers |
InstanceSessionFactory |
per-instance session: HTTP client, WebSocket, token store for one serverId |
EndpointSelector |
the address of an instance to connect to |
ErrorFactory |
HaacException from any caught Throwable |
SavedStateHandle (no factory) |
ViewModels with navigation arguments (roomId, entityId); @AssistedFactory only for an argument the route does not carry |
Adding a factory:
- Interface and
Default…implementation in thedomain(ordata) package of its topic, both with KDoc. @Bindsin the topic'sdimodule.- A test with the cases per type; use a fake of the interface in the tests of its users.
- Add it to the table in concept 17.2 and regenerate the code index (section 5).
When a new entity domain is added, the change belongs in the factories above, not in screens or repositories.
Every error the app throws or passes on is a HaacException with an ErrorCode.
- All codes are defined in one file:
core/error/src/main/kotlin/com/stacknoise/haac/core/error/ErrorCode.kt. Nowhere else. - Format
HAAC-<AREA>-<NNN>. Areas:NET,AUTH,SEC,BRG,SYNC,DB,LAY,ENT,INST,DISC,SCH,APP. A code is never reused or renumbered. docs/error-codes.mdis generated fromErrorCode.ktand the string resources. Look codes up there; never edit it by hand.
An entry has a name that starts with its area, the code, a string resource for the user text, an action and a one-line technical description:
NET_UNREACHABLE(
"HAAC-NET-001",
R.string.error_net_unreachable,
ErrorAction.RETRY, // RETRY, SIGN_IN, OPEN_SETTINGS or NONE
"Connect or request to the server failed (DNS, timeout, refused, I/O)",
),Adding an error code
- Take the next free number of the area and add the enum entry in
ErrorCode.kt(not in the middle of existing numbering: never renumber). - Add the user text as
error_<name>tocore/error/src/main/res/values/strings.xmlandvalues-de/strings.xml. Short, plain language, says what happened and what to do; no technical terms, passwords, tokens or full URLs. An apostrophe in an Android string must be written\'; better rephrase. - Throw the matching exception subclass with the code, e.g.
throw ValidationException(ErrorCode.LAY_NAME_MISSING). The hierarchy:NetworkException,AuthException,KeystoreException,BridgeException,SyncException,StorageException,ValidationException(areas LAY, ENT, INST, DISC) andUnexpectedException(HAAC-APP-000). - Run
./gradlew codeIndexand commitdocs/error-codes.md. ErrorCodeTestchecks that codes are unique, match the format, have a text and a description, and that the name starts with the area. It must stay green.
Errors reported by the bridge carry a HAB code. ErrorFactory.fromBridgeError(habCode) maps it with the table DefaultErrorFactory.BRIDGE_CODES (the same table as concept 18.3); unknown HAB codes become HAAC-BRG-005. The HAB code stays on the exception (bridgeCode) and is shown in the detail sheet. When the bridge gets a new HAB code that reaches the app, update BRIDGE_CODES, the table in concept 18.3 and the bridge's APP_CODES.
Rules
- Never throw plain
Exception,IllegalStateExceptionorRuntimeException. - Catch low-level exceptions (
IOException,SSLException,SerializationException,SQLiteException,KeyPermanentlyInvalidatedException) at the data-layer boundary and convert them withErrorFactory.from(throwable). Room calls can useerrorFactory.database { … }. Code above the data layer only seesHaacException. - Never catch or wrap
CancellationException;ErrorFactory.fromrethrows it. - Never swallow an exception: either the UI handles it or it goes to
ErrorReporter.report(error, serverId), which creates the entry in the notification list (with the code). The same code within 10 minutes is grouped into one entry. - Errors that block the screen are additionally shown there, always with the code.
- Uncaught exceptions are recorded as
HAAC-APP-000byCrashMarker: only a marker file, never a stack trace or message (they could contain addresses or tokens).
docs/code-index.md lists every class and every function of the app with signature, file and a one-line description, grouped by package. It exists so that existing code is found and reused instead of written again.
- Before writing code, search
docs/code-index.mdfor a function or class with the same purpose. Reuse or extend it. - Every class and function, including private ones, has a one-line KDoc summary.
codeIndexCheckfails on a missing one. - After adding, renaming or removing a class or function:
./gradlew codeIndex, and commit the regenerateddocs/code-index.mdanddocs/error-codes.mdin the same commit. CI (codeIndexCheck) fails otherwise. - Never edit the two files by hand. After a merge or rebase conflict in
docs/code-index.md, take either side and regenerate it; never merge it by hand. - The generator lives in
build-logic(codeindex, task registered byCodeIndexConventionPlugin) and has its own tests (./gradlew -p build-logic test).
docs/code-doku/index.html is the code documentation: one self-contained page (open it in a browser) with an explorer (module, package, class, function) showing metrics, the KDoc and the source text, and a dependency map between packages and classes. The documentation must be updated with every code change: run python3 scripts/build_code_doku.py and commit the page in the same commit; CI (--check) fails if it is outdated. The page shows the KDoc, so change it when the behaviour changes. Metrics (lines, complexity, maintainability, Ca/Ce) are approximations of a source scanner, not a compiler analysis. The page template is scripts/code_doku_template.html; the same script and template are used in stacknoise/haac-bridge, keep them identical.
- Code needed in a second place is extracted into its own function at that moment, in the topic package or in
core:commonif several topics use it. - CI runs PMD CPD over
app/src,coreandfeatureand fails from 100 duplicated tokens. This includes tests: identical fakes (for example aScheduleDao) belong in one shared test class (FakeScheduleDao). - Detekt (
config/detekt/detekt.yml): documented public classes and functions, lines of at most 120 characters, no magic numbers (20.dpis allowed), top-level constants in PascalCase (StaleDelayMs), at most 11 functions per file. ViewModels with one small handler per input, DAOs and repositories with one small function per operation may exceed it with@Suppress("TooManyFunctions")and a comment that gives the reason (app review K-09); any other class is split. Compose functions are exempt from the length and naming rules. - The Kotlin compiler treats warnings as errors.
- Theme:
HaacTheme("Salbei", light and dark) lives in:core:common. The colour tokens are inHaacPalette;HaacColors.Xare@Composablegetters that read the current palette. Add a new colour as a token to the palette (light and dark), never asColor(0x…)in a screen. In draw lambdas (Canvas,drawBehind,DrawScopefunctions) read the colour first in the composable and pass it in as a parameter. - Strings: all UI text in
strings.xml, withvalues/(English) andvalues-de/(German, informal "Du"). Do not change German nouns withlowercase()in code; use a full string instead. Texts that Home Assistant sends (HVAC, fan and preset names) stay as sent. - Title lines: screen titles use
HaacScreenTitle(one line, shrinks to 24 sp). - Mockups under
docs/mockupsshow layout; the concept (chapter 15) and the built screens are the reference for colours and wording. - Launcher icons under
app/src/main/resare generated artefacts; replace them only on an explicit request for a new icon.
- Room database
HaacDatabasein:core:database; schemas are exported tocore/database/schemasand committed. A schema change needs a version bump, a migration and a migration test. Data of different HA instances is separated byserverId. - Settings that are not part of the database live in DataStore. No secrets in Room or DataStore; only the refresh token is stored, AES-GCM encrypted with an Android Keystore key.
- Tests: JUnit 5, MockK, Turbine, MockWebServer, Compose UI tests (concept 14.2). Test files mirror the package of the class they test. Use fakes of the factory interfaces and shared
Fake…classes.
mainis protected by rulesets: changes only by pull request, squash merge only, linear history, no force push or deletion, required checks (build/lint/detekt/tests, CPD, CodeQL with "high or higher" blocking).- Branches
feat/<topic>,fix/<topic>,docs/<topic>,chore/<topic>,ci/<topic>. Commit messages and PR titles follow Conventional Commits (feat:,fix:,docs:,chore:, optionally with a scope such asfeat(ui):). - Start every branch from the current
origin/main(git switch --no-track -c <name> origin/main) and push with upstream set. - Stacked PRs and squash merges: after the first PR is squash-merged, rebase the second one with
git rebase --onto origin/main <last commit of the first branch> <second branch>and push with--force-with-lease. - Workflows:
ci.yml(build, lint, Detekt, unit tests,codeIndexCheck, build-logic tests; a separate CPD job),codeql.yml(Kotlin with an explicit Gradle build, plus the workflow files),release.yml. - A GitHub default CodeQL setup and a CodeQL workflow in the repository exclude each other; this repository uses the workflow.
docs/concept.md here is the leading copy of the specification; stacknoise/haac-bridge holds an identical copy. A change goes first into this repository; after it is merged, the copy is taken over into the bridge repository in its own pull request (same blob). There is no other copy: the former online Claude Doc no longer exists. Read the matching chapter before changing behaviour; items in concept 14.5 ("Open points") are undecided: ask, or implement behind a clearly marked TODO.
- The version is
appVersioninapp/build.gradle.kts.versionNameequals it,versionCodeis derived (major * 10000 + minor * 100 + patch; 0.2.1 is 201). - Releasing:
- Raise
appVersionin its own pull request (chore(release): bump the version to X.Y.Z) and merge it. Update the status line of the README. - Check
mainonce more, then tag the merge commit:git tag -a vX.Y.Z <sha> -m vX.Y.Zandgit push origin vX.Y.Z. release.ymlbuildsassembleSideloadRelease, verifies the signature withapksignerand attacheshaac-vX.Y.Z-sideload.apkand its.sha256to the GitHub Release. It also builds the Play bundle (bundlePlayRelease), verifies its signature and keepshaac-vX.Y.Z-play.aabas a workflow artifact for 30 days (Actions run → Artifacts); the upload to Google Play is done by hand in the Play Console.
- Raise
- Tags
v*are protected (no deleting, moving or overwriting). A wrong tag cannot be corrected, so check the version first. - Signing: the keystore and passwords exist only as secrets of the GitHub environment
release(HAAC_KEYSTORE_BASE64,HAAC_KEYSTORE_PASSWORD,HAAC_KEY_ALIAS,HAAC_KEY_PASSWORD); the build reads them from environment variables. Never commit a keystore or*.jks. - A breaking change of a
haac_bridge/*command raises the bridgeapi_version; the app declares the range it supports.
- Never store, log or hard-code a password or token in plain text. No HTTP logging of
/auth/*requests, also in debug builds. - Fingerprint unlock uses
BiometricPromptwith aCryptoObject(Class 3); a UI-only check is not acceptable. - Login uses
client_idhttps://stacknoise.com/haac/andredirect_urihttps://stacknoise.com/haac/auth-callback. Do not change them; existing refresh tokens are bound to theclient_id. - The app talks to entities only through
haac_bridge/*WebSocket commands, never through Home Assistant's generic state and service APIs. - The bridge carries out only the services and
service_datakeys listed in concept 11.4 (others:HAB-SVC-002,HAB-WS-001). A new service or key inServiceCallFactoryneeds a bridge release that allows it first, and an entry in that table. - The bridge never sends attributes that name other entities or carry an access link (concept 11.3); the app must not depend on them.
- Local aliases, layout and tile sizes never write back to Home Assistant.
- Only add dependencies under Apache-2.0-compatible licenses (Apache-2.0, MIT, BSD), never GPL. No license headers in source files.