1. Getting Started

Structa is a native macOS database application builder. It lets you create relational databases, design visual forms, write automation scripts, and publish your data to the web — all from a single application running on your Mac. Think of it as a modern, native alternative to FileMaker Pro, built with Swift and SQLite.

1.1 Projects & Workspace

Everything in Structa revolves around a project. A project is a self-contained database that holds your tables, fields, relationships, forms, scripts, and data. You can have multiple projects open at once — each opens in its own window.

To create a new project, use File > New Project... (Cmd+N). Choose a location and name, then click Save. Structa creates a .structa package and opens it in Design mode.

To open an existing project:

• Double-click a .structa file in Finder.
• Use File > Open Project... (Cmd+O).
• Choose from File > Recent Projects.

The workspace consists of a sidebar (left) for navigation and a detail area (right) that shows the active editor. Sidebar sections include Project, Design (Tables, Relationships, Forms, Scripts), Data (Browse Data), Deploy (Publish, Host Mode), and Configuration (Settings).

1.2 The .structa Format

A .structa file is a macOS package — a directory that Finder displays as a single file. Inside the package:

MyProject.structa/
    manifest.json          ← Project metadata (name, version, dates)
    project.sqlite         ← SQLite database (schema + data)
    assets/                ← File attachments and images
    templates/             ← Exported template bundles
    snapshots/             ← Autosave and recovery snapshots
    previews/              ← Form preview image cache
    exports/               ← CSV and other export output
    logs/                  ← Diagnostic logs

The manifest.json records the format version, application version, project name, creation and modification timestamps, default publish profile, and startup mode. The project.sqlite file contains both Structa's internal metadata tables and all user-created data tables.

1.3 Creating Your First Project

1. Launch Structa. The Welcome screen appears.
2. Click "New Project" (or press Cmd+N). Choose a location and name, then click Save.
3. Navigate to Tables in the sidebar.
4. Click "Add Table" and enter a display name (e.g., "Contacts").
5. Add fields by clicking the "+" button: First Name (Text), Last Name (Text), Email (Email), Phone (Text).
6. Save with Cmd+S.
7. Switch to Data Browser (Cmd+Shift+R) and start adding records.

1.4 The Interface

1.5 Application Modes

Structa operates in one of three modes, switchable from the Runtime menu or View > Mode:

2. Schema Designer

The Schema Designer is where you define the structure of your database. Navigate to Tables in the sidebar to access it. Here you create tables, add fields, set validation rules, and manage schema changes.

2.1 Creating Tables

Click the "+" button at the bottom of the table list. Enter a Display Name (e.g., "Invoice") and an optional Plural Display Name (e.g., "Invoices"). Structa generates a sanitized internal name automatically — lowercased, spaces become underscores, non-alphanumeric characters are stripped, and names starting with a digit are prefixed with t_.

Every table automatically receives a _rowid INTEGER PRIMARY KEY AUTOINCREMENT column as its first column, providing a stable unique identifier for every record.

2.2 Field Types Reference

Structa supports 18 field types. Add a field by clicking the "+" button in the field list and selecting a type:

2.3 Validation Rules

Each field can have one or more validation rules that are checked when a record is saved:

Validation errors appear inline in the Data Browser and Form Designer. If a record fails validation, it cannot be committed.

2.4 Schema Migrations

When you modify a table's structure (add, rename, or remove a field; change a field type), Structa performs an automatic schema migration. The process:

1. A recovery snapshot is created before any changes are made.
2. Structa uses SQLite's ALTER TABLE when possible (adding columns, renaming columns).
3. For destructive changes (removing columns, changing types), Structa creates a new table, copies data with type coercion, drops the old table, and renames the new one.
4. Foreign key relationships and indexes are rebuilt as needed.

3. Relationship Designer

The Relationship Designer provides a visual canvas for defining how your tables relate to one another. Navigate to Relationships in the sidebar to open it.

3.1 The Canvas

Each table appears as a node on the canvas showing its name and fields. Relationships are drawn as lines connecting a foreign key field to its target table's primary key. You can pan the canvas by dragging the background and zoom with the scroll wheel or trackpad pinch gesture.

3.2 Cardinality Types

3.3 Creating Relationships

1. Ensure at least one table has a foreignKey field pointing to another table.
2. In the Relationship Designer, click "Add Relationship".
3. Select the source table and its foreign key field.
4. Select the target table (the table being referenced).
5. Choose the cardinality (One-to-One, One-to-Many, or Many-to-Many).
6. Optionally enable Cascade Delete (deleting a parent automatically deletes related children).
7. Click Save. The relationship appears as a line on the canvas.

3.4 Referential Integrity

Structa enforces foreign key constraints at the application level. When you attempt to delete a record that has related child records, Structa will:

• With Cascade Delete enabled: Delete all child records automatically.
• Without Cascade Delete: Show an error and prevent the deletion until all child records are removed or reassigned.

Orphaned records (foreign key values pointing to non-existent parents) are flagged in the Data Browser with a warning indicator.

