# eygraber/vice architecture

> Architecture diagram of the GitHub repository eygraber/vice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eygraber/vice
- Repository: https://github.com/eygraber/vice

## Overview

##### Main Components
- Repository/CI layer
– GitHub (push to branches, GitHub Actions workflows)
– Publishing to Maven Central/Sonatype
- Modules (library components)
– vice-core: UDF runtime, ViceContainer, ViceCompositor, ViceView, ViceEffects
– vice-sources: StateSource, FlowSource, LoadableSource, etc.
– vice-nav: navigation primitives (ViceDestination, NavGraphBuilder extensions)
– vice-nav-material3: Material3-specific NavGraphBuilder integrations
– vice-portal: ’portal’ integration entrypoint
- Sample Applications
– samples/nav/androidApp: Android Compose application
– samples/nav/desktopApp: Compose Multiplatform desktop app
– samples/nav/wasmJsApp: Compose-for-WASM/JS web app
– samples/nav/shared: shared logic & UI between sample apps
- External Services/Frameworks
– Kotlin Multiplatform & Gradle
– Compose Multiplatform (AndroidX Compose, Desktop Compose, WASM/JS)
– kotlinx.coroutines (Flow, StateFlow)
– AndroidX Navigation Compose (for vice-nav integration)

##### Relationships & Data Flows
- Library Modules → MavenCentral
– Each module compiles to KMP artifacts and publishes to Maven
- Sample Apps → Library Modules
– Each sample app depends on vice-core, vice-sources, vice-nav (and material3) via Gradle
- Runtime Flow in an App
– App’s UI calls ViceContainer.Vice(...) → instantiates ViceCompositor + ViceEffects + ViceSources
– ViceCompositor.composite() reads currentState() from multiple ViceSources (StateSource, FlowSource…)
– ViceCompositor emits ViewState → delivered to ViceView composable
– ViceView renders UI, emits Intents (user events) back to ViceContainer
– ViceContainer dispatches Intents to ViceCompositor.onIntent() and to any ViceIntentFilters
– ViceEffects.runEffects() handles side-effects (analytics, lifecycle, navigation)

