familyHub/readme.md

# Family Hub

A centralized family organization system with tabs for chores, groceries, meal planning, family currency, and settings.

## Features
- Tabbed interface for chores, groceries, meals, shared Google Calendar embed, currency, and family settings (profiles, stores, preferences)
- JSON-based data storage under `data/`
- Daily automated exports (`scripts/daily_export.php` and `export.php?type=…`)
- Mobile-friendly interface

## Setup
1. Clone this repository to your web server.
2. **Configure the environment**
   - With a browser, open the app URL (for example `http://your-server/familyHub/`). If `.env` is missing, you are redirected to **`install.php`**, which builds `.env` from **`env.example`**.
   - Alternatively, copy `env.example` to `.env` and edit `.env` by hand.
   - See [Environment variables](#environment-variables) below for where to get each value.
3. Ensure proper permissions on the `data` directory (and that the web server can create or write JSON files there).
4. Set up the daily cron job for exports (see `scripts/daily_export.php`). It writes one JSON file per type into `exports/` (for example `chores`, `groceries`, `meals`, **`meal_plans`**, `expenses`, `stores`, `grocery_lists`, `grocery_catalog`). From the command line, the script exits with an error if `.env` is missing; complete browser setup first or copy `env.example` manually.
5. Access the hub at `http://your-local-ip/familyHub/` (adjust path and host to match your deployment).

### Google Cloud prerequisites (OAuth + APIs)

Most Google-related values come from **[Google Cloud Console](https://console.cloud.google.com/)**.

1. Create or select a **project**.
2. Open **APIs & Services → Library**, then enable any APIs you rely on (for example **Google Calendar API** and **Google Drive API** if you use those integrations).
3. Open **APIs & Services → OAuth consent screen** and complete it for your use case (Internal for Workspace-only, External for broader testing; test users may be required until published).
4. Open **APIs & Services → Credentials → Create credentials → OAuth client ID**. Choose **Web application** if your app uses a browser redirect.
5. Under **Authorized redirect URIs**, add the exact URL you will put in **`GOOGLE_REDIRECT_URI`** in `.env` (scheme, host, path, no trailing slash unless your app uses one).

Use the official [Google Cloud OAuth documentation](https://developers.google.com/identity/protocols/oauth2) for details if anything in the console changes.

## Environment variables

Values are defined in **`env.example`**. The install wizard reads that file only; use this section to learn **where to obtain** each value.

### Google API credentials

| Variable | What it is | Where to find it |
| -------- | ----------- | ---------------- |
| **`GOOGLE_CLIENT_ID`** | Public OAuth 2.0 client ID for your app | **Google Cloud Console → APIs & Services → Credentials**. Open your **OAuth 2.0 Client ID** (Web application). Copy **Client ID**. |
| **`GOOGLE_CLIENT_SECRET`** | Secret for the same OAuth client | Same credential row. Copy **Client secret** (treat it like a password; never commit it). |
| **`GOOGLE_REDIRECT_URI`** | URL Google redirects to after OAuth | Must match **exactly** one of **Authorized redirect URIs** on that OAuth client. Set it to your real callback URL (e.g. `https://yourdomain.com/family-hub/auth/google/callback`). Use the same scheme and path your server exposes. |

### Google Calendar

The **Calendar** tab embeds your family calendar in the hub using these values (HTTPS Google Calendar URLs only; optional iframe `src` is extracted from pasted HTML).

| Variable | What it is | Where to find it |
| -------- | ----------- | ---------------- |
| **`GOOGLE_CALENDAR_ID`** | ID of the calendar to target (APIs, sharing, embeds) | **[Google Calendar](https://calendar.google.com/)** → hover the calendar in the sidebar → **⋮** → **Settings and sharing** → scroll to **Integrate calendar** → **Calendar ID** (often an email or `...@group.calendar.google.com`). If **`GOOGLE_CALENDAR_EMBED_CODE`** is unset, the tab builds a standard embed URL from this ID. |
| **`GOOGLE_CALENDAR_EMBED_CODE`** | Embed URL or full iframe HTML from Google | Same **Settings and sharing** page → **Integrate calendar** → copy the **embed code** (iframe) or the `https://calendar.google.com/...` URL from the `src` attribute. Prefer this when you want Google’s chosen view options. |

### Google Drive

| Variable | What it is | Where to find it |
| -------- | ----------- | ---------------- |
| **`GOOGLE_DRIVE_FOLDER_ID`** | Folder used as export or attachment root | **[Google Drive](https://drive.google.com/)** → open the folder in the browser. The URL looks like `https://drive.google.com/drive/folders/THIS_PART_IS_THE_ID` — copy **`THIS_PART_IS_THE_ID`**. |

### Application settings

| Variable | What it is | Where to find it |
| -------- | ----------- | ---------------- |
| **`APP_ENV`** | Logical environment name | Your choice (e.g. `development`, `staging`, `production`). Used for app behavior toggles if the code checks it. |
| **`APP_DEBUG`** | Verbose errors / debug mode | `true` or `false` (strings as in `env.example`). Only use **`true`** on trusted local or staging servers. |
| **`APP_URL`** | Base URL of this app | Same origin users use in the browser (e.g. `https://example.com/family-hub`), no trailing path beyond the app root unless your deployment requires it. Should align with **`GOOGLE_REDIRECT_URI`** host/path where applicable. |

### Export settings

| Variable | What it is | Where to find it |
| -------- | ----------- | ---------------- |
| **`EXPORT_FREQUENCY`** | How often exports are expected to run | Your choice (e.g. `daily`). Match how you schedule **`scripts/daily_export.php`** in cron. |
| **`EXPORT_RETENTION_DAYS`** | How long to keep export files (interpreted by app logic) | Integer number of days (e.g. `30`). |

## Directory Structure
familyHub/
├── api/                  # JSON POST endpoints (chores, groceries, meals, people, settings, expenses, …)
├── assets/               # Static assets
│   ├── css/              # CSS files
│   │   └── style.css
│   ├── js/               # JavaScript files
│   │   └── main.js
│   └── img/              # Images
├── config/               # Configuration files
│   ├── config.php
│   └── env.php           # Loads .env
├── data/                 # JSON data storage (not tracked in git)
│   ├── chores.json       # Chores, assignments, submissions, reviews
│   ├── people.json       # Profiles, roles, PIN hashes, currency balances
│   ├── family_settings.json   # Currency labels, timezone, week start, etc.
│   ├── expenses.json     # Head-of-household expense log
│   ├── stores.json       # Grocery store definitions
│   ├── grocery_lists.json     # Per-store shopping lines
│   ├── grocery_catalog.json   # Deduped catalog / recurring metadata
│   ├── groceries.json    # Legacy single-file groceries; migrated when detected
│   ├── meals.json        # Meal library (titles, tags, ingredients, shopping items)
│   └── meal_plans.json   # Active weekly plan: `weekStart` (Monday YYYY-MM-DD) and `slots` 0–6 × breakfast/lunch/dinner → meal id or empty
├── includes/             # PHP includes (db, persona, tab helpers, `api_bootstrap.php`, …)
│   ├── header.php
│   ├── footer.php
│   ├── db.php            # JSON file I/O (flock)
│   └── utils.php         # Shared helpers
├── exports/              # Export output (not tracked in git)
├── scripts/              # Cron / CLI helpers
│   └── daily_export.php
├── tabs/                 # Tab views included by `index.php`
│   ├── chores.php
│   ├── groceries.php
│   ├── meals.php
│   ├── calendar.php
│   ├── currency.php
│   └── settings.php
├── env.example           # Environment template (parsed by install.php)
├── install.php           # Web wizard to create .env when missing
├── .gitignore
├── .cursor/              # Cursor editor configuration and rules
├── readme.md
├── index.php             # Main entry point
├── AGENTS.md             # Agent / contributor notes
└── export.php            # `?type=` JSON export (same types as daily script)