From fef2aa6df4cdf64090508a534f05bfb85d6c9323 Mon Sep 17 00:00:00 2001 From: Alexis Tercero Date: Mon, 10 Aug 2026 14:12:05 -0600 Subject: [PATCH 1/5] NEW | #32 CI/CD and Build Updates - Fix Test report - REVIEW - NEW Release Action --- .github/workflows/android.yml | 6 ++--- .github/workflows/release.yml | 46 +++++++++++++++++++++++++++++++++++ gradle.properties | 5 ++-- 3 files changed, 51 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml index 3bccf1b..0e61dec 100644 --- a/.github/workflows/android.yml +++ b/.github/workflows/android.yml @@ -3,9 +3,9 @@ name: Android Debug CI/CD Rho.Studio® on: workflow_dispatch: push: - branches: [ "27-plan-domain-layer-use-case-implementation" ] + branches: [ " " ] pull_request: - branches: [ "dev" , "pre-release" , "main" ] + branches: [ "dev" , "pre-release" ] jobs: build: @@ -43,4 +43,4 @@ jobs: uses: actions/upload-artifact@v7.0.1 with: name: test-reports - path: app/build/reports/tests/ + path: "**/build/reports/tests/" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..2f3e14e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,46 @@ +name: Android Release Rho.Studio® + +on: + workflow_dispatch: + push: + branches: [ "Pre-release-v102" ] + pull_request: + branches: [ "main" ] + +jobs: + build: + name: Build and Release Rho.Studio® + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v6.1.0 + + - name: Set up JDK 17 + uses: actions/setup-java@v5.5.0 + with: + java-version: '17' + distribution: 'temurin' + cache: gradle + + - name: Grant execute permission for gradlew + run: chmod +x gradlew + + - name: Run Unit Tests + run: ./gradlew test + + - name: Build with Gradle + run: ./gradlew assembleDebug + + - name: Upload APK + uses: actions/upload-artifact@v7.0.1 + with: + name: Rho-Studio-UI + path: app/build/outputs/apk/debug/RhoStudioUI.apk + + - name: Upload Test Reports + if: always() + uses: actions/upload-artifact@v7.0.1 + with: + name: test-reports + path: "**/build/reports/tests/" diff --git a/gradle.properties b/gradle.properties index 0a9d59b..ae9a532 100644 --- a/gradle.properties +++ b/gradle.properties @@ -26,9 +26,8 @@ android.defaults.buildfeatures.resvalues=false android.sdk.defaultTargetSdkToCompileSdkIfUnset=true android.usesSdkInManifest.disallowed=true android.uniquePackageNames=false -android.dependency.useConstraints=true +android.dependency.useConstraints=false android.r8.strictFullModeForKeepRules=false android.r8.optimizedResourceShrinking=true -android.dependency.excludeLibraryComponentsFromConstraints=true android.generateSyncIssueWhenLibraryConstraintsAreEnabled=false -android.sync.suppressAgpWarnings=LIBRARY_CONSTRAINTS_SHOULD_BE_DISABLED +android.sync.suppressAgpWarnings=LIBRARY_CONSTRAINTS_SHOULD_BE_DISABLED,UNSUPPORTED_PROJECT_OPTION_USE From ce95fe9453fbbce3350be05f079be3e76db28038 Mon Sep 17 00:00:00 2001 From: Alexis Tercero Date: Mon, 10 Aug 2026 14:38:06 -0600 Subject: [PATCH 2/5] UPDATE | #32 CI/CD named app --- .github/workflows/android.yml | 2 +- .github/workflows/release.yml | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml index 0e61dec..f57bac3 100644 --- a/.github/workflows/android.yml +++ b/.github/workflows/android.yml @@ -39,7 +39,7 @@ jobs: path: app/build/outputs/apk/debug/app-debug.apk - name: Upload Test Reports - if: always() + if: failure() uses: actions/upload-artifact@v7.0.1 with: name: test-reports diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2f3e14e..e5f2178 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,6 +32,24 @@ jobs: - name: Build with Gradle run: ./gradlew assembleDebug + # Debug: list the APK directory to see what was produced + - name: List APK directory + run: | + echo "Contents of app/build/outputs/apk/debug:" + ls -la app/build/outputs/apk/debug/ || echo "Directory not found" + + # Rename the APK (handle different possible names) + - name: Rename APK + run: | + APK_DIR="app/build/outputs/apk/debug" + # Find any .apk file (ignore if multiple, but take the first) + APK_FILE=$(find "$APK_DIR" -maxdepth 1 -name "*.apk" | head -n 1) + if [ -n "$APK_FILE" ]; then + echo "Found APK: $APK_FILE" + mv -v "$APK_FILE" "$APK_DIR/RhoStudioUI.apk" + else + echo "No APK found!" && exit 1 + - name: Upload APK uses: actions/upload-artifact@v7.0.1 with: @@ -39,7 +57,7 @@ jobs: path: app/build/outputs/apk/debug/RhoStudioUI.apk - name: Upload Test Reports - if: always() + if: failure() uses: actions/upload-artifact@v7.0.1 with: name: test-reports From c1b9a9cb6fc82177944b2ba214b648c7feb1a8ae Mon Sep 17 00:00:00 2001 From: Alexis Tercero Date: Mon, 10 Aug 2026 14:42:46 -0600 Subject: [PATCH 3/5] FIX | #32 CI/CD named app FIX --- .github/workflows/release.yml | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e5f2178..c586309 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,23 +32,11 @@ jobs: - name: Build with Gradle run: ./gradlew assembleDebug - # Debug: list the APK directory to see what was produced - name: List APK directory - run: | - echo "Contents of app/build/outputs/apk/debug:" - ls -la app/build/outputs/apk/debug/ || echo "Directory not found" + run: ls -la app/build/outputs/apk/debug/ - # Rename the APK (handle different possible names) - name: Rename APK - run: | - APK_DIR="app/build/outputs/apk/debug" - # Find any .apk file (ignore if multiple, but take the first) - APK_FILE=$(find "$APK_DIR" -maxdepth 1 -name "*.apk" | head -n 1) - if [ -n "$APK_FILE" ]; then - echo "Found APK: $APK_FILE" - mv -v "$APK_FILE" "$APK_DIR/RhoStudioUI.apk" - else - echo "No APK found!" && exit 1 + run: mv app/build/outputs/apk/debug/app-debug.apk app/build/outputs/apk/debug/RhoStudioUI.apk - name: Upload APK uses: actions/upload-artifact@v7.0.1 From 74b774493833b4ad8ac1bb16e3d5404c3d93ab63 Mon Sep 17 00:00:00 2001 From: Alexis Tercero Date: Mon, 10 Aug 2026 17:54:23 -0600 Subject: [PATCH 4/5] UPDATE | #32 Release set up done. --- README.md | 386 ++++++++++++++---- .../rho/studio/ui/features/home/HomeScreen.kt | 3 +- .../studio/ui/features/home/HomeViewModel.kt | 4 +- .../features/home/components/ServiceItem.kt | 2 +- 4 files changed, 320 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 5572b7a..637a918 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,352 @@ -# Technical Report: Rho Studio UI Architecture -## Modern Android Development with Jetpack Compose & MVVM -This report outlines the architecture design of the Rho Studio UI application. +# Technical Report: Rho Studio UI +An Android Jetpack Compose app. -Image +[![Android CI/CD Rho.Studio®](https://github.com/Rho-Studio/UI-Utils-Rho-Studio/actions/workflows/android.yml/badge.svg)](https://github.com/Rho-Studio/UI-Utils-Rho-Studio/actions/workflows/android.yml) +[![Android Release Rho.Studio®](https://github.com/Rho-Studio/UI-Utils-Rho-Studio/actions/workflows/release.yml/badge.svg)](https://github.com/Rho-Studio/UI-Utils-Rho-Studio/actions/workflows/release.yml) -## Contributions +> _Document Version: 2.0 Last Updated: August 10, 2026_ +## Enterprise-Grade Android Architecture with Jetpack Compose -Must follow the next requirements [CONTRIBUTION.md](CONTRIBUTION.md) +This document provides a comprehensive technical overview of the **Rho Studio UI** application. It serves as the primary architectural reference for developers, outlining the system's design, layer responsibilities, and technical standards. + +App Screenshot --- ## 1. Executive Summary -The application is a pure **Jetpack Compose** implementation following a **Single-Activity Architecture**. It leverages a reactive **MVVM (Model-View-ViewModel)** pattern to ensure a clean separation of concerns, testability, and a fluid user experience driven by Unidirectional Data Flow (UDF). +Rho Studio UI is the **base application template** designed to establish and enforce the **Rho Studio Android App Standards**. It provides a robust foundation for building secure, authenticated mobile experiences within the Rho Studio ecosystem. + +The application is a pure **Jetpack Compose** implementation following a **Single-Activity Architecture**, leveraging a reactive **MVVM (Model-View-ViewModel)** pattern to ensure a clean separation of concerns, testability, and a fluid user experience driven by **Unidirectional Data Flow (UDF)**. This architectural foundation ensures a focus on **Fluid UX**, **Transactional Integrity**, and **Decoupled Business Logic**. + +### Core Features: +- **Secure Authentication**: Robust login flow with real-time validation and session lifecycle management, following corporate security protocols. +- **Adaptive Home Experience**: A responsive home interface that dynamically adjusts to different service modules and device form factors. +- **Brand Consistency**: A centralized design system leveraging Material 3 to reflect the Rho Studio corporate identity across all derived applications. --- -## 2. Integrated Architectural Perspective -The project utilizes a **Feature-Layered Architecture**. Each feature is encapsulated within its own package, maintaining a clean internal separation between UI (Compose) and Logic (ViewModels), while sharing a common Core/Data foundation. +## 2. Architectural Framework +The application follows a **Single-Activity Architecture** and is structured according to **Clean Architecture** principles. It utilizes a **Feature-Layered Modularization** strategy to ensure scalability and maintainability. -### 2.1 UI & Feature Layers (View) -The UI is composed of stateless screens and modular components that observe state from their respective ViewModels. +### 2.1 Layered Structure +The system is divided into three primary logical layers, enforcing a strict unidirectional dependency flow: **UI → Domain ← Data**. -- **`MainActivity.kt`**: The application's core orchestrator. Manages the high-level `NavHost`, coordinates the global `LoadingOverlay`, and synchronizes navigation via `SessionManager`. -- **Authentication Feature (`features/auth/`)**: - - `LoginScreen.kt`: The main entry point for user authentication. - - `LoginEmailField.kt` / `LoginPasswordField.kt`: Specialized inputs with built-in validation and security logic. -- **Home & Dashboard Feature (`features/home/`)**: - - `HomeScreen.kt`: The primary post-auth landing page. - - `ServiceList.kt` / `ServiceItem.kt`: Adaptive components for dynamic content delivery. -- **Common UI Feature (`features/common/`)**: - - `PageHeader.kt` / `PageFooter.kt`: Shared layouts that provide global context and actions (e.g., Logout). +```mermaid +graph TD + subgraph "UI Layer (Presentation)" + UI[Jetpack Compose Screens] + VM[ViewModels] + Nav[Navigation / NavHost] + end -### 2.2 Business Logic & State Layer (ViewModel) -ViewModels act as the bridge between features and the data layer, handling user intent and reactive state. + subgraph "Domain Layer (Business Logic)" + UC[Use Cases / Interactors] + Entities[Domain Entities] + Int[Repository Interfaces] + end -- **`BaseViewModel.kt`**: The architectural anchor providing unified loading states, toast messaging, and standardized error handling. -- **`LoginViewModel.kt`**: Manages complex form state and **debounced validation** logic. -- **`HomeViewModel.kt`**: Orchestrates dashboard content lifecycle and session termination. -- **`HeaderViewModel.kt`**: Bridges the `SessionManager` state to common UI components like the `PageHeader`. + subgraph "Data Layer (Infrastructure)" + Repo[Repository Implementations] + SM[Session Manager] + Local[Local / Network Data Sources] + end -### 2.3 Core Data & Infrastructure Layer -Provides the essential services and "Single Source of Truth" for the entire application. + UI --> VM + VM --> UC + UC --> Entities + UC --> Int + Repo -.-> Int + Repo --> SM + Repo --> Local +``` -- **`SessionManager.kt`**: A singleton coordinator for the application's global authentication state and user profile. -- **`SessionRepository.kt`**: Manages persistent storage and retrieval of session tokens and user data. -- **`Credentials.kt` / `User.kt` / `ServiceModule.kt`**: Strongly typed data models that enforce business rules and schema consistency. +### 2.2 Multi-Module Topology +We have moved away from a monolithic `:app` structure to a **Feature-Layered Modularization** strategy. This optimizes build parallelization and enforces strict dependency inversion. +```mermaid +flowchart TD + APP[":app
MainActivity, NavHost"] + + AUTH[":features:auth
LoginScreen, LoginViewModel"] + HOME[":features:home
HomeScreen, HomeViewModel"] + + UI_CORE[":core:ui
Theme, Common Composables"] + DOMAIN[":core:domain
Use Cases, Models, Contracts"] + DATA[":core:data
Repositories, SessionManager"] + + APP --> AUTH + APP --> HOME + + AUTH --> UI_CORE + AUTH --> DOMAIN + HOME --> UI_CORE + HOME --> DOMAIN + + UI_CORE --> DOMAIN + + DOMAIN -.->|"implemented by"| DATA + + style APP fill:#e94560,stroke:#c62828,color:#ffffff + style AUTH fill:#1a1a2e,stroke:#e94560,color:#ffffff + style HOME fill:#1a1a2e,stroke:#e94560,color:#ffffff + style UI_CORE fill:#16213e,stroke:#0f3460,color:#ffffff + style DOMAIN fill:#0f3460,stroke:#16213e,color:#ffffff + style DATA fill:#1a1a2e,stroke:#e94560,color:#ffffff +``` +> **Key Principle**: `:features` depend only on `:core` modules (`:core:domain`, `:core:ui`), preventing circular dependencies. Feature-specific models remain within their respective feature modules, adhering to the Interface Segregation Principle. --- -## 3. Core Technical Implementations +## 3. Layer Detail & Responsibilities -### 3.1 State-Driven Reactive Navigation -Navigation is decoupled from direct user input. `MainActivity.kt` observes the `isAuthenticated` state from `SessionManager.kt`. When this state changes, a `LaunchedEffect` executes the transition, ensuring the UI is always a reflection of the underlying session state. +### 3.1 UI Layer (Presentation) +**Goal**: Transform application state into a visual interface and handle user interactions. +- **Jetpack Compose**: All UI is declarative, using stateless composables for maximum testability. +- **MVVM Pattern**: ViewModels manage UI state using `StateFlow`, exposing it to the UI in a lifecycle-aware manner. +- **UDF (Unidirectional Data Flow)**: User actions trigger events in the ViewModel, which updates the state, triggering a UI recomposition. +- **Side-Effect Orchestration**: `MainActivity` uses `LaunchedEffect` keyed to authentication state, transforming state changes into one-time navigation events. +- **Key Components**: + - `MainActivity.kt`: The entry point and navigation orchestrator. + - `LoginViewModel.kt` & `HomeViewModel.kt`: Feature-specific state holders. + - `BaseViewModel.kt`: Provides shared logic for loading states, error handling, and navigation side-effects. + - `HeaderViewModel.kt`: Bridges `SessionManager` state to common UI components +```mermaid +flowchart TB + subgraph Navigation["Navigation Orchestration"] + MA["MainActivity.kt
- NavHost
- Session-based routing"] + end + + subgraph Shared["Shared UI Components"] + PV["BaseViewModel.kt
- Loading states
- Error handling"] + HV["HeaderViewModel.kt
- Session state bridging"] + PH["PageHeader.kt"] + PF["PageFooter.kt"] + end + + subgraph Auth["Authentication Feature"] + LS["LoginScreen.kt"] + LVM["LoginViewModel.kt
- Form state
- Debounced validation"] + end + + subgraph Home["Home Feature"] + HS["HomeScreen.kt"] + HVM["HomeViewModel.kt
- Home state
- Session termination"] + end + + MA --> LS + MA --> HS + LS --> LVM + HS --> HVM + LVM --> PV + HVM --> PV + HV --> PV + + style Navigation fill:#e94560,stroke:#c62828,color:#ffffff + style Shared fill:#16213e,stroke:#0f3460,color:#ffffff + style Auth fill:#1a1a2e,stroke:#e94560,color:#ffffff + style Home fill:#1a1a2e,stroke:#e94560,color:#ffffff +``` -### 3.2 Performance Optimized Validation -To ensure a smooth typing experience, `LoginViewModel.kt` utilizes **Coroutine Debouncing**. Input validation is deferred until the user pauses for 300ms, minimizing unnecessary UI updates and logic execution. - -### 3.3 Centralized Design System -Managed in `ui/theme/`, the app uses a custom Material 3 implementation. This ensures brand consistency (`RhoRed`, `RhoStrongGray`) is automatically applied to all features through a unified `Theme.kt` and `Color.kt` definition. +### 3.2 Domain Layer (Business Logic) +**Goal**: House the platform-agnostic business rules and "truth" of the application. +- **Pure Kotlin**: This layer has zero dependencies on the Android Framework (no `Context`, no `Parcelable`). +- **Use Cases (Interactors)**: Each business action is encapsulated in a dedicated Use Case (e.g., `LoginUseCase`). This promotes the Single Responsibility Principle and makes logic reusable across ViewModels. +- **Entities**: Data classes like `User` and `Credentials` represent the core business models. +- **Key Components**: + - `BaseUseCase`: Standardizes execution context (Coroutines) and error handling. + - `SessionManagerInterface`: Defines the contract for session operations without revealing implementation details. + - `LoginUseCase`: Encapsulates the authentication transaction. + - `LogoutUseCase`: Orchestrates atomic session teardown. +### 3.3 Data Layer (Infrastructure) +**Goal**: Manage data acquisition, persistence, and external service coordination. +- **Repository Pattern**: Acts as a mediator between different data sources (Network, Database) and the Domain Layer. +- **Session Management**: `SessionManager` serves as the Single Source of Truth (SSOT) for the user's authentication state, exposing `StateFlow` for the UI to observe. +- **Current Implementation**: Uses `SharedPreferences` with `Gson` serialization for persistence and mock authentication for development. +- **Key Components**: + - `SessionManager.kt`: Singleton coordinator for authentication state and user profile. + - `SessionRepository.kt`: Coordinates data retrieval strategies. + - `SessionRepositoryImpl.kt`: Manages persistent storage using SharedPreferences. Migrated to Room Database in the future. + - `AuthRepositoryImpl.kt`: Mock implementation (**temporary**) simulating network delay and user creation. Replaced by Firebase Auth in the future. +```mermaid +flowchart TB + subgraph SSOT["Single Source of Truth"] + SM["SessionManager.kt
- AuthState Flow
- updateSession()
- clearSession()"] + end + + subgraph Repos["Repository Implementations"] + ARI["AuthRepositoryImpl
- Mock login()"] + SRI["SessionRepositoryImpl
- SharedPreferences"] + end + + subgraph Sources["Data Sources (Planned)"] + Remote["Remote API
- Firebase Auth"] + Local["Local Storage
- Room Database"] + end + + SM --> SRI + ARI --> Remote + SRI --> Local + + style SSOT fill:#e94560,stroke:#c62828,color:#ffffff + style Repos fill:#1a1a2e,stroke:#e94560,color:#ffffff + style Sources fill:#0f3460,stroke:#16213e,color:#ffffff +``` --- -## 4. File Registry & Responsibilities +## 4. Technical Implementation Standards -| File | Feature | Primary Engineering Responsibility | -| :--- | :--- | :--- | -| `MainActivity.kt` | App Root | Global orchestration, NavHost, and session-based routing. | -| `BaseViewModel.kt` | Core | Shared architectural logic for Loading/Error states. | -| `SessionManager.kt` | Core | Centralized authentication and session lifecycle management. | -| `LoginViewModel.kt` | Auth | Form state management and debounced validation. | -| `HomeScreen.kt` | Home | Root layout for the post-authentication dashboard. | -| `ServiceList.kt` | Home | Efficient grid implementation for platform modules. | -| `Credentials.kt` | Core | Logic-heavy model for credential validation rules. | -| `Theme.kt` | Design | Global Material 3 theme configuration and brand mapping. | +### 4.1 Reactive Orchestration +The application uses **Kotlin Coroutines and Flow** for all asynchronous operations. +- **State-Driven Navigation**: `MainActivity` observes `SessionManager.isAuthenticated`; state changes trigger navigation transitions via `LaunchedEffect`. +- **Debounced Validation**: Login inputs are validated using a 300ms debounce to optimize performance. +- **State Pushing**: ViewModels push immutable state objects to the UI, ensuring that recompositions are predictable and efficient. +```mermaid +sequenceDiagram + participant UI as MainActivity + participant SM as SessionManager + participant Nav as NavController + + UI->>SM: collectAsState() + SM-->>UI: AuthState (Unauthenticated) + UI->>Nav: navigate to Login + + Note over UI,Nav: User clicks Login + UI->>LoginViewModel: onLoginClicked() + LoginViewModel->>LoginUseCase: login(email, password) + LoginUseCase->>AuthRepository: login(credentials) + AuthRepository-->>LoginUseCase: User + LoginUseCase->>SessionManager: updateSession(user) + + SM-->>UI: AuthState (Authenticated) + UI->>Nav: navigate to Home +``` ---- +### 4.2 Modularization Strategy +The project is split into granular Gradle modules to improve build times and enforce architectural boundaries: +- `:app`: The main coordinator and DI root. +- `:features:*`: Feature-specific UI and ViewModels (e.g., `:features:auth`, `:features:home`). +- `:core:ui`: Shared design system components and theming. +- `:core:domain`: The platform-agnostic business layer. +- `:core:data`: Implementation details for data and external services. -## 5. Path to Enterprise-Grade Architecture +### 4.3 Design System +Located in `:core:ui`, the design system defines the application's visual language: +- **Typography**: Custom typeface integration. +- **Color Palette**: Strict adherence to the Rho Studio brand (`RhoRed`, `RhoStrongGray`). +- **Components**: A library of reusable, styleable components (Buttons, Inputs, Cards). -To transition this foundation into a highly scalable, enterprise-grade application, the following architectural advancements are planned to manage complex business flows and transactional integrity. +--- + +## 5. Roadmap & Evolution: Strategic Phases -### 5.1 Domain Layer & Use Case Implementation -As business logic complexity grows, direct ViewModel-to-Repository interaction is being transitioned to a dedicated **Domain Layer**. -- **Use Cases (Interactors)**: Classes like `LoginUseCase.kt` (`core/domain/usecase/LoginUseCase.kt`) encapsulate specific business rules, making the logic reusable across different ViewModels and testable in isolation. -- **Business Transaction Flow**: A single user action (e.g., "Login") may involve multiple steps: credential validation -> token acquisition -> user profile synchronization. These are managed as atomic transactions within the Domain Layer. -- **Best Practice**: [Android Guide to the Domain Layer](https://developer.android.com/topic/architecture/domain-layer) +The application is transitioning from a modular prototype to a production-hardened system. The evolution is structured into three strategic phases: -### 5.2 Advanced Data Flow & Synchronization -Enterprise apps require robust data handling beyond simple memory state. -- **Repository Pattern**: Refined `SessionRepository.kt` and future repositories will implement a **Single Source of Truth (SSOT)** strategy, coordinating between local storage (Room) and remote APIs (Retrofit). -- **Reactive Stream Transactions**: Utilizing **Kotlin Flow** for end-to-end reactive streams. Transactions are modeled as immutable states flowing from the Data Layer to the UI. -- **Best Practice**: [Data Layer with Repositories](https://developer.android.com/topic/architecture/data-layer) +### Phase I: Dependency Orchestration & Decoupling +- **Dagger Migration**: Implementation of **Dagger 2** to replace manual Service Locators. + - Define `@Component` and `@Module` boundaries for `:core` and `:features`. + - Implement `@Inject` for UseCase and ViewModel construction to ensure compile-time dependency safety. +- **Interface Segregation**: Strict enforcement of domain-defined interfaces to further isolate the Data Layer from Business Logic. -### 5.3 Scalability & Reliability Standards -- **Dependency Injection (Hilt)**: Moving from manual singleton management to **Dagger Hilt** for better decoupling and automated lifecycle management. -- **Modularization**: Splitting the current feature packages into independent Gradle modules (`:feature:auth`, `:feature:home`, `:core:data`) to improve build times and enforce strict visibility boundaries. -- **Best Practice**: [Guide to App Modularization](https://developer.android.com/topic/modularization) +### Phase II: Transactional Integrity & persistence +- **Advanced Token Management**: + - Implementation of an atomic token refresh mechanism within the Data Layer. + - Securing critical transaction flows by validating session integrity before high-stakes domain executions. + - Complete token lifecycle: Acquisition → Persistence → Validation → Refresh → Recovery → Invalidation. +- **Offline-First with Room**: + - Integration of **Room Database** as the local cache for service modules. + - Implementation of a "Source of Truth" strategy in Repositories to handle network-to-local synchronization. +```mermaid +flowchart TD + A[1. Acquisition
LoginUseCase → AuthRepository.login()] + B[2. Persistence
SessionRepository.saveToken()] + C[3. Validation
ValidateTokenUseCase] + D[4. Refresh
RefreshTokenUseCase] + E[5. Recovery
SessionManager.initializeSession()] + F[6. Invalidation
LogoutUseCase] + + A --> B --> C + C -->|"Valid"| G[Use Access Token] + C -->|"Expired"| D --> B + E --> C + F --> H[Reset AuthState] + + style A fill:#e94560,stroke:#c62828,color:#ffffff + style B fill:#16213e,stroke:#0f3460,color:#ffffff + style C fill:#1a1a2e,stroke:#e94560,color:#ffffff + style D fill:#0f3460,stroke:#16213e,color:#ffffff + style E fill:#16213e,stroke:#0f3460,color:#ffffff + style F fill:#e94560,stroke:#c62828,color:#ffffff + style G fill:#0f3460,stroke:#16213e,color:#ffffff + style H fill:#1a1a2e,stroke:#e94560,color:#ffffff +``` +### Phase III: Verification & Quality Engineering +- **Domain Test Suite**: Achieving 90%+ coverage for `:core:domain` logic using JUnit 5 and MockK. +- **UI & Regression Testing**: + - Implementation of **Compose UI Tests** for critical user journeys (Login, Home navigation). + - Integration of **Screenshot Testing** to ensure visual consistency across the Rho Studio design system. +- **Performance Profiling**: Regular benchmarking of recomposition counts and memory allocation in high-density feature screens. +```mermaid +flowchart LR + subgraph Current["Current Flow"] + C1[UI] --> C2[ViewModel] --> C3[UseCase] --> C4[Repository] --> C5[SharedPreferences/Mock Auth] + end + + subgraph Planned["Planned Flow"] + P1[UI] --> P2[ViewModel] --> P3[UseCase] --> P4[Repository] + P4 --> P5[Local: Room Database] + P4 --> P6[Remote: Retrofit/Firebase] + end + + Current -.->|"Evolution"| Planned + + style Current fill:#1a1a2e,stroke:#e94560,color:#ffffff + style Planned fill:#0f3460,stroke:#16213e,color:#ffffff +``` --- -## 6. References & Standards +## 6. Verification & Quality Assurance +- **CI/CD**: GitHub Actions pipeline verifies every commit against build and test suites. +- **Static Analysis**: Automated linting and ASCII metadata headers enforce code style and legal standards. + +## 7. File Registry and responsibilities +Here is the updated table based on the file structure provided: + +| File / Module | Layer | Responsibility | Status | +|:----------------------------------|:-------------|:-------------------------------------|:-------| +| `MainActivity.kt` | UI Layer | Navigation orchestration | ✅ | +| `BaseViewModel.kt` | UI Layer | Loading/Error state management | ✅ | +| `HeaderViewModel.kt` | UI Layer | Session state bridging | ✅ | +| `PageHeader.kt` / `PageFooter.kt` | UI Layer | Shared UI components | ✅ | +| `LoginScreen.kt` | UI Layer | Login UI entry point | ✅ | +| `LoginViewModel.kt` | UI Layer | Form state & validation | ✅ | +| `LoginEmailField.kt` | UI Layer | Email input with validation | ✅ | +| `LoginPasswordField.kt` | UI Layer | Password input with security | ✅ | +| `LoginButton.kt` | UI Layer | Login action button | ✅ | +| `HomeScreen.kt` | UI Layer | Home UI entry point | ✅ | +| `HomeViewModel.kt` | UI Layer | Home state & session termination | ✅ | +| `ServiceList.kt` | UI Layer | Service list grid component | ✅ | +| `ServiceItem.kt` | UI Layer | Individual service item component | ✅ | +| `ServiceModule.kt` | UI Layer | Feature-specific model (Home) | ✅ | +| `BaseUseCase.kt` | Domain Layer | Standardized UseCase abstraction | ✅ | +| `LoginUseCase.kt` | Domain Layer | Atomic authentication transaction | ✅ | +| `LogoutUseCase.kt` | Domain Layer | Session teardown orchestration | ✅ | +| `SessionManagerInterface.kt` | Domain Layer | Session operations contract | ✅ | +| `AuthRepository.kt` | Domain Layer | Authentication contract | ✅ | +| `SessionRepository.kt` | Domain Layer | Session persistence contract | ✅ | +| `User.kt` / `Credentials.kt` | Domain Layer | Pure Kotlin Entities | ✅ | +| `SessionManager.kt` | Data Layer | SSOT for authentication | ✅ | +| `AuthRepositoryImpl.kt` | Data Layer | Mock auth (Firebase **planned**) | ⚠️ | +| `SessionRepositoryImpl.kt` | Data Layer | SharedPreferences (Room **planned**) | ⚠️ | +| `RefreshTokenUseCase.kt` | Domain Layer | Token refresh (**planned**) | 📅 | +| `Dagger Components` | App Root | DI setup (**planned**) | 📅 | +## 8. References & Standards - **MAD (Modern Android Development)**: Adhering to official [Android Architecture Guidelines](https://developer.android.com/topic/architecture). -- **Jetpack Compose Best Practices**: Following [UDF (Unidirectional Data Flow)](https://developer.android.com/jetpack/compose/architecture#udf) principles for state management. -- **Clean Architecture**: Implementing principles from Robert C. Martin to maintain a high degree of testability and independence from external libraries. [Clean Architecture Reference](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) +- **Jetpack Compose Best Practices**: Following UDF ([Unidirectional Data Flow](https://developer.android.com/develop/ui/compose/architecture#udf)) principles for state management. +- **Multi-Module Topology**: Following [Guide to App Modularization](https://developer.android.com/topic/modularization). +- **Dependency Injection**: [Dagger Documentation](https://dagger.dev/). +- **Secure Token Management**: [Android Security Best Practices](https://developer.android.com/privacy-and-security/security-best-practices). + --- -**[Rho.Studio®](https://rho.studio/) - Engineering Department** - Contact [alexis.tercero@rho.studio](mailto:alexis.tercero@rho.studio) +**[Rho.Studio®](https://rho.studio/) - Engineering Department** - Contact [alexis.tercero@rho.studio](mailto:alexis.tercero@rho.studio) diff --git a/features/home/src/main/java/com/rho/studio/ui/features/home/HomeScreen.kt b/features/home/src/main/java/com/rho/studio/ui/features/home/HomeScreen.kt index 0e2bf8a..b5cd8a2 100644 --- a/features/home/src/main/java/com/rho/studio/ui/features/home/HomeScreen.kt +++ b/features/home/src/main/java/com/rho/studio/ui/features/home/HomeScreen.kt @@ -14,7 +14,8 @@ * ============================================================================ * Description: * The primary landing screen of the application, serving as the main - * dashboard for user interactions. It orchestrates the display of + * Rho Studio Home screen. It establishes the primary entry point and + * experience for user interactions. It orchestrates the display of * the header, available services, and the footer. * * Key Features: diff --git a/features/home/src/main/java/com/rho/studio/ui/features/home/HomeViewModel.kt b/features/home/src/main/java/com/rho/studio/ui/features/home/HomeViewModel.kt index fac3bfa..7d3e6e0 100644 --- a/features/home/src/main/java/com/rho/studio/ui/features/home/HomeViewModel.kt +++ b/features/home/src/main/java/com/rho/studio/ui/features/home/HomeViewModel.kt @@ -12,7 +12,7 @@ * Email: alexis.tercero@rho.studio * Date: 2026-08-06 * ============================================================================================== - * Description: ViewModel for the Home feature, managing dashboard state, session data, + * Description: ViewModel for the Home feature, managing feature state, session data, * and providing access to available service modules. * ============================================================================================== */ @@ -36,7 +36,7 @@ class HomeViewModel : BaseViewModel() { private val _currentUser = MutableStateFlow(sessionManager.getCurrentUserSync()) val currentUser: StateFlow = _currentUser.asStateFlow() - // Parametrized services for the dashboard + // Parametrized services for the Home experience private val _services = MutableStateFlow>( listOf( ServiceModule("inv", R.string.module_inventory, R.color.rho_red), diff --git a/features/home/src/main/java/com/rho/studio/ui/features/home/components/ServiceItem.kt b/features/home/src/main/java/com/rho/studio/ui/features/home/components/ServiceItem.kt index b46ce65..39b9f9a 100644 --- a/features/home/src/main/java/com/rho/studio/ui/features/home/components/ServiceItem.kt +++ b/features/home/src/main/java/com/rho/studio/ui/features/home/components/ServiceItem.kt @@ -27,7 +27,7 @@ * • Feedback: Built on Material 3 Button semantics to provide * standard touch feedback and accessibility support. * • Scalable Grid Integration: Designed to be used within LazyVerticalGrid - * for responsive dashboard layouts. + * for responsive feature layouts. * ============================================================================ */ package com.rho.studio.ui.features.home.components From 617417044b2a4e9b587f6a1e4ae1fa6a44f4e905 Mon Sep 17 00:00:00 2001 From: Alexis Tercero Date: Mon, 10 Aug 2026 18:00:50 -0600 Subject: [PATCH 5/5] FIX | #32 Diagram typo. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 637a918..8558d41 100644 --- a/README.md +++ b/README.md @@ -257,11 +257,11 @@ The application is transitioning from a modular prototype to a production-harden - Implementation of a "Source of Truth" strategy in Repositories to handle network-to-local synchronization. ```mermaid flowchart TD - A[1. Acquisition
LoginUseCase → AuthRepository.login()] - B[2. Persistence
SessionRepository.saveToken()] + A[1. Acquisition
LoginUseCase --> AuthRepository.login] + B[2. Persistence
SessionRepository.saveToken] C[3. Validation
ValidateTokenUseCase] D[4. Refresh
RefreshTokenUseCase] - E[5. Recovery
SessionManager.initializeSession()] + E[5. Recovery
SessionManager.initializeSession] F[6. Invalidation
LogoutUseCase] A --> B --> C