# imayordomo/lks_parking architecture

> Architecture diagram of the GitHub repository imayordomo/lks_parking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imayordomo/lks_parking
- Repository: https://github.com/imayordomo/lks_parking

## Overview

1. **What this repo is**
   - A single Android application module (`app/`) for managing parking reservations at LKS Next offices.
   - It is a **client app only**: there is no custom backend in this repo; the app talks to **Firebase** services for identity, data, and messaging.

2. **Primary architecture style**
   - The app follows **MVVM** with **Jetpack Compose** UI.
   - The code is organized into clear layers:
     - `ui/pages` = screens
     - `ui/viewmodel` = state and orchestration
     - `data` = models, auth, and repository access
     - `utils` = cross-cutting helpers

3. **Entry point and navigation**
   - `MainActivity` is the app entry point.
   - Compose navigation is centralized in `ui/components/ParkingNavigation.kt`.
   - Screens are mostly page-level Compose functions under `ui/pages`, with navigation state and screen routing owned above them.

4. **Presentation layer**
   - Screens cover the full user journey: landing, login/register, forgot password, dashboard, new/edit reservation, parking view, history, notifications, profile, report, help, and about.
   - Shared UI pieces live in `ui/components`, including navigation shell and scrolling helpers.
   - Theme and styling are isolated in `ui/theme`.

5. **State and orchestration layer**
   - Each major screen has a dedicated ViewModel in `ui/viewmodel`.
   - ViewModels expose state with **StateFlow** and coordinate validation, loading, and user actions.
   - `ViewModelFactory` is a manual dependency injection boundary: it wires ViewModels to shared dependencies instead of using Hilt/Koin.

6. **Data layer and business-facing services**
   - `ParkingRepository` / `ParkingRepositoryImpl` encapsulate parking-domain data access.
   - `AuthManager` isolates authentication-related logic.
   - The domain model is centralized in `data/model/Models.kt`, suggesting a shared set of reservation, vehicle, user, and notification entities used across screens.

7. **Firebase integration**
   - The app relies on several Firebase services:
     - **Firebase Auth** for registration/login and password recovery
     - **Cloud Firestore** for reservation and parking data
     - **Firebase Cloud Messaging** for push notifications
     - **Crashlytics** and **Performance Monitoring** for observability
   - `google-services.json` in `app/` confirms Firebase is configured at the app module level.

8. **Notification flow**
   - `MyFirebaseMessagingService` handles incoming push messages.
   - `utils/NotificationReceiver.kt` and `utils/ReservationReminderManager.kt` support local notification delivery and scheduled reminders.
   - This creates two notification paths: remote FCM-triggered messages and app-side reminder notifications.

9. **Localization and device behavior**
   - The app is localized for **Spanish, English, and Basque** using resource folders `values-es`, `values-en`, and `values-eu`.
   - `utils/LocaleManager.kt` likely manages runtime language selection.
   - The localization strategy is app-wide and affects UI strings, not just isolated screens.

10. **Testing boundaries**
   - Unit tests cover data, utils, and ViewModels under `app/src/test`.
   - UI/instrumentation coverage exists under `app/src/androidTest`, including screen tests and end-to-end flows.
   - The test structure mirrors production layers, which is useful for diagramming clear subsystem boundaries.

11. **Quality, CI, and release pipeline**
   - GitHub Actions workflows (`.github/workflows/main.yml`, `release.yml`) automate validation and release tasks.
   - Static analysis and quality tools include **Detekt**, **Lint**, **JaCoCo**, and **SonarCloud**.
   - This repo also includes a `scripts/seed.js` utility, likely used to populate Firebase/Firestore test or demo data.

12. **How data flows through the app**
   - User interaction starts in a Compose screen.
   - The screen calls into a ViewModel.
   - The ViewModel validates input, updates UI state, and invokes `AuthManager` or the repository.
   - The repository talks to Firebase.
   - Results flow back to the ViewModel as state, then to the UI.
   - Notifications and reminders are side-channel flows that can be triggered by Firebase messages or local scheduling logic.

13. **Architecture diagram boundaries to show**
   - Put **UI/Compose**, **ViewModels**, **data/repository/auth**, **Firebase services**, and **notification/reminder services** as separate boxes.
   - Treat **MainActivity + Navigation** as the UI shell.
   - Treat **Localization**, **theme**, and **utilities** as shared cross-cutting support.
   - Treat **tests** and **CI/CD** as external quality/support systems, not runtime components.

