Total Family App

A self-hostable, offline-first family organizer. One household runs it on their home network, and each family member picks a profile on their own device to see and manage the family's shared chores, calendar, lists, projects, and kid rewards.

It's also a learning project: a deliberately over-documented, cleanly layered TypeScript codebase you can read end to end.

Features

• Calendar & events: shared family appointments with per-member colour coding and a weekly view.
• Personal tasks & chore board: day-to-day chores assigned to individual family members, with completion tracking.
• Recurring series: both chores and calendar events can repeat on a schedule, materialised by a dedicated recurrence engine.
• Family lists: shared checklists for groceries, packing, and errands.
• Projects & rollover: group related work toward a goal; unfinished tasks roll over automatically.
• Daily reward reveal: finishing all of a child's chores for the day reveals a surprise, to keep kids motivated.
• Offline-first PWA: keeps working on flaky home Wi-Fi and on phones and tablets, syncing when the connection returns.
• Background scheduler & Git backup: in-process jobs handle recurring maintenance, including an optional nightly Git backup of the database.

Architecture

A Bun + TypeScript monorepo using Bun workspaces under code/*:

• @family-app/shared (code/shared): framework-free TypeScript with domain entity types, branded IDs, and REST/action/view-model API contracts. Types only, imported by both other packages so client and server stay in lock-step.
• @family-app/backend (code/backend): a single Bun.serve HTTP server handling routing, Ajv request validation, a layered service factory (routes → services → use cases → repositories), background jobs, and the recurrence engine. Persistence is JSON-file-based via @tbelmega/potato-db (no SQL, no migrations), with all data partitioned by family ID.
• @family-app/frontend (code/frontend): a React 19 + Vite PWA, styled with Tailwind CSS v4 and routed with React Router, served by the back end under /app.

The app is single-family per deployment today, but every record is scoped by a family ID so it can grow into a multi-tenant service later.

Coding conventions for the codebase (naming, types, layering, testing, commits, and more) live in AGENTS.md.

Documentation

Detailed docs live under docs/:

• docs/features/architecture-overview.md: the moving parts and how a request flows end to end.
• docs/features/: a deep-dive doc per feature (calendar, chore board, recurring series, projects, reward reveal, offline/PWA, and more).
• docs/adr/: architecture decision records covering the key design choices (layering, family-scoped repositories, branded IDs, local file persistence, offline-first PWA, and others).

Getting started

Requires Bun.

bun install     # install dependencies across all workspaces
bun run seed    # seed a default family with sample data
bun run dev     # run backend + frontend together

Then open the app in your browser (the dev server prints the URL).

During development, run the full check across all packages:

bun run check   # typecheck + tests for backend, frontend, and shared

Other useful scripts: bun run typecheck, bun run test, bun run build, and bun run start (production back end serving the built front end).

Recommended tooling for contributors

If you fork this repo or develop it further with an AI coding agent, I recommend installing decently-capable-powers: a minimalist set of behavioral disciplines for AI coding agents that installs as configuration for Claude Code, OpenAI Codex, and Cursor. It pairs well with the conventions in AGENTS.md.

License

This project is licensed under the MIT License.