Fatima/README.md

# Fatimas Calendar

A mobile-first Flask calendar with session authentication and infinite week scrolling.

Amounts and worked/vacation/sick statuses selected for dates are stored persistently in `instance/calendar.sqlite`, which is created automatically on first launch.

## Run it

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
waitress-serve --host=0.0.0.0 --port=9009 flask_fatima:app
```

To use a different port, substitute it in the command (for example,
`--port=8080`). The application exposes its WSGI callable as `flask_fatima:app`, so it
can also be used by platforms that ask for an application entry point.

Set the username, password, and Flask signing key in `config.yaml` before starting. This file is excluded from Git. Use `config.example.yaml` as the documented template when setting up another machine.

The two paid quick-choice buttons are configured in the same file:

```yaml
amounts:
  presets:
    - "55"
    - "27.50"
```

The €0 and custom-amount controls remain available automatically.

## Reverse proxy path

The app is served below `/fatima` by default. Configure the external path in
`config.yaml`:

```yaml
flask:
  url_prefix: "/fatima"
  log_file: "/tmp/fatima.log"
  database: "instance/calendar.sqlite"
```

Set `URL_PREFIX` in the environment to override this value at deployment time.
Use an empty value (`url_prefix: ""` or `URL_PREFIX=`) to serve from `/` instead.
The reverse proxy must preserve the prefix when forwarding requests to Waitress.

## Import the Excel calendar

Preview an import without changing the database:

```sh
python scripts/import_excel.py /path/to/fatima.xlsx
```

The preview prints the absolute workbook and database paths, current database
row counts and date range, discovered workbook values, and overwrite counts.
Check that the printed database path is the same file used by the production
app before applying the import.

Add `--apply` to import:

```sh
python scripts/import_excel.py /path/to/fatima.xlsx --apply
```

The importer refuses to write if the database is missing, has the wrong schema,
or the workbook contains no importable data. It creates a consistent SQLite
backup before writing, reads every imported value back after committing, and
prints the final row counts and date range. If production uses a non-default
database location, specify it explicitly:

```sh
python scripts/import_excel.py /path/to/fatima.xlsx --database /absolute/path/calendar.sqlite --apply
```

On the iPhone, visit `http://<your-computer-on-the-local-network>:9009/fatima/`.
Waitress listens on all network interfaces with the command above. For anything
exposed beyond a trusted home network, put it behind an HTTPS reverse proxy.

For deployments, `APP_CONFIG` can point to a YAML file elsewhere. `SECRET_KEY`,
`APP_USERNAME`, `APP_PASSWORD`, `DATABASE`, and `LOG_FILE` environment variables optionally
override the corresponding values. `DATABASE` should be an absolute path to the
SQLite file used in production.

The YAML `flask.database` path is resolved relative to the directory containing
the selected config file. If it is omitted, the app uses
`instance/calendar.sqlite` beside `flask_fatima.py`; it no longer relies on
Flask's environment-dependent inferred instance directory.

At startup, the app prints a database summary to the Waitress log containing the
resolved path, amount and status totals, distinct recorded-date total, and date
range. Compare that path and those totals with the importer's output to confirm
that both processes use the same database. The timestamped summary is also
appended to the configured `flask.log_file` each time the app starts. It defaults
to `/tmp/fatima.log` and can be overridden at deployment time with `LOG_FILE`.