{"id":31322867,"url":"https://github.com/jonahkingcs/household-tracker","last_synced_at":"2026-04-30T08:31:58.052Z","repository":{"id":315762080,"uuid":"1060718330","full_name":"jonahkingcs/household-tracker","owner":"jonahkingcs","description":"A desktop app for Mac built with Python (PySide6 + SQLite) to track household chores and recurring purchases, featuring analytics, rotation fairness, and offline persistence.","archived":false,"fork":false,"pushed_at":"2025-10-21T14:42:56.000Z","size":3650,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-21T15:34:42.245Z","etag":null,"topics":["analytics","desktop-app","macos","personal-project","portfolio","productivity","pyside6","python","qt","sqlite","task-tracker","usability"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonahkingcs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T13:01:23.000Z","updated_at":"2025-10-21T14:42:59.000Z","dependencies_parsed_at":"2025-09-20T16:17:00.318Z","dependency_job_id":"8738a3d5-50b9-4868-84c7-ed7ba1816da2","html_url":"https://github.com/jonahkingcs/household-tracker","commit_stats":null,"previous_names":["jonahkingcs/household-tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonahkingcs/household-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonahkingcs%2Fhousehold-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonahkingcs%2Fhousehold-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonahkingcs%2Fhousehold-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonahkingcs%2Fhousehold-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonahkingcs","download_url":"https://codeload.github.com/jonahkingcs/household-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonahkingcs%2Fhousehold-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32459420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","desktop-app","macos","personal-project","portfolio","productivity","pyside6","python","qt","sqlite","task-tracker","usability"],"created_at":"2025-09-25T19:25:17.100Z","updated_at":"2026-04-30T08:31:58.048Z","avatar_url":"https://github.com/jonahkingcs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Household Tracker\n\nA desktop app for Mac built with **Python (PySide6 + SQLite)** to help flatmates fairly track **chores** and **recurring household purchases**.  \nThe app runs **fully offline**, stores data locally, and provides **analytics dashboards** to keep everything transparent and fair.\n\n---\n\n## Features\n\n### Chores\n- Rotate chores fairly between all housemates  \n- Log completions with duration + comments  \n- View history timeline of who did what and when  \n- Analytics: pie charts + leaderboards of time spent  \n\n### Purchases\n- Track recurring household purchases (milk, toilet paper, etc.)  \n- Rotate who buys each item to ensure fairness  \n- Log purchases with quantity, price, and comments  \n- Analytics: total spend per user, item breakdowns, pie charts  \n\n### Global\n- Works 100% offline — data stored in local SQLite database  \n- Light \u0026 dark mode stylesheets with rounded, modern design  \n- Add/remove users dynamically (rotations auto-adjust)  \n- Searchable, filterable history timeline  \n\n---\n\n## Features Implemented So Far\n\n- **Core app \u0026 theming**\n  - Main window with tabs: **Chores**, **Purchases**, **History**, (Analytics placeholder)\n  - **Light/Dark** QSS themes with pixel 9-slice cards/buttons; theme persists via QSettings\n  - Quick toggle (Shift+L) and menu: View → Appearance\n\n- **Database \u0026 repos**\n  - SQLite + SQLAlchemy 2.0 models: `User`, `Chore`, `ChoreCompletion`, `Item`, `PurchaseRecord`\n  - Clean repo layer (`src/db/repo/*`) with eager-loading to avoid N+1 queries\n  - UUID primary keys; money stored in **cents** for correctness\n\n- **Users management**\n  - **Users dialog**: list, add, toggle active, hard delete (with safe reassignment/nulling)\n  - Deactivation removes users from rotations; history retained\n\n- **Chores**\n  - **Chore board**: scrollable 2-column grid of cards (title, description, due, next assignee)\n  - Add/Edit dialogs; **Complete Chore** dialog (duration + comments)\n  - Global alphabetical **rotation** of active users; due dates bump via `bump_due`\n  - Humanized due text (“Today / Tomorrow / in 3d / Overdue by 2d”)\n\n- **Purchases**\n  - **Purchases board**: 2-column cards (restock due, next buyer)\n  - Add/Edit item dialogs; **Log Purchase** dialog (qty, price, comments)\n  - Rotation advances on purchase; next restock date bumped\n  - **Purchases History** tab: table (Item • Buyer • Qty • Total • Date • Comments) with filters  \n    (Item, Buyer, Last 30/90 days) and default **Date desc** sorting\n\n- **Dev utilities**\n  - Simple seed scripts under `src/dev` for adding users/items/chores/purchases\n  - Paths centralized in `src/services/paths.py` (`~/Library/Application Support/HouseholdTracker`)\n\n---\n\n## Upcoming Features\n\n- **History enhancements**\n  - Chores history (toggle alongside Purchases)\n  - CSV export of filtered history\n\n- **Analytics (MVP)**\n  - Total spend per user \u0026 per item\n  - Chore time leaderboards / completion streaks\n  - Simple charts (matplotlib / pyqtgraph / Qt Charts)\n\n- **Rotations \u0026 data model**\n  - Per-entity rotations (item/chore-specific order vs global)\n  - Optional soft-delete \u0026 name snapshots for cleaner history\n\n- **Settings \u0026 tooling**\n  - App Settings panel (currency, date/time format)\n  - Data export/import (JSON/CSV)\n  - Alembic migrations as the schema stabilizes\n\n- **Packaging**\n  - Polished macOS `.app` bundle (codesign/notarize) with PyInstaller/Briefcase\n\n---\n\n## Screenshots\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_chore_board.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_add_chore.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_complete_chore.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_edit_chore.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_purchase_board.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_add_item.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_log_purchase.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_edit_item.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_purchase_history.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_user_settings.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshot_add_user.png\" width=\"600\" alt=\"Main Window screenshot\"\u003e\n\u003c/p\u003e\n\n---\n\n## Tech Stack\n\n- **Language:** Python 3.11  \n- **Framework:** PySide6 (Qt for Python)  \n- **Database:** SQLite + SQLAlchemy ORM  \n- **Visualization:** Matplotlib (planned)  \n- **Dev Tools:** Ruff (linting), Black (formatting)  \n\n---\n\n## Getting Started\n\n### 1. Clone the repo\ngit clone https://github.com/jonahkingcs/household-tracker.git\ncd household-tracker\n\n### 2. Set up a virtual environment\n```bash\npython3 -m venv venv\nsource venv/bin/activate   # macOS/Linux\nvenv\\Scripts\\activate      # Windows\n```\n\n### 3. Install dependencies\n```bash\npip install -r requirements.txt\n```\n\n### 4. Run the app\n```bash\npython -m src.app\n```\n\n---\n\n## Project Structure\n\nHouseholdTracker/\n├── src/\n│   ├── app.py              # Application entry point\n│   ├── views/              # Qt views (MainWindow, future widgets)\n│   ├── db/                 # SQLAlchemy models \u0026 session setup\n│   ├── services/           # Paths, helpers, business logic\n│   └── styles/             # QSS stylesheets (light/dark themes)\n│   └── assets/             # Custom icons and ui\n│   └── dev/                # Dev-only scripts (test seeds, etc.)\n├── docs/                   # Screenshots, diagrams\n└── requirements.txt\n\n---\n\n## Roadmap\n\n- Build chore \u0026 purchase widgets\n- Implement analytics dashboards\n- Add gamification (points, streaks, rewards)\n- Export/share reports\n\n---\n\n## License\n\nThis project is provided for portfolio and demonstration purposes only.  \nAll rights reserved — no permission is granted to use, copy, or distribute this code.\n\n---\n\n## Author\n\n**Jonah King**\n- [GitHub](https://github.com/jonahkingcs)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonahkingcs%2Fhousehold-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonahkingcs%2Fhousehold-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonahkingcs%2Fhousehold-tracker/lists"}