English | 中文

kurashi (暮らし)

Todo + Periodic Reminders + Fridge — lunar-calendar aware, local-first, Android + iOS.
Built for personal daily life. No accounts, no cloud, no ads.

Get Started · Usage · Report Issue

Table of Contents

1. About The Project
2. Built With
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
   • Today's Agenda
   • Periodic Reminders
   • Fridge Management
5. Testing
6. Deployment
7. Roadmap
8. Contributing
9. License
10. Acknowledgments

About The Project

kurashi (暮らし — "daily living" in Japanese) is a personal life management app for Android + iOS. Three tabs, one local database, zero cloud.

Tab	What you get
Today	Daily agenda blending todos, habits, and subscription anchors in one scroll
Subscription	Recurring reminders for festivals, birthdays, bills, and custom intervals — all lunar-calendar native
Fridge	Food inventory with expiry tracking, smart restock suggestions, full change history (JSON-exportable)

Designed and built for personal use. The developer maintains it to solve their own daily friction — lunar dates for Chinese holidays, no subscription tracking in existing apps, food waste from forgotten fridge items. Everything local-first: no accounts, no tracking, no ads, no collaboration. Just your data on your device.

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

Getting Started

Prerequisites

• Flutter 3.41.x (stable channel) — Install guide
• Dart 3.12+
• Android Studio / Xcode (for platform builds)
• A physical device or emulator

Installation

1. Clone the repo

   git clone https://github.com/kurashi-app/kurashi.git
   cd kurashi

2. Install dependencies

   flutter pub get

3. Run code generation (required for Isar collections and Riverpod providers)

   dart run build_runner build --delete-conflicting-outputs

4. Run on a connected device or emulator

   flutter run -d <device-id>

List available devices:

flutter devices

(back to top)

Usage

Today

The default screen. Combines three data sources into one chronologically sorted list:

• Todos — tasks with optional due dates and times
• Habits — weekly frequency goals (e.g., "read 30 min, 3x/week") with checkin
• Subscription anchors — upcoming reminders from the Subscription tab, surfaced when relevant

Completed todos disappear from today's view immediately.

Subscription

Create recurring reminders for anything that repeats:

Type	Examples	Calendar
Chinese festivals	Spring Festival, Mid-Autumn, Qingming	Lunar
Western festivals	Mother's Day, Thanksgiving	Solar
Birthdays	"Dad's birthday, lunar 7/8, remind 3 days before"	Lunar or Solar
Bills	"Credit card payment, 5th of each month"	Solar
Custom	"Change water filter every 180 days"	Smart interval
Home	"Replace smoke alarm battery yearly"	Solar
Pets	"Heartworm prevention, every 30 days"	Solar
Documents	"Driver's license renewal, 90 days before"	Solar
Health	"Annual checkup", "Dental cleaning every 6 months"	Solar
Vehicle	"Oil change yearly", "Insurance renewal"	Solar

Active reminders are sorted by days-until and shown in the Today tab.

Fridge

Manage food inventory and reduce waste:

• Add items — with name, quantity, expiry date, and tag (vegetable / fruit / meat / custom)
• Expiry tracking — items nearing expiry surface in the restock list
• Smart restock — items with restock enabled auto-suggest when stock runs low (custom per-item threshold)
• Change history — every add / edit / delete / undo is logged with before/after values. Export to JSON for analysis
• Retention policy — set log retention to 30 days, 90 days, or forever

Build Release APK

flutter build apk --release
# Output: build/app/outputs/flutter-apk/app-release.apk

Install on a device:

adb install build/app/outputs/flutter-apk/app-release.apk

(back to top)

Testing

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

# Analyze code
flutter analyze

89 unit & widget tests covering repository behavior, lunar calendar calculations, notification scheduling, and widget rendering.

(back to top)

Deployment

This project uses GitHub Actions for CI:

• Static analysis + test suite on every push and PR
• Release APK built automatically after tests pass (artifact attached to the run)

The workflow uses Flutter 4.41.4 on ubuntu-latest with Java 17.

(back to top)

Roadmap

• Today tab with todos + habits + subscription anchors
• Subscription reminders (lunar and solar)
• Fridge inventory with expiry tracking
• Change log with JSON export
• Restock suggestions
• Retention policy
• JSON import (restore from export)
• Multi-batch expiry per item (e.g., 3 eggs used one by one)
• Theming beyond monochrome
• Widget / home screen quick-add

Roadmap reflects the developer's personal needs. New features are prioritized by daily friction, not popularity.

(back to top)

Contributing

This is a personal project — the developer builds it for their own daily life. Issues and suggestions are welcome, but features are prioritized by personal need.

If something doesn't work for you:

1. Check if it's a personal-preference mismatch (the app is opinionated by design)
2. Search existing issues
3. Open a new issue with: what you expected, what happened, steps to reproduce

Pull requests that align with the app's direction (local-first, minimal, personal-scale) may be considered. Large architectural changes or social/cloud features likely won't fit.

(back to top)

License

Distributed under the MIT License. See LICENSE for details.

(back to top)

Acknowledgments

• lunar — Chinese lunar calendar calculations
• IconPark — outline icon set
• Inter / JetBrains Mono / Noto Sans SC — bundled typefaces

(back to top)