4. Calculation Engine

The Calculation Engine powers computed fields, script conditions, search criteria, and validation formulas. Formulas are written in a simple expression language that supports field references, operators, function calls, and literal values.

4.1 Formula Syntax

Formulas follow this general pattern:

functionName(argument1, argument2) & " literal text " & fieldReference

Key rules:

• String literals use double quotes: "hello"
• Number literals are bare: 42, 3.14
• Boolean literals: true, false
• Field references use the field's internal name: firstName, totalAmount
• Related field references use dot notation: Company::name
• Function names are case-insensitive: Upper() = upper()
• Parentheses control evaluation order: (price + tax) * quantity

4.2 Operators

Operator precedence (highest to lowest): NOT, * / %, + -, comparison, AND, OR. Use parentheses to override.

4.3 Field References

Reference fields from the current table by their internal name: firstName. Reference fields from related tables using double-colon notation: TableName::fieldName. Related references follow the relationship graph — the tables must be connected through a defined relationship.

4.4 Formula Examples

// Full name
firstName & " " & lastName

// Line total with tax
quantity * unitPrice * (1 + taxRate / 100)

// Age from birth date
year(today()) - year(birthDate)

// Status label
if(isempty(completedDate), "In Progress", "Completed")

// Conditional discount
case(
    totalAmount >= 1000, totalAmount * 0.9,
    totalAmount >= 500,  totalAmount * 0.95,
    totalAmount
)

5. Formula Function Reference

Structa provides 118 built-in functions organized into 13 categories (string, math, conditional, null, date, conversion, logical, crypto, statistics, advanced math & calculus, system / Get(), arrays, and dynamic / metadata functions). All function names are case-insensitive.

5.1 String Functions (17)

5.2 Math Functions (8)

5.3 Conditional Functions (2)

5.4 Null Functions (1)

5.5 Date & Time Functions (12)

5.6 Conversion Functions (4)

5.7 Logical Functions (2)

5.8 Crypto & Encoding Functions (13)

5.9 Statistics Functions (13)

5.10 Advanced Math & Calculus (20)

5.11 System / Get() Functions (4)

5.12 Array Functions (19)

5.13 Dynamic & Metadata Functions (3)

FileMaker-parity primitives for runtime introspection and dynamic evaluation. Unlike the rest of the library, these functions need access to the current row, the metadata catalogue, and the project database, so they're registered per evaluation rather than as static library entries — but they look and call exactly the same way from a formula.

6. Script Engine

Scripts automate repetitive tasks in Structa. A script is an ordered sequence of steps (actions) that can manipulate records, navigate between forms, display dialogs, perform calculations, and more. Navigate to Scripts in the sidebar to manage them.

6.1 The Script Editor

The Script Editor has three panels:

• Script List (left): All scripts in the project. Click the "+" button to create a new script.
• Step List (center): The ordered sequence of steps in the selected script. Drag steps to reorder. Click "+" to add a step.
• Step Inspector (right): Configure the selected step's parameters, conditions, and options.

Each step has an optional condition — a formula that is evaluated at runtime. If the condition evaluates to false, the step is skipped.

6.2 Variables

Scripts support local variables that persist for the duration of a script run. Variables are set with the setVariable step and referenced in formulas with the $ prefix:

// Set a variable
setVariable: name = "discountRate", value = 0.1

// Use in a later step's formula
setField: field = "totalPrice", value = subtotal * (1 - $discountRate)

Variable names are case-sensitive. Variables are scoped to the current script execution — they do not persist between runs or leak into other scripts (unless passed via performScript parameters).

6.3 Control Flow

Scripts support conditional execution and looping through step conditions and the following patterns:

• Step Conditions: Any step can have a condition formula. If it evaluates to false, the step is skipped.
• If/Else Branching: Use setVariable to store a condition result, then use that variable as conditions on subsequent steps.
• Looping: Use goToRecord with "Next" to iterate through a found set. Combine with step conditions to create loop-exit logic.
• Sub-Scripts: Use performScript to call another script, optionally passing a parameter.

6.4 Event Triggers

Scripts can be triggered automatically in response to events. Configure triggers in the script's properties:

6.5 Error Handling

If a script step fails (e.g., deleteRecord on a locked record, or a calculation error), Structa halts the script and displays an error dialog. To handle errors gracefully, use step conditions to check for potential problems before they occur, or use isvalid() in formulas to test values before operating on them.

7. Script Step Reference

Structa provides 50 built-in script steps organized by category (navigation, record manipulation, field operations, control flow, data, window/UI, script flow, file, reports, dashboards, record locks, and miscellaneous).

7.1 Field Steps

7.2 Record Steps

7.3 Navigation Steps

7.4 Search & Sort Steps

7.4a Control Flow Steps

7.4b Lock Steps

7.5 Variable Steps

7.6 Dialog & UI Steps

7.7 URL & File Steps

7.8 Export & Import Steps

7.9 Report Steps

7.10 Script Flow Steps

7.11 HTTP Integration Steps

