lonc/README.md

# Lonc

Lonc is a responsive PWA frontend for household kitchen stock and labeling workflows backed by Tryton APIs.

## Stack

- Vite for a lightweight client build
- Bootstrap 5 for layout and form styling
- Alpine.js for local component state and interaction
- Plain `fetch()` service modules for backend communication
- Static manifest and service worker for PWA installability

## Scripts

- `npm install`
- `npm run dev`
- `npm run build`
- `npm run preview`

## Production installation

### Requirements

- Node.js 20 or newer
- npm 10 or newer
- A static web server for the generated `dist/` directory
- A Tryton backend that exposes the `kitchen` user application and kitchen endpoints

### Build for production

1. Install dependencies:

   ```bash
   npm install
   ```

2. Create the production build:

   ```bash
   npm run build
   ```

3. Deploy the generated `dist/` directory to your web server.

### Serve the built app

Lonc is a static frontend. In production you do not run a Node.js application server for it. You build the app once and serve the files from `dist/` with a normal static web server such as:

- Nginx
- Apache
- Caddy
- a CDN/static hosting platform

The frontend uses hash-based routing, so no special SPA history fallback is required for route handling.

### Example deployment flow

```bash
npm install
npm run build
rsync -av dist/ /var/www/lonc/
```

Then configure your web server to serve `/var/www/lonc` as a static site.

### Runtime configuration

The application does not require build-time environment variables for the Tryton connection. Users configure the following in the login screen:

- Tryton server base URL
- database name
- user login

Authentication is done with Tryton user application keys for the `kitchen` application, not with JSON-RPC session login.

### Reverse proxy / browser requirements

If the frontend and Tryton backend are served from different origins, the Tryton server must allow cross-origin requests from the frontend origin.

At minimum, production should ensure:

- `Authorization` headers are accepted for API requests
- CORS is configured for the frontend origin when origins differ
- HTTPS is enabled in production

### PWA notes

For installability and service worker support:

- serve `manifest.webmanifest` with an appropriate web manifest content type
- make sure `service-worker.js` is reachable from the deployed site root
- avoid aggressive caching on `index.html` during upgrades so new builds are picked up reliably

### Smoke test after deployment

After deployment, verify that:

1. the site loads from the production URL
2. login can create a Tryton user application key
3. kitchen selection loads successfully
4. stock review and label creation can reach the backend
5. the browser can install the app as a PWA

## Project structure

```text
public/
  icons/
  manifest.webmanifest
  offline.html
  service-worker.js
src/
  api/
  app/
  components/
  features/
  styles/
  main.js
index.html
package.json
```

## Current MVP features

- Login/configuration screen for Tryton server URL and database
- Session restore and logout shell
- Active kitchen selection and switching
- Dashboard with quick actions
- Label creation flow with item lookup, location loading, preview, and stock entry creation
- Stock list with search and filters
- Stock detail page with stock adjustment workflow
- PWA manifest, icons, service worker, and offline fallback

## Tryton integration assumptions

The frontend is intentionally organized around adapter-style API modules so the exact backend contract can be finalized without rewriting screens.

Default endpoint placeholders live in [`src/app/config.js`](/Users/blaz/PycharmProjects/lonc/src/app/config.js), and the canonical URL builder lives in [`src/api/client.js`](/Users/blaz/PycharmProjects/lonc/src/api/client.js).

Expected shapes today:

- Kitchen-scoped application resources use:
  `/{database}/kitchen/{kitchen_id}/{resource}`
- User application key management uses:
  `/{database}/user/application/`
- Non-kitchen-scoped authenticated resources currently assume:
  `/{database}/{resource}`

- `POST /{database}/user/application/`
  Sends `{ user, application: "kitchen" }` and returns the application key as a JSON string.
- `DELETE /{database}/user/application/`
  Sends `{ user, key, application: "kitchen" }` and disconnects the client.
- `GET /{database}/kitchen/kitchens`
  Requires `Authorization: Bearer <application_key>` and is used as the current lightweight verification call after key approval.
  Returns `{ data: [...] }` or `{ kitchens: [...] }`.
- `GET /{database}/kitchen/items?search_name=...`
  Returns item definitions for autocomplete.
- `POST /{database}/kitchen/items?label=1`
  Creates a stock item plus label-related output on the backend side.
- `POST /{database}/kitchen/items?label=1&preview=1`
  Returns an image blob, `{ imageUrl }`, or `{ imageSvg }` for in-browser preview.
- `GET /{database}/kitchen/locations`
  Returns a nested location tree.
- `GET /{database}/kitchen/{kitchen_id}/stock`, `GET /{database}/kitchen/{kitchen_id}/stock/:id`, `POST /{database}/kitchen/{kitchen_id}/stock/:id/adjust`
  Back the stock overview, creation, and adjustment workflows.

## Notes

- Hash-based routing is used to keep static deployment simple.
- Local storage only keeps non-sensitive app config, session payload, active kitchen, and label draft state.
- Kitchen context now lives in the URL path instead of a custom header.
- `includeKitchen: false` in the API client only removes the kitchen path segment; it does not disable bearer authentication.