Samson Advisory Samson AdvisoryGrowth Strategists & Implementers
Documentation

Screen Builder

A low-code authoring environment for building, previewing, and deploying admin screens on top of your data.

What It Is

Screen Builder lets you scaffold a fully working admin screen — controller, model, views, routes, and database migration — from a single name and data-source choice. From there, you edit the generated code in a familiar three-panel IDE, preview the screen against a sandboxed copy of your data, then deploy it to production through a guided wizard that handles menu placement, role-based permissions, and schema migration for you.

You'll find it at /admin/screen-builder after logging in as an admin.

What You Can Do

Scaffold a new screen

  • Click New Screen, enter a name and a screen key.
  • Choose your data source: scaffold a new table (Screen Builder writes the migration for you) or build on top of an existing data_db table (it auto-imports sample rows).
  • Screen Builder generates a controller, an Eloquent model, index/create/edit Blade views, routes, and a migration — following Awali's Laravel conventions out of the box.

Edit in the integrated IDE

  • Three-panel layout: file tree on the left, Monaco editor in the center, terminal at the bottom.
  • Syntax highlighting for PHP, Blade, SQL, HTML, and JSON.
  • A bundled Context.md file documents the Laravel patterns the scaffold uses and the database setup it assumes.
  • Browse your dbt project read-only from the same tree so you can cross-reference transformation logic without switching tools.
  • Full dark-mode support in both the editor and the generated views.

Preview before you ship

  • Click Preview. Screen Builder runs your migrations into an isolated SQLite sandbox and serves the screen there.
  • Create, edit, and delete test records to see how the screen behaves end-to-end.
  • Use Import Data to seed the sandbox with real production rows for realistic testing.
  • Use Reset Database to clear the sandbox and start over.

Deploy through a guided wizard

Click Deploy to open a five-step wizard:

  1. Overview — confirm the screen metadata and the migrations that will run.
  2. Database — confirm the target table and any schema changes. Re-deployments skip unchanged migrations and apply only what's new.
  3. Menu — optionally add the screen to the admin menu with a custom label and icon.
  4. Permissions — assign view / edit / delete permissions per role.
  5. Confirm — the wizard copies files into the CustomScreens module, runs migrations against data_db, updates the menu, sets permissions, and clears caches. The screen is live immediately.

Iterate on a deployed screen

  • Find the screen in the workspace list and click Load for Edit — the deployed files are copied back into your workspace.
  • Edit, preview, and deploy again. The deploy wizard handles incremental schema changes gracefully.

Archive screens

  • Move a screen out of your active list with Archive. The files are preserved and can be restored at any time.

Common Workflows

Build a new Invoices screen

  1. Screen Builder → New Screen → name it “Invoices”, key invoices.
  2. Choose New table. Screen Builder generates the controller, model, views, routes, and migration.
  3. Edit the migration to add the columns you need (amount, customer_id, status, due_date).
  4. Click Preview. The sandbox spins up; you create a few test invoices to verify the UI.
  5. Click Deploy. Walk through the wizard: add the screen to the “Finance” menu group, grant view to finance-viewer, edit/delete to finance-admin.
  6. Confirm. The screen appears in the admin menu for users in those roles.

Add a CRUD UI on top of an existing dbt table

  1. Build your transformation in DBT Workshop and run it; the table lands in data_db.
  2. In Screen Builder, New Screen → Use existing data_db table → pick your table from the dropdown.
  3. Screen Builder imports sample rows and scaffolds a screen matching the column types.
  4. Edit views and controller as needed; preview; deploy.

The Two-Database Model

Screen Builder respects Awali's standard split between authentication state and business data:

auth_db
Holds users, roles, menus, and permissions. Screen Builder never writes business data here.
data_db
Holds all business data. Generated screens read and write here. Migrations run here.

Glossary

Workspace
Your editable scratch area — the files for screens you're building or revising. Nothing here is live.
Deployed screen
A screen that has been shipped through the wizard. It lives in the CustomScreens module and is visible in production according to its permission grants.
Scaffold
The starter set of files Screen Builder generates when you create a new screen.
Preview sandbox
An isolated SQLite database that serves your in-progress screen. Resetting it has no effect on production.
Re-deploy
Shipping a revised version of an already-deployed screen. The wizard applies only the new migrations.
CustomScreens module
The runtime home for all deployed Screen Builder screens.

Access & Security

  • Admin role required, plus an active MFA session.
  • Previews run in a sandboxed SQLite database — they never touch production.
  • Deployment is a deliberate, multi-step wizard so schema changes and permission grants are always reviewed before going live.
  • Per-screen permissions are role- and user-aware: can_view, can_edit, can_delete are assigned individually.

← Back to overview

↑