Talk to external services from inside a script. Both steps run synchronously from the script's perspective — they block the calling script until the response arrives or the timeout elapses — and write the response into either a script variable (when the target starts with $) or a field on the current record.

url:    "https://api.weather.example.com/forecast?q=" & cityField
target: weatherSnapshot

8. Form Designer

The Form Designer lets you create custom visual layouts for viewing and editing records. Navigate to Forms in the sidebar. Forms are bound to a single table and display one record at a time (or multiple records in a list/portal).

8.1 Form Objects

The object palette has 25 distinct types. Every type renders identically in the native runtime and on the web (see 11.7 HTML Rendering).

8.1a Form Sections (Bands)

Forms are organised into bands, analogous to FileMaker Pro's Part Setup. Open Form › Section Editor to manage them. Each band can be enabled or disabled, given an explicit height, and optionally pinned so it stays static when the user scrolls.

Bands render in the same order both natively and in the published HTML. Each band's height is honoured exactly. Pinned bands stay fixed while the body scrolls.

8.2 Layout & Arrangement

Objects are positioned on a free-form canvas using absolute coordinates. The Form Designer provides alignment and distribution tools:

• Alignment: Align selected objects by their left, right, top, bottom, or center edges.
• Distribution: Space objects evenly horizontally or vertically.
• Snap to Grid: Toggle grid snapping for precise placement (grid size configurable in Settings).
• Tab Order: Set the order in which fields receive focus when the user presses Tab.

Select multiple objects with Shift+click or by dragging a selection rectangle. Use Cmd+G to group selected objects.

8.3 Data Binding

Each form object can be bound to a field from the form's table. Select an object, then in the Object Inspector, choose a Field from the dropdown. The object will display and edit the value of that field for the current record.

For labels, you can bind to a formula instead of a field. The formula is evaluated in the context of the current record.

8.4 Portals

A portal displays related records from a child table. To add a portal:

1. Drag a Portal object onto the canvas.
2. In the Object Inspector, select the relationship to follow.
3. Choose which fields from the related table to display as columns.
4. Optionally configure sorting and filtering for the portal rows.

Portals support inline editing if the related fields are editable. New related records can be created directly in the portal's last empty row.

8.5 Appearance & Behavior

Each object has appearance settings (font, font size, color, background, border, corner radius) and behavior settings (visible, enabled, tooltip). Appearance can be static values or formula-driven via conditional formatting rules.

Conditional Formatting Rules

Every form object has a Conditional Formatting Rules section in the Object Inspector. Each rule consists of:

• Formula — a boolean expression evaluated against the current record (e.g. balance < 0, DueDate < today(), status = "Overdue").
• Attribute overrides — background color, foreground (text) color, border color, and a bold toggle. Any attribute left blank uses the object's static value.
• Enabled toggle — flip a rule off without deleting it.

Rules are stacked top-to-bottom and applied as a layered overlay: each rule that evaluates to true overwrites the attributes set so far. The last matching rule wins, so place broader rules first and more-specific overrides below them. Disabled rules are skipped. Conditional formatting renders identically in the native runtime and in published HTML forms.

Example: a Due Date label that turns red bold when overdue.

Rule 1
  Formula:    DueDate < today()
  Background: #FFE5E5
  Text:       #B00020
  Bold:       on

8.6 Charts

The Chart object renders interactive data visualizations using the bundled chart.js library. It runs inside a fully transparent WKWebView, so the chart floats over your form background (solid color, image, or gradient) with no borders or scrollbars.

Supported chart types:

• Bar — classic vertical bars. Supports stacking when you have multiple Y fields.
• Line — smoothed connecting lines, one per Y field.
• Area — line chart with filled regions under each series.
• Pie / Doughnut — one slice per X-axis label using the first Y field as slice values.
• Scatter — point plot, useful when X is numeric.

Placing a chart:

1. Drag the Chart object from the object palette onto the canvas.
2. Open the Object Inspector. The Chart panel auto-selects the form's own table and offers sensible X-axis defaults.
3. Tick one or more Y Fields in the multi-select list. The table and X-field defaults are persisted automatically on the first tick — the chart renders immediately.
4. Adjust the chart type, title, aggregation (Sum, Average, Count, Min, Max, None), and per-series colors as needed.

Chart configuration fields:

Web-published charts: Published forms render identical charts client-side. The same chart.js library that runs in-app is served from /structa-static/chart.js, so your web users don't fetch it from a CDN and the chart looks exactly like it does on your Mac.

9. Data Browser

The Data Browser is your primary interface for viewing and editing data. Navigate to Browse Data in the sidebar (or press Cmd+Shift+R).

9.1 Grid View

The default view displays records as rows in a spreadsheet-like grid. Each column corresponds to a field. You can:

• Resize columns by dragging their header borders.
• Reorder columns by dragging column headers.
• Click a cell to edit its value inline.
• Double-click a row to open the Record Inspector (a detail panel showing all fields).
• Right-click a row for context menu actions (duplicate, delete, copy, etc.).

