Use when adding a new screen or modifying navigation in the Alkaa project — triggers on tasks like "add a new screen", "navigate to X", "add destination", "wire up navigation", or "create a navigation event". Also triggers when connecting UI actions to routes in NavGraph.
Alkaa uses event-driven navigation: UI components send named action events, and the system resolves where to go. Navigation is never triggered directly from UI or ViewModels — it always flows through NavEventController.
| File | Package | Purpose |
|---|---|---|
*Event.kt | com.escodro.navigationapi.event | Defines action events |
*Destination.kt | com.escodro.navigationapi.destination | Defines typed routes |
*NavGraph.kt | feature module | Registers entries and sends events |
Both *Event.kt and *Destination.kt live in features/navigation-api. → See for Kotlin examples of all three files.
references/CODE_PATTERNS.mdOnEditClick, not NavigateToEdit) → see references/CODE_PATTERNS.md@Serializable; choose interface based on screen type → see references/CODE_PATTERNS.mdentry<Destination> block with appropriate transition spec → see references/CODE_PATTERNS.mdnavEventController.sendEvent() → see references/CODE_PATTERNS.md| Interface | When to use |
|---|---|
TopLevel | Bottom-nav root screens only (requires title, icon, @CommonParcelize) |
TopAppBarVisible | Dialogs, bottom sheets, non-full-screen destinations |
| Neither | Regular full-screen push destinations |
Also register TopLevel and TopAppBarVisible destinations in the corresponding sets in Destination.kt.
On*Click, On*Save)@SerializableTopLevel only for bottom-nav root screens (with @CommonParcelize, title, icon)TopAppBarVisible only for dialogs/sheets/non-full-screenTopLevel/TopAppBarVisible destinations registered in Destination.kt setsentry<> block exists for each new destinationEvent.OnBack, not custom events| Mistake | Fix |
|---|---|
navEventController.sendEvent() in a ViewModel | Must not leave the NavGraph — pass navigation as lambda callbacks instead |
navEventController.sendEvent() inside a @Composable | Move to NavGraph entry<> block via lambda callback |
Event named NavigateToDetail or GoToSettings | Name after the action: OnDetailClick, OnSettingsClick |
Destination without @Serializable | Add annotation — Navigation3 requires it |
Full-screen destination with TopAppBarVisible | Remove — use only for dialogs/sheets |
New feature with no NavGraph implementation | Create *NavGraph.kt and bind in Koin module |