##### Architectural Patterns
- Unidirectional Data Flow (UDF)
- Model-View-Intent (MVI)
- Compose-based reactive rendering (ViceView)
- Strict separation of state (ViewState), events (Intent), side-effects (ViceEffects)
- Modularization for extensibility (core vs. navigation vs. sources)
- KMP layering (commonMain → platformMain for each target)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI / Pipeline
    subgraph "CI / Pipeline"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        PublishSnapshot["publish_snapshot_release.yml"]:::ci
        PublishRelease["publish_release.yml"]:::ci
    end

    %% Library Modules
    subgraph "Library Modules"
        direction TB
        ViceCore["vice-core"]:::core
        ViceSources["vice-sources"]:::core
        ViceNav["vice-nav"]:::core
        ViceNavM3["vice-nav-material3"]:::core
        VicePortal["vice-portal"]:::core
    end

    %% Sample Applications
    subgraph "Sample Apps"
        direction TB
        SharedSample["shared (samples/nav/shared)"]:::sample
        AndroidApp["androidApp"]:::sample
        DesktopApp["desktopApp"]:::sample
        WasmJsApp["wasmJsApp"]:::sample
    end

    %% External Frameworks
    subgraph "External Frameworks"
        direction TB
        KotlinMP["Kotlin Multiplatform"]:::external
        ComposeMP["Compose Multiplatform"]:::external
        Coroutines["kotlinx.coroutines"]:::external
        NavCompose["AndroidX Navigation Compose"]:::external
    end

    %% Build-time Dependencies
    GitHubActions -->|triggers| ViceCore
    GitHubActions -->|triggers| ViceSources
    GitHubActions -->|triggers| ViceNav
    GitHubActions -->|triggers| ViceNavM3
    GitHubActions -->|triggers| VicePortal
    ViceCore -->|publishes KMP artifact| MavenCentral["Maven Central"]:::external
    ViceSources -->|publishes KMP artifact| MavenCentral
    ViceNav -->|publishes KMP artifact| MavenCentral
    ViceNavM3 -->|publishes KMP artifact| MavenCentral
    VicePortal -->|publishes KMP artifact| MavenCentral

    AndroidApp -->|depends on| ViceCore
    AndroidApp -->|depends on| ViceSources
    AndroidApp -->|depends on| ViceNav
    AndroidApp -->|depends on| ViceNavM3
    AndroidApp -->|depends on| SharedSample

    DesktopApp -->|depends on| ViceCore
    DesktopApp -->|depends on| ViceSources
    DesktopApp -->|depends on| ViceNav
    DesktopApp -->|depends on| ViceNavM3
    DesktopApp -->|depends on| SharedSample

    WasmJsApp -->|depends on| ViceCore
    WasmJsApp -->|depends on| ViceSources
    WasmJsApp -->|depends on| ViceNav
    WasmJsApp -->|depends on| ViceNavM3
    WasmJsApp -->|depends on| SharedSample

    SharedSample -->|uses| ViceCore
    SharedSample -->|uses| ViceSources

    KotlinMP -->|platform| ViceCore
    KotlinMP -->|platform| ViceSources
    KotlinMP -->|platform| ViceNav
    KotlinMP -->|platform| ViceNavM3
    KotlinMP -->|platform| VicePortal

    ComposeMP -->|UI layer| ViceCore
    ComposeMP -->|UI layer| AndroidApp
    ComposeMP -->|UI layer| DesktopApp
    ComposeMP -->|UI layer| WasmJsApp

    Coroutines -->|flow/state| ViceSources
    NavCompose -->|integration| ViceNav

    %% Runtime Flow
    subgraph "Runtime Flow" 
        direction TB
        ViewState["ViewState"]:::runtime
        ViceView["ViceView"]:::runtime
        Intent["Intent"]:::runtime
        ViceContainer["ViceContainer"]:::runtime
        ViceCompositor["ViceCompositor"]:::runtime
        ViceEffects["ViceEffects"]:::runtime
        ViceSourceRuntime["ViceSource(s)"]:::runtime
    end

    ViewState -.->|renders| ViceView
    ViceView -.->|emits| Intent
    Intent -.->|sent to| ViceContainer
    ViceContainer -.->|initializes| ViceCompositor
    ViceContainer -.->|dispatches| ViceEffects
    ViceCompositor -.->|reads| ViceSourceRuntime
    ViceSourceRuntime -.->|provides| ViewState
    ViceEffects -.->|handles| Intent

    %% Click Events
    click PublishRelease "https://github.com/eygraber/vice/blob/master/.github/workflows/publish_release.yml"
    click PublishSnapshot "https://github.com/eygraber/vice/blob/master/.github/workflows/publish_snapshot_release.yml"

    click ViceContainer "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/ViceContainer.kt"
    click ViceCompositor "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/ViceCompositor.kt"
    click ViceView "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/ViceView.kt"
    click ViceEffects "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/ViceEffects.kt"
    click ViceSource "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/ViceSource.kt"
    click ViceIntentFilter "https://github.com/eygraber/vice/blob/master/vice-core/src/commonMain/kotlin/com/eygraber/vice/filter/ViceIntentFilter.kt"

    click StateSource "https://github.com/eygraber/vice/blob/master/vice-sources/src/commonMain/kotlin/com/eygraber/vice/sources/StateSource.kt"
    click FlowSource "https://github.com/eygraber/vice/blob/master/vice-sources/src/commonMain/kotlin/com/eygraber/vice/sources/FlowSource.kt"
    click LoadableSource "https://github.com/eygraber/vice/blob/master/vice-sources/src/commonMain/kotlin/com/eygraber/vice/sources/LoadableSource.kt"
    click ViceLoadable "https://github.com/eygraber/vice/blob/master/vice-sources/src/commonMain/kotlin/com/eygraber/vice/loadable/ViceLoadable.kt"

    click ViceDestination "https://github.com/eygraber/vice/blob/master/vice-nav/src/commonMain/kotlin/com/eygraber/vice/nav/ViceDestination.kt"
    click ViceNavGraphBuilder "https://github.com/eygraber/vice/blob/master/vice-nav/src/commonMain/kotlin/com/eygraber/vice/nav/ViceNavGraphBuilder.kt"
    click SharedTransitions "https://github.com/eygraber/vice/blob/master/vice-nav/src/commonMain/kotlin/com/eygraber/vice/nav/SharedTransitions.kt"

    click ViceMaterial3NavGraphBuilder "https://github.com/eygraber/vice/blob/master/vice-nav-material3/src/commonMain/kotlin/com/eygraber/vice/nav/material3/ViceMaterial3NavGraphBuilder.kt"

    click VicePortal "https://github.com/eygraber/vice/blob/master/vice-portal/src/commonMain/kotlin/com/eygraber/vice/portal/VicePortal.kt"

    click AndroidApp "https://github.com/eygraber/vice/blob/master/samples/nav/androidApp/src/main/kotlin/com/eygraber/vice/samples/nav/android/SampleNavActivity.kt"
    click DesktopApp "https://github.com/eygraber/vice/blob/master/samples/nav/desktopApp/src/main/kotlin/com/eygraber/vice/samples/nav/desktop/SampleNavDesktopApp.kt"
    click WasmJsApp "https://github.com/eygraber/vice/blob/master/samples/nav/wasmJsApp/src/wasmJsMain/kotlin/SampleNavWasmJsApplication.kt"

    click SharedSample "https://github.com/eygraber/vice/blob/master/samples/nav/shared/src/commonMain/kotlin/com/eygraber/vice/samples/nav/shared/App.kt"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef sample fill:#DFF5D0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE8B0,stroke:#333,stroke-width:1px
    classDef ci fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef runtime fill:#F0F0F0,stroke:#666,stroke-width:1px,stroke-dasharray: 3 3
```