A form view is also available — click the Form View toggle in the toolbar to switch between grid and the default form for the current table.

9.2 Searching

Click the search field in the toolbar (or press Cmd+F) to search. Type a search term to perform a quick search across all text fields. For more precise searching, use search operators:

Full-text indexing. Quick search is backed by SQLite's FTS5 index. The first search on a new table transparently builds the index (in a single transaction) so subsequent searches return near-instantly, even on 50k+ row tables. The index is kept in sync as you add, edit, and delete records; searches with a leading wildcard (e.g. *smith) automatically fall back to LIKE scans, since FTS5 can't use an index for those.

9.3 Sorting & Filtering

Click a column header to sort by that field (click again to reverse). Hold Shift and click additional column headers to add multi-level sorts.

Use Records > Sort Records... to configure a custom sort order with multiple fields and ascending/descending per field.

9.4 Creating & Editing Records

• New Record: Click the "+" button in the toolbar or press Cmd+N.
• Duplicate Record: Select a record and press Cmd+D.
• Delete Record: Select a record and press Cmd+Delete. Confirm in the dialog.
• Commit: Press Return or click outside the row. Validation runs automatically.
• Revert: Press Escape before committing to discard changes.

Reports

The Reports workspace turns table data into printable, shareable documents. Open it from the sidebar's Reports entry.

• Build a report by selecting a source table, choosing columns, and adding optional group-by + summary rows.
• Filter with the same query language as the Data Browser (operators like =, >, .., !).
• Preview renders the report inline before printing.
• Print or export to PDF via the standard macOS print dialog.

Reports persist alongside the project, so a saved report definition reproduces the same output as the underlying data evolves.

Dashboards

Dashboards are at-a-glance pages combining KPIs, charts, recent-record lists, and notes. Each project can have any number of dashboards, selectable from the sidebar's Dashboards section.

Tile Types

• KPI tiles — a single number (count, sum, average, min, max) from any table, with optional row filter and click-through formula. The driving number is computed at SQL level, not in Swift.
• Charts — bar, line, area, pie, doughnut, scatter. Same chart engine as form-embedded charts.
• Recent Records — a compact list of the N most-recently-touched rows from a table. Useful for "latest leads", "open tickets", "last 10 jobs". Each row is clickable and opens the table's default form on that record.
• Note — rendered markdown / rich text. Useful as a section header, an instructions panel, or a "what to look at today" callout.

Refresh & Performance

Each dashboard has its own refresh timer (5 s – 5 min, or manual). Every refresh batches the SQL work: all KPI tiles backed by the same table are computed in one SQL round-trip, not one per tile. A 12-tile dashboard against the Jobs table runs one query, not twelve — so refresh latency is essentially independent of tile count. The result of each aggregate is cached briefly so a tile that the user nudges twice doesn't re-hit SQL.

Configuration

• Startup dashboard: a project can be configured to open directly on a dashboard. All five bundled templates ship with one to demonstrate the pattern.
• Embed inside a form: drop a Dashboard Embed object onto any form to show the dashboard inline (handy for "overview at the top of the home form").
• Background: dashboards take the same background colour / image controls as forms.
• Navigate from a script: the goToDashboard script step jumps to a named dashboard, in either the native runtime or via a 302 redirect when triggered from a published web button.

AI Assistant

The AI Assistant is a chat surface that can answer questions about the project's schema, suggest formula expressions, and draft scripts. It runs against your configured AI provider (configured in Settings > AI).

The assistant has read-only access to the project's metadata (table names, field names, relationship structure). It does not transmit row data unless you explicitly paste it into the conversation.

10. Import & Export

10.1 CSV Import & Export

Import: Use File > Import > CSV... to import a CSV file into a table. The import wizard lets you:

1. Select the target table (or create a new one from the CSV headers).
2. Map CSV columns to table fields.
3. Preview the first 100 rows before importing.
4. Choose how to handle duplicates (skip, update, or create new).

Column type inference samples the first 200 rows of the file (not the whole thing), so even multi-million-row CSVs preview quickly. The actual write pipeline uses a single prepared INSERT statement per batch of 500 rows, giving dramatically faster bulk loads compared to per-row inserts.

Export: Use File > Export > CSV... to export the current found set. Choose which fields to include, the delimiter (comma, tab, semicolon), and the text encoding (UTF-8 or ISO-8859-1). Export streams rows from SQLite straight to disk, so memory stays flat regardless of table size.

10.2 FileMaker Import

Structa can import FileMaker Pro data in two ways. When you pick FileMaker as the import source, Structa's import screen explains the trade-offs inline. Here is the fuller picture:

10.2.1 Binary .fmp12 import

Structa reads the .fmp12 file format directly — no FileMaker installation required. The binary importer recovers:

• Tables — all tables in the file, by their real names (not placeholders).
• Fields — name and type code for each column, mapped to the closest Structa type (text, number, date, time, timestamp, container).
• Records — cell values for every record, with XOR/SCSU decoding and UTF-8/Latin-1 fallback.
• Relationships — joined field pairs between tables. Cardinality is not stored in the binary, so every relationship imports as one-to-many; adjust in the Relationship Designer after import.

