Skip to content

Modules ​

A module is a domain the platform keeps a ledger for — rows about what happened between the business and a visitor. A schema turns one on under modules, by name, and points each of its roles at a collection of the same schema: the module works on entries the client already edits, never on a second copy.

jsonc
"modules": {
  "bookings": { "services": "services", "resources": "masters" }
}

At a glance ​

the declaration"modules": { "<module>": { "<role>": "<collection>" } } in jtk/schema.json
bookings rolesservices (required), resources (required), classes (optional)
bookings settingsjtk/modules/bookings.json: {"v": 1, "settings": {…}}, each row of a list with its _key (contract 2: jtk/bookings.json, one bookings_config block)
shop rolesproducts (required)
shop settingsjtk/modules/shop.json: {"v": 1, "settings": {…}}, each row of a list with its _key
several units in one bookingcount — on GET /api/availability and in POST /api/book; never units, nights or days, which the edge drops
money{"minor": 4500}, whole minor units of the site's one currency — 45.00 (contract 2: the bare 4500)
timestime_of_day is minutes from local midnight; duration is minutes
an entry a module readsa record: no body; a service collection is route: "none" with shown_on
in other languagesevery entry a role names is in every language, never hidden: no untranslated: "hide", no visible: false in its translation
the words a booking saysthe dictionary; any other key is JTK_W_WORD_UNKNOWN

The set is closed. A name not below is refused with JTK_E_MODULE_UNKNOWN; a role left unbound, a role pointed at a collection that is not declared, or an entry type that cannot carry what the module reads is refused with JTK_E_MODULE_ROLE_INVALID.

What a module reads from an entry is a field of the entry's own type, declared by the site like any other and named by the key below. The entry type may carry anything else besides — a description, a picture, a price written in words for the page — and the module reads none of it. A key it reads must have the kind it reads it as, and a required one must be declared, though an entry may leave it empty: what that does is said beside each.

The module's settings are a document of ours: the owner fills them in in the panel (under the diary), a save writes them to jtk/modules/<module>.json so that a page can read them, and import_branch reads that file back into the diary. So the file is also how an agent seeds the diary before anybody opens the panel — the module's own document, v and its settings, every row of a list with its _key (the files under jtk/ shows it whole). On the scaffold npx @jtakeit/astro schema seeds an empty one when the schema turns the module on:

json
{ "v": 1, "settings": { "zone": "Europe/Zurich", "confirm": "auto", "payment": "no",
                        "hours": [{ "_key": "mon", "day": "monday", "opens": 540, "closes": 1020 }] } }

A file in any other shape — the settings as top-level keys, a key beside v and settings, a value a field's kind refuses — is refused with JTK_E_DOCUMENT_INVALID by import_branch and by validate_schema, rather than read as an empty diary. Its fields are listed so that a seed and a page both know what the owner will be asked; a site does not declare them. On contract 2, the older contract, the same settings are one block of the module's config type in jtk/<module>.json — {"blocks": [{"type": "bookings_config", "v": 1, …}]} — refused in another shape with JTK_E_MODULE_FILE_INVALID.

An entry a module reads is a record, not a post: short fields, no body, and for services route: "none", shown on the page that lists them. What the module holds — the owner's hours, the services' prices — lives once; a page block that types it again as text is a second copy. The judge says both as advice, refusing nothing (JTK_W_MODULE_POST, JTK_W_MODULE_TWIN).

What a module books is in every language. An entry of a collection a role names is booked by the diary in any language's form, so it is never held back in a language: the collection may not say untranslated: "hide" (JTK_E_ATTRIBUTE_INVALID), and a translation of its entry may not say visible: false (JTK_E_DOCUMENT_INVALID). Where nobody translated it, a language shows the original's words — translations.

bookings ​

Appointments: what a visitor may book, who or what it occupies, and when the business is open.

Roles ​

