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:

   npm install
   

2. Create the production build:

   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

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

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, and the canonical URL builder lives in 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.