What the binary importer cannot recover, because FileMaker does not encode it in a reversible way:

• Layouts (screens / forms)
• Scripts and script triggers
• Value lists
• Access privileges / privilege sets
• Calculated fields' original formulas (the stored values are imported, but the formula text is not)

10.2.2 DDR XML import (recommended for a full migration)

For a complete migration, use FileMaker's Database Design Report export:

1. In FileMaker Pro, open your file and choose Tools → Database Design Report…
2. Select XML as the output format.
3. Import the generated .xml file in Structa via File > Import > FileMaker…

The DDR XML path imports tables, fields, records, the full relationship graph (with cardinality), scripts, value lists, and layout metadata.

10.3 Advanced Import/Export

Structa also supports advanced import/export workflows:

• Scheduled CSV export to a specified directory.
• Batch import of multiple CSV files with automatic table creation.
• Export to JSON for integration with external systems.
• Field content export for extracting images and documents from the assets directory.

11. Web Publishing

Structa ships with an embedded HTTP daemon. Flip a single switch and your project is online — every form you've designed becomes a working web page, every script-bound button becomes a working web button, and every list view becomes a sortable, searchable HTML grid. Browser clients require an active Web Sharing subscription (Apple in-app purchase — see Pricing).

11.1 Per-Project Sharing Toggles

Each project carries its own sharing state. Open Sharing › Settings to flip:

• Web sharing enabled — serve this project's forms to browsers on the network. Requires Web Sharing IAP.
• Native sharing enabled — serve this project to other Macs running Structa. Requires a Native Hosting CAL pack.
• Listed in publishing root — when on, the project appears as a tile on the daemon's home page (/); when off, the project is still reachable at its slug but doesn't show up on the lobby.
• Auto-save — when on (the default), field edits in a web form commit on blur and on tab close (via navigator.sendBeacon); when off, the user must explicitly press Save.
• Native Guest / Web Guest — per-surface toggles next to each share URL. When on, that surface lets visitors in without an account; when off (default with accounts defined), Structa challenges for credentials.
• Guest can: Read / Create / Edit / Delete — four global CRUD flags that gate what an anonymous visitor may do. Visible only when at least one Guest toggle is on. Defaults: read on, mutations off.

State persists inside the .structa package, so the next time you (or another machine) opens the project, the daemon comes up with the same toggles you left it with.

