Skip to content

Commit 6591d86

Browse files
rh-idgoogle-labs-jules[bot]
rh-id
and
google-labs-jules[bot]
authored
Update README with comprehensive architecture and workflow documentation (#15)
- Added detailed User Workflow section. - Documented Modular Single-Activity Architecture, including `a-navigator` and `a-provider`. - Explained the multiple Room Database strategy and Command Pattern usage. - Added Mermaid diagrams for Architecture and Startup Flow. - Documented Automation & CI/CD setup (GitHub Actions, Fastlane). Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
1 parent 57e3858 commit 6591d86

1 file changed

Lines changed: 122 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 122 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -8,31 +8,128 @@
88
![Release Build](https://github.com/rh-id/a-personal-stuff/actions/workflows/android-release.yml/badge.svg)
99
![Emulator Test](https://github.com/rh-id/a-personal-stuff/actions/workflows/android-emulator-test.yml/badge.svg)
1010

11-
This is basically open source re-write (native instead of Flutter) of My-Personal-Stuff that I publish on google play.
12-
13-
App used to track, manage and remind you of your own stuff.
14-
Sometimes we forgot where to put something somewhere or forgot when something is going to expire.
15-
it could be your cooked food that have short expiry or maybe raw meat or chicken that people forgot to cook or even dispose them from refrigerator, or could be anything with expiry or need action that you store somewhere and forgot about it.
16-
Having calendar events to all of these doesn't really solve problems, because it can be a lot of things to put in and you do not want to mix important events with your raw meat expiration events.
17-
Having todo list app or notes also not much helpful since it was meant to be as generic as possible.
18-
similar to like warehouse logistics system but more to personal.
19-
20-
Features of this app:
21-
<ul>
22-
<li>Allow user to manage item easily</li>
23-
<li>Setup notification to remind you of something</li>
24-
<li>Allow user to manage the amount and reminder of the items to keep track of the item.</li>
25-
<li>Support barcode scan as input & search</li>
26-
</ul>
27-
28-
This project is intended for demo app for [a-navigator](https://github.com/rh-id/a-navigator) and [a-provider](https://github.com/rh-id/a-provider) library usage.
29-
The app still works as production even though it is demo app.
30-
31-
## Project Structure
32-
33-
The app uses a-navigator framework as navigator and StatefulView as base structure,
34-
combined with a-provider library for service locator,
35-
and finally RxAndroid to handle UI use cases.
11+
This is an open-source Native Android rewrite of the "My-Personal-Stuff" app (originally Flutter). It serves as a practical demonstration and production-ready implementation of the [a-navigator](https://github.com/rh-id/a-navigator) and [a-provider](https://github.com/rh-id/a-provider) libraries.
12+
13+
The app is designed to track, manage, and remind you of your personal belongings—whether it's tracking food expiration, organizing warehouse-like logistics at home, or managing maintenance schedules.
14+
15+
## Features
16+
* **Item Management**: Easily add, edit, and organize items.
17+
* **Smart Reminders**: Set up notifications for expiration dates or custom events.
18+
* **Usage Tracking**: Log when and how much of an item is used.
19+
* **Maintenance Logs**: Keep track of repairs or maintenance tasks for specific items.
20+
* **Barcode Support**: Scan barcodes for quick input and searching.
21+
22+
## User Workflow
23+
24+
The application is designed around a central Dashboard (`HomePage`) that provides quick access to all major functions.
25+
26+
1. **Dashboard**: The entry point where you can navigate to different lists or quickly add new entries.
27+
2. **Adding an Item**:
28+
* Click "Add Item" on the dashboard.
29+
* Fill in details (Name, Image, Tags).
30+
* Save to store it in the local database.
31+
3. **Tracking Usage/Maintenance/Reminders**:
32+
* These are linked to specific items.
33+
* From the dashboard, click "Add Usage" or "Add Maintenance".
34+
* Select the target item from the list.
35+
* Log the details (e.g., amount used, maintenance performed).
36+
37+
## Architecture & Modular Design
38+
39+
This project follows a **Modular Single-Activity Architecture**, emphasizing separation of concerns and scalability.
40+
41+
### Core Libraries
42+
* **[a-navigator](https://github.com/rh-id/a-navigator)**: Handles navigation. The app uses a single `MainActivity`, and all screens are implemented as `StatefulView`s (View-based architecture) rather than Fragments or Activities.
43+
* **[a-provider](https://github.com/rh-id/a-provider)**: A lightweight Dependency Injection (DI) framework used to manage services, repositories, and UI components.
44+
* **RxJava3**: Used heavily for reactive programming, handling asynchronous operations, and event buses.
45+
46+
### Modular Structure
47+
The codebase is split into feature-centric modules to enforce boundaries:
48+
* `:app`: The main entry point, containing the `MainActivity`, DI setup, and wiring for all modules.
49+
* `:base`: Common entities, utilities, and shared UI components.
50+
* `:barcode`: Barcode scanning functionality.
51+
* `:item-usage`: Logic and UI for tracking item usage.
52+
* `:item-maintenance`: Logic and UI for item maintenance logs.
53+
* `:item-reminder`: Notification and alarm scheduling logic.
54+
* `:settings`: App configuration and preferences.
55+
56+
### Database Strategy
57+
Instead of a monolithic database, the app uses **multiple Room Databases**, one for each feature module (e.g., `ItemUsageDatabase`, `ItemMaintenanceDatabase`). This ensures that modules remain decoupled and can be maintained or extracted independently.
58+
59+
### Command Pattern
60+
Business logic is encapsulated using the **Command Pattern**. Instead of putting logic in Views or ViewModels, specific actions are defined as `Cmd` classes (e.g., `NewItemCmd`, `QueryItemCmd`).
61+
* **Benefit**: Decouples logic from UI.
62+
* **Execution**: Commands run on background threads (via `ExecutorService`) and return `RxJava` types (`Single`, `Observable`) to the UI.
63+
64+
### Architecture Diagram
65+
66+
```mermaid
67+
graph TD
68+
User -->|Interacts| MainActivity
69+
MainActivity -->|Hosts| Navigator
70+
Navigator -->|Manages| StatefulView[StatefulView (UI Pages)]
71+
72+
subgraph "Feature Modules"
73+
StatefulView -->|Invokes| Command[Command Pattern (Business Logic)]
74+
Command -->|Uses| DAO[Room DAO]
75+
DAO -->|Accesses| DB[(Feature-Specific Database)]
76+
end
77+
78+
subgraph "Infrastructure"
79+
Provider[a-provider (DI)]
80+
RxJava[RxJava3 (Async/Event Bus)]
81+
end
82+
83+
StatefulView -.->|Injects| Provider
84+
Command -.->|Injects| Provider
85+
```
86+
87+
## Code Execution Flow
88+
89+
### Startup Sequence
90+
1. **MainApplication**: Initializes the global `Provider` (DI container) and registers module configurations.
91+
2. **MainActivity**:
92+
* Creates the Activity-scoped Provider.
93+
* Initializes the `Navigator`.
94+
* Sets up the `RxDisposer` to handle subscription lifecycles.
95+
3. **Navigator**:
96+
* Loads the `SplashPage`.
97+
* After initialization, routes to `HomePage`.
98+
4. **HomePage**:
99+
* The user lands on the dashboard, ready to interact.
100+
101+
```mermaid
102+
sequenceDiagram
103+
participant OS as Android OS
104+
participant App as MainApplication
105+
participant Activity as MainActivity
106+
participant Provider as Provider (DI)
107+
participant Nav as Navigator
108+
participant Splash as SplashPage
109+
participant Home as HomePage
110+
111+
OS->>App: onCreate()
112+
App->>Provider: Initialize Global Modules
113+
OS->>Activity: onCreate()
114+
Activity->>Provider: Create Activity Scope & Components
115+
Activity->>Nav: Initialize & Setup Routes
116+
Nav->>Splash: Push SplashPage
117+
Splash->>Home: Push HomePage (after init)
118+
Home-->>Activity: Render Dashboard
119+
```
120+
121+
## Automation & CI/CD
122+
123+
The project leverages automation to ensure quality and streamline releases.
124+
125+
### GitHub Actions
126+
Located in `.github/workflows/`, the project has three main pipelines:
127+
1. **Android CI (`gradlew-build.yml`)**: Runs on every push/PR to `master` to ensure the project builds successfully.
128+
2. **Android Release (`android-release.yml`)**: Triggered when a tag starting with `v*` is pushed. It builds the release APK, signs it using repository secrets, and creates a GitHub Release with a changelog.
129+
3. **Emulator Test (`android-emulator-test.yml`)**: Runs instrumented tests on an Android emulator.
130+
131+
### Fastlane
132+
The `fastlane/` directory contains metadata (images, changelogs, descriptions) used for store listings. This structure allows for version-controlled store presence management.
36133

37134
## Screenshots
38135
<img src="https://github.com/rh-id/a-personal-stuff/blob/master/fastlane/metadata/android/en-US/images/featureGraphic.png" width="1024"/>

0 commit comments

Comments
 (0)