FamPlus – Next-Generation Family Management Platform

1. Purpose

FamPlus is the successor to the existing banking app. It retains the proven ideas of chore tracking, allowance automation and simple finance management, but is rebuilt from the ground up for scalability, modularity and multi-family usage.

The project is organised as a monorepo with clearly separated backend and frontend packages and a shared documentation space.
Everything is open-source and designed for self-hosting or simple cloud deployment.

---

2. High-Level Feature Set

Chore Management ✔︎

• Create one-off or recurring chores with flexible schedules.
• Mobile-first dashboard for parents & kids.
• Approval workflow, streaks, points & allowance automation.

Accounting Lite 💰

• Double-entry style accounts (Asset / Expense / Liability / Equity / Revenue) inspired by current implementation.
• Transaction categorisation with parent-defined Categories and automatic suggestions.
• Family budgets & simple reports.

Asset Tracking 📈

• Register purchases & disposals of assets (e.g. crypto, shares, collectibles).
• Real-time price look-ups via CoinGecko (or other providers).
• Capital-gain calculation using FIFO / LIFO / Highest-gain strategies.

Multi-Family Support 👨‍👩‍👧‍👦

• Each Family is an isolated tenant; all data rows carry family_id and queries are automatically filtered.
• Invitation & role system (Parent, Child, Guest).

Notifications & Scheduling 🔔

• Server-side tasks (Celery + Redis) for chore spawning, reminders and price refresh.
• Optional push & email integrations.

---

3. Technology Stack

Layer	Technology
Backend	Django 5.2 · Django REST Framework · MySQL · Channels 4.1 · Daphne 4.1 · Celery[redis] 5.4
Frontend	React 18.3 + Vite + TypeScript · Tailwind CSS · shadcn/ui · TanStack Query 5.21 · lucide-react · axios
DevOps	Local MySQL & Redis (no Docker) · GitHub Actions CI · Traefik / Caddy for HTTPS

Key Package Versions

Backend

• Django 5.2
• sqlparse 0.5.3
• mysqlclient 2.2.7
• channels 4.1.0
• daphne 4.1.0
• redis 5.0.4
• celery[redis] 5.4.0

Frontend

• react 18.3.0
• react-dom 18.3.0
• react-router-dom 6.23.0
• @tailwindcss/vite 4.1.10
• @tanstack/react-query 5.21.0
• lucide-react 0.300.0
• axios 1.6.5
• shadcn@latest

---

4. Planned Repository Structure

famplus/
├── backend/                 # Django project & apps
│   # All Django apps live inside the `apps/` folder
│   ├── manage.py
│   ├── requirements.txt
│   ├── project/             # Django settings
│   └── apps/
│       ├── core/            # Common utilities & custom user model
│       ├── families/        # Multi-tenancy & invitations
│       ├── chores/
│       ├── accounting/
│       └── assets/
├── frontend/                # React/Vite workspace
│   ├── index.html
│   ├── vite.config.ts
│   └── src/
│       ├── components/
│       ├── lib/
│       └── features/
├── doc/                     # Detail design docs & ADRs
└── scripts/                 # Helper shell scripts

(Exact layout will evolve as tasks are completed.)

---

5. Architectural Notes

1. Modularity first – each bounded-context gets its own Django app & React feature slice.
2. Strict API contract – REST/JSON as default, GraphQL considered for complex querying.
3. Multi-tenancy – row-level security enforced through FamilyForeignKey and DRF permission classes.
4. Dark & Light mode – shadcn/ui components with system preference toggle.

---

6. Getting Started

1. Clone repo → git clone <this repo>
2. Install Python & Node requirements.
3. Run service helper → ./scripts/setup_services.sh (installs & starts MySQL/Redis and optional MailHog).
4. Configure environment variables (see list below).
5. Install pre-commit → pip install pre-commit then pre-commit install.
6. Run the dev server → cd backend && FAMPLUS_SQLITE=1 python manage.py runserver (uses SQLite by default).
7. Run unit tests (SQLite) → FAMPLUS_SQLITE=1 ./scripts/run_tests_sqlite.sh
8. Start background tasks (two terminals):
   • Worker – cd backend && celery -A project worker --loglevel=info
   • Beat – cd backend && celery -A project beat --loglevel=info
9. Launch the React UI → cd frontend && npm install && npm run dev (http://localhost:5173 by default).

ℹ️ The Vite dev server proxies API requests if you export VITE_API_URL=http://localhost:8000 before starting it.

Required Environment Variables

Set these before running the backend (a .env file works too):

SECRET_KEY=<your secret>
DB_NAME=famplusdb
DB_USER=famplususer
DB_PASSWORD=<password>
DB_HOST=127.0.0.1
DB_PORT=3306
CELERY_BROKER_URL=redis://127.0.0.1:6379/0
CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/0

Optionally set FAMPLUS_SQLITE=1 to use SQLite instead of MySQL.

---

7. Roadmap

High-level tasks are tracked in TASKS.md. Sub-tasks & in-depth design notes live under doc/.

License

Released under the MIT License.

Happy hacking! ✨