rolerequiredmeans
servicesyesThe collection of things that may be booked. Each entry carries how long it takes in a takes field, and — to be payable online — what it costs in a costs field, in minor units of the site's currency. A service without costs is bookable and not payable, which is an ordinary state.
resourcesyesThe collection of things that get occupied — masters, chairs, tables. One entry is a solo business. An entry may carry its own weekly hours (a list of day, opens, closes rows, the same shape as the module's), and is then offered only inside them and inside the business's own.
classesnoThe collection of classes the resources are grouped in — a fleet's Економ, Комфорт, Бус. Optional: without it the diary draws its resources in one list. A class is an entry of its own so that it can carry its price and the site can show it.

What it reads from an entry of services ​

keykindin the filerequiredmeans
takesdurationminutesyesHow long one appointment takes, in minutes. An entry that leaves it empty is not offered: nothing can be laid on a grid without a length.
costsmoney{"minor": 8500}noWhat it costs, in minor units of the site's currency — 8500 is CHF 85.00. Without it, and without rates, the service is bookable and not payable, whatever the module's payment setting says. A price written in words for the page is a different field.
perselectan option's valuenoWhat the price is counted in (wiki/70): booking — once, whatever the party, a haircut is one head — or person, the price times the party: a class per place, a tour, shoes. Without it, booking. A service with no takes and a price is an add-on — taken only beside a timed service in one visit, priced once per visit, times the party when person.
rateslistrows, each with its _keynoWhat it costs by the hour of the week, instead of costs and never beside it: rows of day, from, until and costs, like a week of opening hours with a price on each row — a lane 25 € before six and 42 € on a Friday night. Each unit of a booking (one takes) is priced by the row covering its start, and the booking is the sum; Friday 18:00–21:00 at a before-eight and an after-eight price is two hours at one and one at the other. Rows may not overlap on a day. An open hour no row covers is not sold: the form does not offer it for this service, and the panel says which hours those are.
scaleselectan option's valuenoWhat this service is sold in: hourly — an appointment at a time inside opening hours — or daily, whole days from midnight. Without it, the module's scale. One business may sell both: a three-hour photo session and a day's hire of the same van.
fewestnumbera numbernoThe fewest of this service a visitor may take at once — nights, for a service that takes a day; hours, for one that takes an hour. Without it, one.
mostnumbera numbernoThe most of this service a visitor may take at once. Without it, thirty by the day and one by the hour. A week sold as one service is takes of seven days with fewest and most both one; a day is takes of one day, one to thirty; a studio's hour is takes of sixty, one to twelve — the length and the price times the hours taken.

A rates row is day (select: monday · tuesday · wednesday · thursday · friday · saturday · sunday), from (time_of_day), until (time_of_day), costs (money), from_unit (number), until_unit (number).

What it reads from an entry of resources ​

keykindin the filerequiredmeans
hourslistrows, each with its _keynoThis resource's own week, in the same rows as the business's hours. Without it the resource keeps the business's hours. A closing time before the opening one is after midnight: 18:00–01:00 is one row.
doesrefref: {to: [<services>], many: true} — a list of idsnoThe services this resource performs: on contract 3 one reference to several entries of the services collection, {"to": ["services"], "many": true}, holding their ids; on contract 2, the older contract, rows naming a service's slug (service), best declared as a ref into the services collection. Either way the admin offers a choice and refuses a service that does not exist. Without it, or empty, the resource does all of them. Natalie does gel; Mara does pedicure.
seatsnumbera numbernoHow many people fit, for a resource booked whole — a table, a private room. A booking's party has to fit, and the smallest resource that fits is offered first. Leave it out for a chair.
spotsnumbera numbernoHow many bookings share one slot, for a resource booked by the place — a class, a tour, a tasting. A resource with spots is a session: it offers the start of each of its hours rows and nothing in between. Never together with seats.
markstextwordsnoWhat tells this one from its twins, said after its name — a car's colour and plate («білий · AA1234BB»), a flat's floor, a tool's serial number. The diary, the customer's page and the letters say «VW Combi · білий · AA1234BB». One field for every business rather than a colour and a plate for cars.
classrefan entry's idnoWhich class this resource is in — Економ, Комфорт, Бус — as a ref into the collection bound as the module's classes. The diary groups resources by it; a resource without one is drawn under «without a class». A class renamed keeps its resources: the reference holds the class's id (its slug on contract 2, which never changes).

A hours row is day (select: monday · tuesday · wednesday · thursday · friday · saturday · sunday), opens (time_of_day), closes (time_of_day).

What it reads from an entry of classes ​

keykindin the filerequiredmeans
costsmoney{"minor": 8500}noWhat one unit of the service — a night, a day of hire — costs in this class, in minor units of the site's currency. It replaces the service's price for a resource of this class rather than adding to it; the service is then the unit — a night — and not the price.

The settings document ​

keykindmin / maxrequirededited by
zoneselect: Europe/Kyiv · Europe/Warsaw · Europe/Berlin · Europe/Zurich · Europe/Vienna · Europe/Prague · Europe/London · Europe/Lisbon—yesthe owner
hourslistup to 21nothe owner
scaleselect: hourly · daily—nothe studio
closedlistup to 60nothe owner
slot_everyduration5 – 240nothe studio
bufferdurationup to 1440nothe owner
hand_outtime_of_day—nothe owner
hand_backtime_of_day—nothe owner
hands_overbool—nothe studio
buffer_staydurationup to 1440nothe owner
leaddurationup to 20160nothe owner
horizonnumber1 – 730nothe owner
partynumber1 – 50nothe owner
quantitynumber1 – 20nothe owner
kindtext: apartments · car_rental · clinic · coworking · equipment_rental · hotel · photo_studio · restaurant · salon · sessionsup to 40nothe studio
kittextup to 40nothe studio
kit_versiontextup to 40nothe studio
wordslistup to 200nothe studio
combinebool—nothe owner
pagetextup to 200nothe studio
contactselect: either · both—nothe owner
confirmselect: auto · by_hand—yesthe owner
holdduration15 – 20160nothe studio
cancel_untildurationup to 20160nothe owner
paymentselect: no · deposit · full—yesthe owner
depositnumber1 – 100nothe owner

A hours row is day (select: monday · tuesday · wednesday · thursday · friday · saturday · sunday), opens (time_of_day), closes (time_of_day).

A closed row is from (date), until (date), who (text).

A words row is lang (select: en · es · fr · pt · ru · de · it · uk), key (text), text (text).

The keys a words row may name are the dictionary's, and nothing else: the words a booking may say lists them. A key not in that list is advised as JTK_W_WORD_UNKNOWN.

shop ​

A shop: products with options, variants and customizations, stocked by SKU and sent by the owner's zones and rates. Its stock is never in a file: the agent that builds the shop sets each SKU's starting count with set_stock until the SKU first sells, the owner corrects it in the panel, and a product page asks what is left of each variant by the shop protocol. A buyer checks out through the protocol and pays on the business's own Stripe account; a paid order is told where the site's enquiries go, the buyer gets a confirmation, and the owner runs the shop in the panel — its products, stock, shipping and orders, fulfilled with a tracking number or refunded with the items put back. A site draws it with the kit's storefront, a base to copy, and jtk import products brings its catalogue in.

Roles ​

rolerequiredmeans
productsyeswhat the shop sells: an entry a product, its variants priced and stocked by SKU; a hidden product (visible: false) is held only to its SKUs and its 2,000 variants until it is shown

What it reads from an entry of products ​

keykindin the filerequiredmeans
titletextwordsyesWhat the product is called, in every language of the site — required, as every entry's title is.
optionslistrows, each with its _keynoThe axes a product varies along — size, colour — as rows of a name and its values, each with a label. As many as a product needs: its variants, at most 2,000, are the limit. A variant names a value by its key, so renaming or translating one breaks nothing. Never localized: a translation gives the words, by key.
variantslistrows, each with its _keyyesWhat is sold: rows of a sku, a price, and — when there are options — the picks that say which value of each. A simple product is one variant without picks. The SKU is unique on the site and is what stock and orders are kept by; the price is one amount, with no qualifiers; weight is whole grams; on_sale takes a variant off sale without deleting it — without it, on sale. A SKU an order named stays its variant's: the save and the import refuse a draft that changes it or gives it to another variant (JTK_E_SKU_ORDERED); a variant removed, like a product deleted, keeps its SKUs from every other. At most 2,000 a product. Never localized: SKUs, prices and picks are the original's.
customizationslistrows, each with its _keynoWhat a buyer may be asked that is not stocked — a colour for each part, a name on a tag: rows of a name, a kind (choice, yes_no or text), whether a choice or a text is required (a yes_no is ticked or not, and is never required), a max of characters for a text, the choices of a choice (each a label and what it adds) and what a yes_no or a text adds to the price — each one amount, with no qualifiers. Never localized.
trackedboolwordsnoWhether stock is counted. A product that is not tracked — made to order — is never sold out. Without it, tracked.
size_classselectan option's valuenoWhat size the shipping rates treat the product as: a letter, a parcel or bulky. Without it, a parcel.
tax_codetextwordsnoThe Stripe tax code the product is taxed under where the business charges VAT: txcd_ and eight digits — txcd_35010000 for printed books. Without one, ordinary goods (txcd_99999999); Stripe applies each country's rate, and no rate is kept here.
tariff_numbertextwordsnoThe customs tariff number, needed only when the shop ships abroad.
made_intextwordsnoThe country the product is made in, needed only when the shop ships abroad.

A options row is name (text), values (list).

A variants row is sku (sku), price (money), weight (number), picks (picks), on_sale (bool).

A customizations row is name (text), kind (select: choice · yes_no · text), required (bool), max (number), choices (list), adds (money).

The settings document ​

keykindmin / maxrequirededited by
zoneslist—nothe owner
methodslist—nothe owner
kittextup to 40nothe studio
kit_versiontextup to 40nothe studio

A zones row is name (text), countries (list).

A methods row is zone (text), name (text), pickup (bool), price (money), bands (list), free_above (money), free_bulky (bool).

The other half of a module is a page's, once the module is on: for bookings, bookings on the site is what a booking page draws, and the booking protocol the addresses it talks to; for the shop, the shop on the site is what a product page, the cart and the checkout step draw and how the catalogue comes in, and the shop protocol the addresses they talk to — what is left, the cart's shipping, the checkout and the order's page.