Medication Tracker

The meds app

Tier 1, Lua. A personal medication tracker for families with chronic conditions. The architecture page describes how its parts fit together.

Schema

The views start with v_. v_active_medication is the readable one: every tracked medication in use with its refill status, refill eligibility, physical supply exhaustion, payer and early allowance. v_tracked_product lists the products of each tracked medication, and v_entry_mark their specialty and controlled marks as 1 or 0. The data model page is the reference for every table and view, and must change in the same commit as schema.sql.

Layout

Routes

Conventions to preserve

• Saving the reminder settings reuses the id of the stored profile row. That makes the save an amendment rather than a second row. Do not mint a new ULID on save.
• A form never sends a person to another page to add a record it needs. A drop-down of people, pharmacies or prescribers is the partial _select_or_new, read with quick_add.read. A catalog product is the partial _medication_picker, read with medication_pick.read. The products of a tracked medication are the partial _product_picker, read with product_pick.handle; they travel in hidden fields and the form comes back after each add or remove. The new records and the record of the form land in one batch.
• What a person takes is a tracked medication, not a catalog product. Fills and prior authorizations name person_medication_id. A product belongs to one tracked medication of a person, and a preferred name is unique within a person; the forms check both, through entries.with_product and entries.named.
• A fill, an authorization or a pasted fill for a product on no list of the person adds a tracked medication through entries.add, named after the product’s full name.
• The marks of a tracked medication come from its products through v_entry_mark, as 1 or 0. Lua treats 0 as true, so entries.lua turns them into booleans before a template reads them.
• The person tab chosen last lives in the browser, in static/person_tab.js. The server never stores it.
• The top bar and the footer are the page frame’s. The app draws its section tabs in views/_nav.lsp and nothing else around a page. [ui] navigation = "swap" in app.toml makes a link or a form inside the page replace only the main region, so a script runs once for the whole visit and never sees a fresh page. A script therefore listens on document, or sets up each new page on htmx:load and marks what it set up so it is never bound twice; it never calls location.replace to change the page, because that brings back the full reload. Lint rule PV111 refuses a <script> or a <link rel="stylesheet"> in a view; name the file in [ui] instead.
• A page-specific action, such as Print list, goes in the frame’s menu through menu(label, path, icon) at the top of the view that pv.render names, before its markup, never in a partial. An action every page needs would be an [[ui.menu]] entry in the manifest; the section tabs carry Setup, so the app declares none.
• A typed name that a record already has picks that record. No form adds a name twice.
• Every form that needs a product shows views/_product_box.lsp. The entry form wraps it in _product_picker.lsp: a search with product_q and step=find_product, and the results that come back checked as pick_<medication id>=yes are added together. The fill and authorization forms show the box with one radio button per result, named medication_choice, which medication_pick.read takes as the choice; medication_pick.searched says when the form must come back with results instead of saving. The review of pasted fills keeps the explicit _medication_picker.lsp. The browser asks GET /medications/search?q= for the same results as JSON. A typed search with nothing chosen never saves a form.
• Submit buttons are named step, never action: a control named action shadows form.action in WebKit, and the page frame’s script reads that property to post the form (Privatium issue 68).
• The fields of a new medication carry the route and the form a drug reference gave as hints in _route_ref and _dose_form_ref. The route, form and package type drop-downs win over the hints when a person sets them.
• A part of a form that a script may hide carries data-show-when="<field>=<value>". The server never relies on the script: the choice new with nothing typed is refused, and without the script a typed name wins over the drop-down.
• Prescription numbers are compared through fills.rx_key, without hyphens and spaces.
• A text box whose values repeat gets suggestions in _field, which renders a <datalist>. It needs no script.
• A row of medication that was copied from a drug reference keeps its rxcui, source and retrieved_on through every amendment. catalog_entry.read carries them.
• An amendment replaces the whole row. Read the row, change what the form changed, and append every column. A column left out of the append is cleared.
• Privatium does not apply a column DEFAULT on write. Supply every required value in Lua.
• Refill eligibility follows the latest fill’s payer, its rolling frame and allowance. Physical supply stacks across every fill, with no credit for gaps. Overdue uses supply; due uses eligibility. Controlled fills count across payers without a frame limit. Zero percent waits for physical exhaustion. Frame 0 counts the last fill only, and 3650 counts all history. Preserve the raw boolean in views because Lua treats 0 as true.
• A medication’s short name is Brand (Generic) strength release package unless a person typed another; the release part (24 HR XR, 12 HR XR, DR, EC) appears only when the product has one. A pack of tablets shows Pack of N in place of a strength. One product in two packages is two medications with one RxCUI. A second spelling of a product is a medication_alias row, never a second medication.
• A view that must run in any SQLite tool leaves out the DECIMAL columns.
• Every link goes through url(), so the app works unchanged in solo mode.
• SQL is a literal with bound parameters. The linter refuses SQL built by joining strings, so each table has its own statements.
• A form check lives in lib/validate.lua and returns a value, or nil and a sentence for the person. A form that is refused comes back with what was typed.
• A page address carries record ids and notice codes only. lib/page.lua turns a known code into a sentence and ignores any other.
• A record that other records point to is not removed. The removal page says what uses it.
• Every time and date on a screen is local. Read them from lib/clock.lua, and use date('now', 'localtime') in SQL.
• Pasted text is untrusted. portal_reader and the readers under lib/portals/ only take it apart; fills.read checks every value, and the add step reads the text again instead of trusting the review form.
• A close match in a search is a suggestion. Code never picks a medication from one. Two things pick one: a name that exactly one medication answers to, and a pasted name that starts with the brand or generic name of exactly one medication and holds its strength. The review of pasted fills shows the second kind, marked, before anything is added.
• The catalog can hold thousands of entries. A search narrows in SQL first and compares the few that are left in Lua, or a request runs out of steps. A page never lists the whole catalog.
• What the lookup script puts into a form is untrusted. medication_pick and catalog_entry check it like typed text. The script writes answers of a reference with textContent, never as markup.
• lib/starter_catalog.lua is written by tools/build_seed.py from the lists in tools/seed/. Change the lists and run the script. Do not edit the module by hand. lib/starter.lua loads it when a page finds the catalog empty; there is no sample/seed.jsonl, so the catalog lives in one place.
• A diagnostic message holds no field value. page.masked strips quoted values.
• Templates use <?= ?> only. There is no <?raw ?> here and there should not be.
• static/meds.css uses the shell’s color tokens. Inherit form controls and focus rings rather than duplicating the shell stylesheet.
• Every source file carries the project header from AGENTS.md, not Privatium’s.
• Health information will live in this app. Keep real names, dates of birth and medication records out of lib/starter_catalog.lua, tests and documentation.
• lib/starter_catalog.lua holds the starter catalog only. It never holds a person or a record about one, so it is safe in a real household.
• The invented household for tests and screenshots is tests/fixtures/sample-household.json. It stays outside the app folder and is never a Privatium seed, so no household is ever offered it. Its products are fixed ids of the starter catalog.

Extending it

Adding a field means one column in schema.sql, one input in the form, and one key in every pv.append call that writes the table. A dose form that the starter list lacks gets its icon in lib/form_icon.lua. The schema change rematerializes from the logs; existing events lack the key and the column is NULL for them. Adding a table means a CREATE TABLE with a grain comment and a section in the data model page.

Run the checks in the test how-to before finishing: privatium lint apps/meds, lua5.4 tests/lua/run.lua, python3 tests/test_supply.py, python3 tests/test_catalog.py and tests/smoke.sh. A new check in lib/validate.lua gets unit tests, and a new screen gets smoke tests, with at least one request that must be refused.