okaasan 0.0.8

Two Modes

The application has two operating modes:

• Dev / Server mode: the full application with a FastAPI backend, SQLite database, and a React (Vite + Chakra UI) frontend. All features are read-write.

• Static mode: a pre-built, read-only version of the site that can be deployed to GitHub Pages (or any static host) without a server. During the static build the server’s API responses are cached as JSON files and the frontend reads those instead of calling a live API.

Repository Layout

recipes/
├── install.sh                      # one-line installer (systemd + venv)
├── setup.py                        # pip-installable package definition
├── requirements.txt                # Python dependencies
├── README.rst
│
└── okaasan/
    ├── main/                       # CLI entry point (okaasan command)
    │
    ├── server/                     # FastAPI backend
    │   ├── server.py               # app factory, middleware, startup hooks
    │   ├── run.py                  # uvicorn runner
    │   ├── updater.py              # auto-update from PyPI
    │   ├── gitsync.py              # git-based data backup
    │   │
    │   ├── recipe/                 # Recipe feature
    │   │   ├── routes.py           #   recipe CRUD
    │   │   ├── route_ingredient.py #   ingredient CRUD
    │   │   ├── route_units.py      #   unit conversion CRUD
    │   │   ├── models.py           #   Recipe, Ingredient, Category, …
    │   │   └── facts.py            #   nutrition facts DB
    │   │
    │   ├── calendar/               # Calendar feature
    │   │   ├── routes.py
    │   │   └── models.py           #   Event
    │   │
    │   ├── tasks/                  # Tasks feature
    │   │   ├── routes.py
    │   │   └── models.py           #   Task
    │   │
    │   ├── articles/               # Notes / Articles feature
    │   │   ├── routes.py
    │   │   └── models.py           #   Article, ArticleBlock
    │   │
    │   ├── budget/                 # Budget feature (stub)
    │   │   ├── routes.py
    │   │   └── models.py           #   Receipt, ReceiptItem, Expense
    │   │
    │   ├── product/                # Product / Pantry feature (stub)
    │   │   ├── routes.py
    │   │   └── models.py           #   Product, ProductInventory
    │   │
    │   ├── models/                 # Shared models & re-export facade
    │   │   ├── common.py           #   SQLAlchemy Base class
    │   │   ├── keyvalue.py         #   generic key-value store
    │   │   ├── user.py
    │   │   └── __init__.py         #   re-exports all feature models
    │   │
    │   ├── integrations/           # Third-party service adapters
    │   │   ├── gcalendar.py        #   Google Calendar (service account)
    │   │   ├── route_gcalendar.py
    │   │   ├── route_weather.py    #   Open-Meteo weather
    │   │   ├── route_usda.py       #   USDA FoodData Central
    │   │   ├── route_messaging.py  #   Telegram
    │   │   └── route_garmin.py     #   Garmin (stub)
    │   │
    │   ├── projects/               # Graph / Blockly tools
    │   ├── route_keyvalue.py       # generic key-value API
    │   ├── route_images.py         # image upload API
    │   └── route_jsonstore.py      # generic JSON file store API
    │
    ├── cli/                        # CLI commands
    │   └── staticwebsite.py        # static site generator
    │
    └── ui/                         # React frontend (Vite + TypeScript)
        ├── src/
        │   ├── App.tsx             # router & top-level layout
        │   ├── components/
        │   │   ├── home/           #   dashboard & day detail
        │   │   ├── recipes/        #   recipe CRUD, ingredients, units
        │   │   ├── meal-planning/  #   weekly meal planner
        │   │   ├── calendar/       #   calendar view
        │   │   ├── tasks/          #   tasks & routine
        │   │   ├── settings/       #   app settings pages
        │   │   ├── budget/         #   budget & expense tracker
        │   │   ├── inventory/      #   grocery receipts & pantry
        │   │   ├── content/        #   notes & article views
        │   │   ├── scratch/        #   misc tools (3D print, wood, …)
        │   │   ├── common/         #   shared modals & widgets
        │   │   ├── article/        #   rich block editor & renderer
        │   │   └── ui/             #   UI primitives (color mode, toaster)
        │   ├── services/           #   API client, types, Telegram SDK
        │   ├── utils/              #   date, fraction, unit helpers
        │   └── layout/             #   shell layout & sidebar
        └── dist/                   # production build (bundled into package)

Local Development

1. Backend: start the FastAPI server with hot-reload:

   cd recipes
   pip install -e ".[all]"
   python -m okaasan.server.run          # http://localhost:5001

   The server reads OKAASAN_DATA (or FLASK_STATIC) for the data directory and creates a SQLite database there.

2. Frontend: start the Vite dev server with HMR:

   cd recipes/okaasan/ui
   npm install
   npm run dev                           # http://localhost:5173

   The Vite dev server proxies /api/* requests to the backend at localhost:5001.

3. Build the UI for production:

   cd recipes/okaasan/ui
   npm run build                         # outputs to ui/dist/

   The built files are served directly by FastAPI in production (no separate web server needed).

Static Deployment (GitHub Pages)

The static build turns the live app into a set of HTML + JSON files that can be hosted anywhere without a server:

1. The static site generator (okaasan staticwebsite) starts the server locally, crawls every API route, and caches each response as a .json file.

2. The React frontend is built with a base_path matching the GitHub Pages URL.

3. At runtime the frontend detects static mode and reads from the cached JSON files instead of calling the API.

To set it up from the Settings page:

1. Configure Git Backup with a GitHub repository.

2. Click Setup GitHub Pages to generate a deploy workflow.

3. Push: GitHub Actions builds and publishes the static site automatically.

The result is a public, read-only version of your data at https://<user>.github.io/<repo>/.