Main entry points: [`app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel`](https://github.com/imayordomo/lks_parking/tree/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel) (ViewModels), [`app/src/test`](https://github.com/imayordomo/lks_parking/tree/master/app/src/test) (Tests), [`app/src/main/java/com/lksnext/ParkingIMayordomo/data/repository/ParkingRepositoryImpl.kt`](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/repository/ParkingRepositoryImpl.kt) (Repository), [`app/google-services.json`](https://github.com/imayordomo/lks_parking/blob/master/app/google-services.json) (Firebase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_main_activity["MainActivity<br/>entry<br/>[MainActivity.kt]"]
  node_navigation_shell["Navigation<br/>compose shell"]
  node_screens["Screens<br/>compose pages"]
  node_viewmodels["ViewModels<br/>mvvm state"]
  node_vm_factory["Factory<br/>manual DI"]
  node_data_layer[("Data layer<br/>domain data")]
  node_repo_impl["Repository<br/>firestore access"]
  node_auth_manager["AuthManager<br/>auth service<br/>[AuthManager.kt]"]
  node_models["Models<br/>shared entities<br/>[Models.kt]"]
  node_fcm_service["FCM service<br/>push handler"]
  node_notif_receiver["NotificationReceiver<br/>local notif"]
  node_reminder_mgr["Reminder manager<br/>scheduler"]
end

subgraph group_support["Cross-cutting support"]
  node_locale_mgr["LocaleManager<br/>localization<br/>[LocaleManager.kt]"]
  node_theme["Theme<br/>compose styling<br/>[Theme.kt]"]
  node_ui_utils["UI utils<br/>helpers<br/>[ParkingUtils.kt]"]
end

subgraph group_backend["Firebase services"]
  node_firebase[("Firebase<br/>managed backend")]
end

subgraph group_quality["Quality and delivery"]
  node_ci_cd["CI/CD<br/>workflows<br/>[workflows]"]
  node_tests["Tests"]
end

node_main_activity -->|"starts"| node_navigation_shell
node_navigation_shell -->|"routes to"| node_screens
node_screens -->|"collects state"| node_viewmodels
node_viewmodels -->|"constructed by"| node_vm_factory
node_vm_factory -->|"injects"| node_data_layer
node_viewmodels -->|"auth actions"| node_auth_manager
node_viewmodels -->|"domain actions"| node_repo_impl
node_repo_impl -->|"reads/writes"| node_firebase
node_auth_manager -->|"authenticates"| node_firebase
node_data_layer -->|"shares schema"| node_models
node_viewmodels -->|"maps state"| node_models
node_screens -->|"styled by"| node_theme
node_screens -->|"localized by"| node_locale_mgr
node_screens -->|"uses"| node_ui_utils
node_fcm_service -->|"receives push"| node_firebase
node_fcm_service -->|"triggers"| node_notif_receiver
node_reminder_mgr -->|"schedules"| node_notif_receiver
node_viewmodels -->|"requests reminders"| node_reminder_mgr
node_tests -.->|"covers"| node_viewmodels
node_tests -.->|"covers"| node_repo_impl
node_tests -.->|"covers"| node_screens
node_ci_cd -.->|"runs"| node_tests

click node_main_activity "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/MainActivity.kt"
click node_navigation_shell "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/components/ParkingNavigation.kt"
click node_viewmodels "https://github.com/imayordomo/lks_parking/tree/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel"
click node_vm_factory "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel/ViewModelFactory.kt"
click node_data_layer "https://github.com/imayordomo/lks_parking/tree/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data"
click node_repo_impl "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/repository/ParkingRepositoryImpl.kt"
click node_auth_manager "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/AuthManager.kt"
click node_models "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/model/Models.kt"
click node_firebase "https://github.com/imayordomo/lks_parking/blob/master/app/google-services.json"
click node_fcm_service "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/MyFirebaseMessagingService.kt"
click node_notif_receiver "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/NotificationReceiver.kt"
click node_reminder_mgr "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ReservationReminderManager.kt"
click node_locale_mgr "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/LocaleManager.kt"
click node_theme "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/theme/Theme.kt"
click node_ui_utils "https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ParkingUtils.kt"
click node_ci_cd "https://github.com/imayordomo/lks_parking/blob/master/.github/workflows"
click node_tests "https://github.com/imayordomo/lks_parking/tree/master/app/src/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_activity,node_navigation_shell,node_screens,node_viewmodels,node_vm_factory,node_data_layer,node_repo_impl,node_auth_manager,node_models,node_fcm_service,node_notif_receiver,node_reminder_mgr toneBlue
class node_locale_mgr,node_theme,node_ui_utils toneAmber
class node_firebase toneMint
class node_ci_cd,node_tests toneRose
```

## Components

### App runtime

Android client app and its in-process layers

- [MainActivity](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/MainActivity.kt): entry · App entry point · `app/src/main/java/com/lksnext/ParkingIMayordomo/MainActivity.kt`
- [Navigation](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/components/ParkingNavigation.kt): compose shell · Centralized screen routing and nav host · `app/src/main/java/com/lksnext/ParkingIMayordomo/ui/components/ParkingNavigation.kt`
- **Screens**: compose pages · Landing, auth, dashboard, reservations, history, notifications, profile, report, help, about
- [ViewModels](https://github.com/imayordomo/lks_parking/tree/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel): mvvm state · Screen state, validation, loading, and orchestration · `app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel`
- [Factory](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel/ViewModelFactory.kt): manual DI · Wires ViewModels to shared dependencies · `app/src/main/java/com/lksnext/ParkingIMayordomo/ui/viewmodel/ViewModelFactory.kt`
- [Data layer](https://github.com/imayordomo/lks_parking/tree/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data): domain data · Repository, auth manager, and shared models · `app/src/main/java/com/lksnext/ParkingIMayordomo/data`
- [Repository](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/repository/ParkingRepositoryImpl.kt): firestore access · Parking domain data access implementation · `app/src/main/java/com/lksnext/ParkingIMayordomo/data/repository/ParkingRepositoryImpl.kt`
- [AuthManager](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/AuthManager.kt): auth service · Authentication-related logic and Firebase Auth boundary · `app/src/main/java/com/lksnext/ParkingIMayordomo/data/AuthManager.kt`
- [Models](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/data/model/Models.kt): shared entities · Reservation, vehicle, user, and notification entities · `app/src/main/java/com/lksnext/ParkingIMayordomo/data/model/Models.kt`
- [FCM service](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/MyFirebaseMessagingService.kt): push handler · Receives remote push messages · `app/src/main/java/com/lksnext/ParkingIMayordomo/MyFirebaseMessagingService.kt`
- [NotificationReceiver](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/NotificationReceiver.kt): local notif · Builds local notification delivery · `app/src/main/java/com/lksnext/ParkingIMayordomo/utils/NotificationReceiver.kt`
- [Reminder manager](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ReservationReminderManager.kt): scheduler · Schedules reservation reminder notifications · `app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ReservationReminderManager.kt`

### Cross-cutting support

Shared UI, locale, and utility services

- [LocaleManager](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/LocaleManager.kt): localization · Runtime language selection · `app/src/main/java/com/lksnext/ParkingIMayordomo/utils/LocaleManager.kt`
- [Theme](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/ui/theme/Theme.kt): compose styling · Colors, typography, and app theme · `app/src/main/java/com/lksnext/ParkingIMayordomo/ui/theme/Theme.kt`
- [UI utils](https://github.com/imayordomo/lks_parking/blob/master/app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ParkingUtils.kt): helpers · Scrollbar, parking helpers, and test tags · `app/src/main/java/com/lksnext/ParkingIMayordomo/utils/ParkingUtils.kt`

### Firebase services

External managed services used by the app

- [Firebase](https://github.com/imayordomo/lks_parking/blob/master/app/google-services.json): managed backend · Auth, Firestore, messaging, crash reporting, and performance · `app/google-services.json`

### Quality and delivery

Tests, analysis, and release automation

- [CI/CD](https://github.com/imayordomo/lks_parking/blob/master/.github/workflows): workflows · Validation and release automation · `.github/workflows`
- [Tests](https://github.com/imayordomo/lks_parking/tree/master/app/src/test): unit + ui tests · Layered coverage for data, viewmodels, utils, and Compose flows · `app/src/test`

## Connections

- MainActivity → Navigation: starts · Activity hosts the Compose app shell
- Navigation → Screens: routes to · Navigation drives page-level screens
- Screens → ViewModels: collects state · Screens read UI state and dispatch user actions
- ViewModels → Factory: constructed by · ViewModels are manually wired through a factory
- Factory → Data layer: injects · Shared dependencies are provided to state holders
- ViewModels → AuthManager: auth actions · Login, register, and password reset flow through auth logic
- ViewModels → Repository: domain actions · Reservation and parking operations go through the repository
- Repository → Firebase: reads/writes · Firestore-backed persistence and related Firebase services
- AuthManager → Firebase: authenticates · Firebase Auth handles identity flows
- Data layer → Models: shares schema · Common entities are reused across layers
- ViewModels → Models: maps state · StateFlow state is built from shared models
- Screens → Theme: styled by · Compose UI uses centralized theme definitions
- Screens → LocaleManager: localized by · UI strings and runtime language selection are app-wide
- Screens → UI utils: uses · Shared UI helpers support page rendering
- FCM service → Firebase: receives push · Remote messaging enters through Firebase Cloud Messaging
- FCM service → NotificationReceiver: triggers · Incoming messages can become local notifications
- Reminder manager → NotificationReceiver: schedules · Reminder jobs deliver local notifications
- ViewModels → Reminder manager: requests reminders · Reservation flows can configure reminder scheduling
- Tests → ViewModels: covers · Unit tests verify orchestration and state logic
- Tests → Repository: covers · Repository behavior is unit tested
- Tests → Screens: covers · Instrumentation tests exercise Compose flows
- CI/CD → Tests: runs · Workflows automate validation and release checks
