AI Builder & Large Uploads

The AI Builder

The onboarding wizard designs and provisions an application from a description. The AI Builder is what keeps that loop open afterwards.

Where to find it

Architect Panel → Data:

• AI Builder — describe a change, review what it proposes, apply it
• Sample Data — generate realistic test data for what you just built

Architect Panel → Configuration:

• Blueprint Packs — reusable starting points for common application shapes

The problem it solves

Once version one exists, the AI that built it traditionally stops being available, and every subsequent change means learning the platform's field architect. "Add a Suppliers table", "make Phone required", "we don't use Fax any more" are all things you should be able to simply say.

How to ask

Describe the outcome, not the mechanism.

• Good: "Track which supplier each part comes from." That gives it enough to design the relationship properly.
• Less good: "Add a foreign key to the parts table." That presumes an implementation which may not be the right one here.

Include the why where it is not obvious. "We need to record a second address because tenants often have a correspondence address" produces a better design than "add address2".

Review before applying

Changes are proposed for you to look at rather than applied silently. Read them, particularly anything touching data that already exists:

• Adding a field is safe.
• Making a field required interacts with every existing row that has it empty.
• Changing a type can lose data that does not convert.
• Removing a field is not reversible from here.

It works within the platform

What it produces is ordinary platform configuration — datastores, fields, forms, permissions. There is no separate AI-built layer to maintain, nothing is generated into a file you cannot edit, and anything it creates can be changed by hand afterwards exactly as if you had built it yourself.

Test with sample data

After a structural change, Sample Data generates realistic rows so you can see the forms and views behave before real data arrives. This is far more useful than it sounds — an empty datastore hides layout and validation problems that are obvious with fifty rows in it.

Blueprint packs

Blueprint Packs are reusable starting points for common application shapes. Where what you are building resembles something already modelled, starting from a pack and adjusting is faster and usually better-structured than describing it from nothing.

Worked example

A team running a supplier register asks: "we need to record which contract each supplier is on, and contracts have a start and end date". The builder proposes a Contracts datastore with date fields and a link from Supplier, plus the browse view and form to go with it. The team reviews the proposal, notices it made the end date required, changes that to optional because open-ended contracts exist, and applies it.

Where to be careful

Structural changes to a live system deserve the same care as any other change. Try them on a development instance where you have one, and avoid sweeping changes in the middle of a working day — a required field added at 11am is a required field every user meets immediately.

Recommendations

• One change at a time, reviewed and applied, rather than a paragraph of six.
• Say why, not how.
• Read the proposal for anything touching existing rows.
• Generate sample data and look at the forms before declaring it done.

Uploading Spreadsheets and Large Files

Describing a data model in prose is hard work when you already have it in a spreadsheet. Upload the file instead.

Where to find it

Architect Panel → Data:

• AI Builder — upload a file alongside your description
• Large Uploads — the chunked upload records and their state
• File Stores — where uploaded files are kept

Working from a spreadsheet

Upload the workbook and the builder reads its structure — the columns, the types, the values that actually appear — and proposes datastores and fields to match.

That is usually far closer to what you want than a description, because the spreadsheet already encodes decisions you would otherwise have to remember to mention: which fields are dates, which are numbers, which have a fixed set of values, which are optional in practice.

Tidy the sheet first — this matters most

The structure it infers is the structure you gave it, so preparation pays for itself:

• One header row, at the very top. Not a title, then a blank row, then headers.
• One table per sheet. Two tables side by side become one confused datastore.
• No merged cells. They destroy the column structure.
• No notes rows above the headers or between sections.
• Consistent types down a column. A date column with "TBC" in three rows will be read as text.
• Remove totals rows. A row saying "TOTAL 4,182" is not a record.

A spreadsheet organised for a human reader gives a noticeably worse result than a plain rectangle of data.

Large files

Uploads are chunked, so a file can be roughly a gigabyte rather than the tens of megabytes a single web request allows. The browser splits the file, the pieces are uploaded independently and reassembled on the server, and — because assembling a large file is not something a web request should do — the final step runs as a background job.

The tasks involved

• Background Jobs — dispatches and reaps queued work, including file assembly. Every minute.
• Document Text Extraction — indexes contents so uploaded documents are searchable. Every fifteen minutes.

Both ship disabled under Automation → Tasks. A large upload that reaches 100% and then appears to stall is almost always the Background Jobs task not running — the pieces are all there and nothing is assembling them.

What not to upload

The file contents reach the AI provider. Do not upload live personal data to design a schema.

A sample with realistic structure and invented values gives exactly the same design result without the disclosure — the builder is reading shapes, not people. Twenty made-up rows work as well as twenty thousand real ones.

Worked example

A team has tracked equipment in a spreadsheet for years: asset tag, description, location, purchase date, cost, custodian, and a Notes column. They copy the sheet, replace the names and tags with invented ones, delete the totals row at the bottom, and upload it. The builder proposes an Assets datastore with a date field, a currency field and a link to People for the custodian — which is the model they would have described, arrived at in one step.

Recommendations

• Send a sanitised sample, never live data.
• Fix the sheet before uploading, not the datastore afterwards.
• Enable Background Jobs first if you are uploading anything large.
• Check the inferred types before applying — dates and numbers read as text are the common miss.