The Sharing dashboard shows the real LAN IP for each share URL (e.g. http://192.168.1.75:8080/<slug> rather than 0.0.0.0:8080) so you can copy a URL that works directly from another device on your network. The Sharing toolbar banner uses the same address.

11.2 Auto-Publish Profiles

Every form in your project gets a publish profile automatically the moment it's created — whether from the Form Designer, from a template, or from the AI Assistant. There is no per-form "Publish…" step. The profile's URL slug is derived from the form name; the route handles list, detail, create, update, and delete out of the box.

If you open a project that pre-dates auto-profiles (or one imported from a template), Structa runs a one-time backfill on attach so every form ends up with a working route.

11.3 Routes

Routes are mounted under a per-project slug. For a project slugged jobs and a form slugged active-jobs:

11.4 Server-Side Button Scripts

Native form buttons bound to a script work the same way on the web. The HTML renderer emits a real <button type="submit"> whose form posts to /_action/:scriptID. The daemon runs the script using the current record as context. If the script returns a NavigationRequest, the daemon maps it through the publish-profile registry and 302-redirects the browser:

• Go to Form → the target form's profile URL.
• Go to Table → that table's first published list form.
• Go to Record → /<project>/<form>/<rowid>.
• Go to Dashboard → the dashboard route under the same project.

Field edits flow through the same /_action/ mechanism when auto-save is on; otherwise the user explicit-Saves to fire the update.

11.5 Authentication

Structa supports three authentication modes per publish profile:

Users and roles are managed in the Security workspace (left sidebar › Configuration). See Section 14 — Security & Accounts for the full account / privilege-set model.

Per-project guest controls. The per-project Web Guest toggle (Sharing dashboard) overrides the profile's requiresAuth setting at the project level. When Guest is on, the four global CRUD flags (Read / Create / Edit / Delete) gate which verbs unauthenticated visitors may invoke. Mutating handlers (POST / PUT / DELETE / form submit) check the matching flag before running and return 403 when denied. Read endpoints follow the Read flag the same way.

11.6 Web Home Page Styles

The daemon's lobby (/) renders in one of five distinct visual styles. Pick one in Sharing › Settings › Home Page:

Upload a company logo at the top of the same panel. The logo appears on the lobby page and on the per-project shell. Logos are stored inside the daemon's appearance bundle, not the .structa project, so a single Mac hosting multiple projects only has to set them once.

11.7 HTML Rendering

The HTML renderer mirrors the native form renderer object-for-object:

• 25 form-object types — each has a real HTML counterpart, not a generic fallback.
• SF Symbols — rasterised server-side via AppKit, encoded as PNG data URLs, tinted to match the native appearance. Browsers see the actual glyph.
• Embedded images — container-field images stream from /_assets/…; image objects with bundled appearance data resolve to data URLs.
• Conditional formatting — evaluated server-side per record; CSS-inline styles applied.
• Form-level backgrounds — colour and image both honoured (image streams from the project's appearance store).
• Charts — chart.js renders with the same data the native form is showing, in a transparent wrapper.
• Section bands — master-header, header, body, navigation, footer, master-footer all preserved.

11.8 Webhooks

Each publish profile carries a list of outbound webhooks. Whenever a record is inserted, updated, or deleted — from the native app, the data browser, a script, or a web client — Structa POSTs a JSON envelope to every matching webhook URL.

Each webhook entry has:

• URL — the HTTPS endpoint to call (HTTP also accepted for localhost development).
• Events — any combination of insert, update, delete.
• Table ID — optional. When set, the webhook only fires for that table; when nil, it fires for every table (firehose).
• Headers — optional key/value pairs sent on every request (e.g. Authorization: Bearer … for Slack, Zapier, or a custom auth gateway).
• Enabled — flip a webhook off without deleting it.

The JSON envelope:

{
  "event": "insert" | "update" | "delete",
  "table": "<sanitizedTableName>",
  "tableID": "<table-uuid>",
  "rowid": "<rowid>",
  "values": { "<column>": <value>, … }
}

Delivery is fire-and-forget on a serial utility queue with a five-second timeout and one retry on transport failure or 5xx response. Misconfigured webhooks log an error and never block the record write. Schemes other than http / https are rejected without firing a request.

11.9 Responsive — phones & tablets

Published forms adapt automatically to the viewing device, in three layered passes:

• Page chrome — the surrounding header, list tables, buttons, and inputs reflow at two breakpoints (≤768 px tablet, ≤600 px phone) for proper touch targets (44 px minimum), 16 px font sizes so iOS doesn't zoom on focus, and a "card stack" layout where each list row becomes a full-width tile with field-name labels on the left.
• CSS auto-reflow — when a designed form-canvas is loaded on a narrow viewport but the device wasn't recognised as a phone (e.g. a desktop browser resized down), the abs-positioned canvas is overridden in CSS to flow vertically. Decorative shapes (lines, rectangles, spacers) are hidden so they don't clutter the stack.
• Server-side device detection — phones get a completely separate stacked render path. Each field is emitted as a clean <label>Field Name</label><input/> pair regardless of where the designer placed the corresponding controls on the desktop canvas. This guarantees labels and inputs stay paired even when the desktop layout put them in widely-separated rows. Action buttons follow the field stack so scripts can still be invoked.

Detection precedence:

1. ?layout=phone | tablet | desktop in the URL — explicit override. Handy for QA on a desktop browser.
2. Sec-CH-UA-Mobile: ?1 client hint — modern browsers.
3. User-Agent heuristic (matches "iPhone", "Android", "Mobi", "Windows Phone"; iPad is detected separately as a tablet).
4. Default: desktop.

12. Host Mode

Host Mode turns your Mac into a database server, allowing other Structa users on your local network to connect to your project from their own Macs. Additional native client seats require a Native CAL subscription (1, 3, 5, 10, 15, or 20 seats — see Pricing).

12.1 Setup

1. Open your project and switch to Host mode (View > Mode > Host, or the toolbar toggle).
2. Select a publish profile (or create one if none exists).
3. Click Start Server.
4. Structa displays the local URL (e.g., http://192.168.1.100:8080) that other devices can use to connect.

12.2 The Dashboard

The Host Mode dashboard shows real-time information:

• Server status (running/stopped), port, and uptime.
• Connected clients with IP addresses and last activity timestamps.
• Request log showing recent HTTP requests (method, path, status code, response time).
• Performance metrics (requests per minute, average response time, active sessions).

12.3 LAN Access

By default, the server is accessible to any device on the same local network. Ensure your Mac's firewall allows incoming connections on the configured port. For access from outside your network, configure port forwarding on your router.

12.4 HTTPS

Structa supports HTTPS with TLS certificates for encrypted connections. To enable HTTPS:

1. In the publish profile, toggle HTTPS on.
2. Provide a certificate file (.pem) and private key file (.pem), or let Structa generate a self-signed certificate for development/testing.
3. Restart the server. The URL will change to https://.

Self-signed certificates will trigger browser warnings. For production use, obtain a certificate from a certificate authority (e.g., Let's Encrypt).

13. Multi-User Collaboration

When Host Mode is active, multiple users — on Macs running Structa or in any modern browser — can work in the same project at once. Structa coordinates them in two tiers: live updates (Tier 1) and presence + advisory locks (Tier 2).

13.1 Tier 1 — Live Record Refresh

Every connected client opens a WebSocket to the daemon. The daemon broadcasts a change event whenever any record is inserted, updated, or deleted — whether the write came from the native app, the data browser, a script, a web client, or a JSON API call. Every other client receives the broadcast and re-fetches the affected row, so the form you're looking at always reflects what's actually in the database.

This is on by default whenever the daemon is running; no per-form opt-in. Clients fall back to a slow-poll if their WebSocket drops.

13.2 Tier 2 — Presence & Advisory Locks

The same WebSocket carries presence and lock events:

• Presence — when a client opens a form, the daemon broadcasts a {"presence":"joined", …} message; on close, {"presence":"left", …}. Every other client sees who else is on the same form / record and renders a presence chip.
• Advisory locks — when a user starts editing, the client POSTs /_lock. The daemon either grants the lock (broadcasting {"lock":"acquired", …}) or refuses with the holder's identity. Locks are advisory: the daemon won't reject a write to a locked row, but other clients can show a padlock glyph and disable their edit affordances.
• sendBeacon release — when a browser tab closes (or the user navigates away), the page calls navigator.sendBeacon to POST /_lock/release. sendBeacon is the only browser API that reliably fires during unload, so this prevents zombie locks from closed tabs.
• TTL pruning — even without an explicit release, locks expire on a configurable timeout (default 120 seconds of inactivity). The lock service auto-prunes every minute.

13.3 Native Lock & Skip-Locked

The native runtime exposes locks to scripting:

• Lock Record / Unlock Record script steps for explicit coordination.
• Skip-locked queries — pass ?skip_locked=1 on a JSON API GET /api/v1/<table> and the daemon returns only rows that no other session holds. Pair this with Lock Record in a Loop to build a job queue where each worker automatically claims a disjoint batch.
• Lock indicator banner on detail forms; padlock glyph on list-view rows held by another session.

13.4 Conflict Resolution

If two users manage to submit changes to the same record (e.g., due to network latency or a manually overridden advisory lock), Structa uses an optimistic concurrency model:

1. Each record has a version counter that increments on every save.
2. When a user submits changes, Structa checks that the record version matches what the user loaded.
3. If the version has changed, the save is rejected with a conflict error, and the user is shown both the current server values and their submitted values.
4. The user can choose to overwrite, merge, or discard their changes.

13.5 Audit Logging

Structa logs every record creation, update, and deletion with the user, timestamp, table, record ID, and changed fields. View the audit log from Settings › Audit Log or query it programmatically via the JSON API. The log persists inside the .structa package, so it survives daemon restarts and Mac reboots.

13.6 Open Remote Project

Use File > Open Remote Project… (⇧⌘O) to connect this Mac to another Mac running Structa in Host Mode. Enter the host’s URL (e.g. structa+mu://192.168.1.75:8080/my-project), your username, and your password. The remote session establishes against /auth/login, claims a native CAL seat from the host’s pool, and parks the session on the workspace so all subsequent reads and writes flow over the multiuser protocol.

When a remote write collides with another client’s edit (HTTP 409 + OCC token mismatch), the conflict resolver appears automatically: yours vs. theirs vs. base for each diverged field, with per-field Keep Yours / Accept Theirs / Use Base radios. The resolved values are re-PUT against the server’s newer OCC token so the merged record commits cleanly.

14. Security & Accounts

Structa ships with a built-in security model: named user accounts with hashed passwords, three baked-in privilege sets, a native sign-in gate on project open, and per-project guest controls with explicit CRUD permissions. Every layer is optional — an empty user table means the project opens straight to the workspace and the embedded server serves anonymous traffic.

14.1 The Security Workspace

Click Security in the left sidebar (under Configuration) to open the workspace. It has two tabs:

• Users — add, edit, deactivate, and delete accounts. Each user has a username, a PBKDF2-SHA256 hashed password (100,000 iterations, 16-byte salt), an optional API token for headless integrations, and a privilege set assignment.
• Privilege Sets — manage role definitions. Three sets are seeded automatically the first time you open a project: Admin (full read/write/create/delete + API), Read-Write (CRUD without admin), and Read-Only (browse only). You can add your own custom sets alongside.

14.2 Privilege Sets

A privilege set bundles four kinds of permission:

• Per-table CRUD — read / create / edit / delete flags per table, stored as JSON so new tables default to allow.
• Visible fields — per-table list of field UUIDs the user is allowed to see; nil = all.
• Editable fields — per-table list of field UUIDs the user can edit; nil = all visible fields are also editable.
• Row filter — an optional formula like Owner = Get(AccountName) that scopes which rows the user sees on any table.
• Caps — canUseAPI and canUseFormUI gate the JSON REST API and the form runtime respectively.

The system sets are marked isSystem: true and reseed if you delete them. Your custom sets persist normally.

14.3 Native Sign-In Gate

When you open a project that has at least one active user account and the project’s native guest toggle is off, Structa presents a sign-in sheet before the workspace renders. Enter your username and password; the credentials are verified against the user table’s PBKDF2 hash in constant time. On success, the workspace appears and AppState.currentUser populates so scripts and ACL checks see the acting user. Cancel closes the project without unlocking it.

Projects with no accounts (or with the native guest toggle on) skip the gate entirely and open straight to the workspace.

14.4 Guest Access & CRUD Permissions

Each project carries four independent guest controls, visible in Sharing for any hosted project:

• Native Guest — when on, native clients open the project without an account.
• Web Guest — when on, browser visitors skip the sign-in screen.
• Guest can: Read / Create / Edit / Delete — four checkboxes that gate what an anonymous visitor may do. They appear only when at least one Guest toggle is on. Defaults: read on, mutations off.

The two surface toggles are independent — you can run a project guest-readable on the web while requiring sign-in on native, or vice-versa. The four CRUD flags apply globally across every table; per-table refinement is available through named accounts + privilege sets.

Enforcement: every published-form handler declares its verb (create / edit / delete / default read); when a request resolves to guest, the matching flag is consulted before the handler runs. Disallowed verbs return HTTP 403 with a human-readable message.

14.5 Encryption at Rest

New projects encrypt at rest with AES-GCM. The symmetric key is generated at project creation and stored in your macOS Keychain; the on-disk archive is compressed with Apple’s LZFSE for a 2–4× smaller footprint. Decryption happens once at open; the plaintext lives on disk only during the session and re-encrypts on close.

• Auto-lock — configurable idle timeout and Mac sleep both trigger re-encryption and close.
• Crash recovery — if a plaintext file is found alongside the .enc archive, Structa keeps the newer copy and flags the project for re-encryption on next close.
• Recovery Key — File > Encryption > Export Recovery Key… wraps the project’s symmetric key with a PBKDF2-SHA256 (200k iterations) derived KEK from a user passphrase. Import the same key on another Mac to recover access without the original Keychain.

15. Templates

15.1 Bundled Templates

Structa ships with 17 ready-to-use templates accessible from the onboarding wizard or File > Apply Template…. Every template is JSON-defined (no compiled Swift), includes a hero-banded form layout that renders identically on the web and on mobile, ships with publish profiles enabled, and includes sample data.

Templates are organized under Resources/Templates/structa_templates/ as JSON files and loaded by JSONTemplateLoader. The Apply Template sheet shows previews, sample data toggles, and the per-template hero-band accent color.

15.2 Custom Templates

To create your own template from an existing project:

1. Open the project you want to use as a template.
2. Go to File > Export Template...
3. Choose whether to include sample data or export schema only.
4. Enter a template name, description, and icon.
5. Save. The template is exported to the project's templates/ directory.

To import a custom template, use File > Import Template... and select the template file. It will appear in the onboarding wizard alongside the bundled templates.

16. Pricing

Structa is a free download with the full database builder, scripting, calculation engine, form designer, and all bundled templates included. Two optional in-app subscriptions add multi-user access on top of that base.

16.1 What's Included Free

16.2 In-App Subscriptions

Two independent subscription groups gate multi-user publishing:

• Native CALs — client-access licences for other Structa users connecting to your project from their own Macs over the LAN. Six pack sizes (1, 3, 5, 10, 15, 20 seats). Pick one pack at a time; switching pack sizes is an in-place upgrade/downgrade handled by StoreKit with automatic proration.
• Web Unlimited — unlimited browser-based access on the host's network. Independent of the Native CAL subscription; you can subscribe to either, both, or neither.

17. Keyboard Shortcuts

File & Project

Mode Switching

Design Mode Sub-Routes

Other Navigation

Data Browser & Runtime Form

Documentation Window

Form Designer

Script Editor

18. Troubleshooting

18.1 Common Issues

18.2 Crash Reports

If Structa crashes, macOS generates a crash report. To find and submit it:

1. Open Console.app (in Applications > Utilities).
2. In the sidebar, navigate to Crash Reports.
3. Look for entries named "Structa" with the date/time of the crash.
4. Click the report to view it, then use File > Save to export.

You can also find crash logs at ~/Library/Logs/DiagnosticReports/. When contacting support, include the crash report along with:

• The Structa version (from Structa > About Structa).
• Your macOS version.
• A description of what you were doing when the crash occurred.
• The project file (if possible), or a description of its schema.

18.3 Contact the Developer

For suggestions, bug reports, or complaints, choose Help > Contact the Developer… from the menu bar. A panel opens with:

• Category picker — Suggestion, Bug Report, Complaint, or Other. The chosen category is prefixed onto the email subject line for easy triage.
• Subject — optional one-line summary.
• Message — your note. Structa automatically appends the app version and macOS version when it sends the email.
• Image attachments — click Add Image… to attach screenshots or photos. Up to 10 images, each 5 MB maximum. Click the × on a thumbnail to remove one.

Press Send. Structa opens your default email client with the message and attachments already in place. If no email client is configured, Structa writes the message and attachments to a folder on your Desktop and opens a pre-filled email with instructions — so the feedback path always works.

Structa v2.2 — Documentation © 2026 FI Forensic Intelligence, Ltd. All rights reserved.