Appearance
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 roles | services (required), resources (required), classes (optional) |
bookings settings | jtk/modules/bookings.json: {"v": 1, "settings": {…}}, each row of a list with its _key (contract 2: jtk/bookings.json, one bookings_config block) |
shop roles | products (required) |
shop settings | jtk/modules/shop.json: {"v": 1, "settings": {…}}, each row of a list with its _key |
| several units in one booking | count — 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) |
| times | time_of_day is minutes from local midnight; duration is minutes |
| an entry a module reads | a record: no body; a service collection is route: "none" with shown_on |
| in other languages | every entry a role names is in every language, never hidden: no untranslated: "hide", no visible: false in its translation |
| the words a booking says | the 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
| role | required | means |
|---|---|---|
services | yes | The 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. |
resources | yes | The 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. |
classes | no | The 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
| key | kind | in the file | required | means |
|---|---|---|---|---|
takes | duration | minutes | yes | How 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. |
costs | money | {"minor": 8500} | no | What 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. |
per | select | an option's value | no | What 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. |
rates | list | rows, each with its _key | no | What 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. |
scale | select | an option's value | no | What 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. |
fewest | number | a number | no | The 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. |
most | number | a number | no | The 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
| key | kind | in the file | required | means |
|---|---|---|---|---|
hours | list | rows, each with its _key | no | This 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. |
does | ref | ref: {to: [<services>], many: true} — a list of ids | no | The 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. |
seats | number | a number | no | How 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. |
spots | number | a number | no | How 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. |
marks | text | words | no | What 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. |
class | ref | an entry's id | no | Which 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
| key | kind | in the file | required | means |
|---|---|---|---|---|
costs | money | {"minor": 8500} | no | What 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
| key | kind | min / max | required | edited by |
|---|---|---|---|---|
zone | select: Europe/Kyiv · Europe/Warsaw · Europe/Berlin · Europe/Zurich · Europe/Vienna · Europe/Prague · Europe/London · Europe/Lisbon | — | yes | the owner |
hours | list | up to 21 | no | the owner |
scale | select: hourly · daily | — | no | the studio |
closed | list | up to 60 | no | the owner |
slot_every | duration | 5 – 240 | no | the studio |
buffer | duration | up to 1440 | no | the owner |
hand_out | time_of_day | — | no | the owner |
hand_back | time_of_day | — | no | the owner |
hands_over | bool | — | no | the studio |
buffer_stay | duration | up to 1440 | no | the owner |
lead | duration | up to 20160 | no | the owner |
horizon | number | 1 – 730 | no | the owner |
party | number | 1 – 50 | no | the owner |
quantity | number | 1 – 20 | no | the owner |
kind | text: apartments · car_rental · clinic · coworking · equipment_rental · hotel · photo_studio · restaurant · salon · sessions | up to 40 | no | the studio |
kit | text | up to 40 | no | the studio |
kit_version | text | up to 40 | no | the studio |
words | list | up to 200 | no | the studio |
combine | bool | — | no | the owner |
page | text | up to 200 | no | the studio |
contact | select: either · both | — | no | the owner |
confirm | select: auto · by_hand | — | yes | the owner |
hold | duration | 15 – 20160 | no | the studio |
cancel_until | duration | up to 20160 | no | the owner |
payment | select: no · deposit · full | — | yes | the owner |
deposit | number | 1 – 100 | no | the 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
| role | required | means |
|---|---|---|
products | yes | what 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
| key | kind | in the file | required | means |
|---|---|---|---|---|
title | text | words | yes | What the product is called, in every language of the site — required, as every entry's title is. |
options | list | rows, each with its _key | no | The 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. |
variants | list | rows, each with its _key | yes | What 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. |
customizations | list | rows, each with its _key | no | What 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. |
tracked | bool | words | no | Whether stock is counted. A product that is not tracked — made to order — is never sold out. Without it, tracked. |
size_class | select | an option's value | no | What size the shipping rates treat the product as: a letter, a parcel or bulky. Without it, a parcel. |
tax_code | text | words | no | The 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_number | text | words | no | The customs tariff number, needed only when the shop ships abroad. |
made_in | text | words | no | The 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
| key | kind | min / max | required | edited by |
|---|---|---|---|---|
zones | list | — | no | the owner |
methods | list | — | no | the owner |
kit | text | up to 40 | no | the studio |
kit_version | text | up to 40 | no | the 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.