Create your first application

Overview

An Oblax application consists of modules (forms, bookmarks, flux scripts, templates, ACL rules) that define CRUD operations, filesystem storage under /app, CLI management, SDK integration, and auto-generated REST endpoints.

Application development follows a modular approach where you initialize each module, push resources to the platform, and manage them through deterministic CLI commands.

Installation

Application development requires the Oblax CLI installed and a project initialized.

Verify Prerequisites

obx version
obx login

Project Structure

Ensure you have a project with the standard /app structure:

my-project/
├── oblax.json
└── app/
    ├── forms/
    ├── bookmarks/
    ├── flux/
    ├── templates/
    └── acl/

Configuration

Step 1: Scaffold Your First Module — Forms

The most common starting point is the Forms module — it lets you collect structured data from users.

Initialize Forms

obx app forms init

What this does:

1. Creates ./app/forms/init.json with an empty form schema
2. The file contains the structure with empty fields, ready for you to populate
3. Success message is displayed

Output:

| SUCCESS: Role file initialized
| Edit the initialized role file ./app/forms/init.json

Edit the Initialized File

code ./app/forms/init.json

Add your form fields. Example minimal form:

{
  "name": "contact_form",
  "fields": [{ "name": "email", "type": "string", "required": true }]
}

Push Forms to the Platform

obx app forms push init

This creates the form on the platform and assigns it a platform-generated ID.

Output:

| SUCCESS: Role created
| The role 'contact_form' has been successfully created on the platform.
|
| Local copy of the record is saved in ./app/forms/f2837hfd17q3phc3.json

From now on, refer to this record by its ID f2837hfd17q3phc3 — not by the name init.

Step 2: Scaffold Your Second Module — Bookmarks

Bookmarks are another ID-based module, useful for saving user references.

Initialize Bookmarks

obx app bookmarks init

Push Bookmarks to Platform

obx app bookmarks push

Step 3: Add a Flux Script (Key-Based Module)

Flux scripts are key-based semantic singletons. They trigger workflows based on platform events.

Initialize a Flux Script

obx app flux:scripts init user.created

Key validation: The CLI validates whether user.created is a valid key. If not, an error is shown:

| ERROR: Flux handler initialization failed
| The key "user.created" is not a valid flux handler script key.

If valid, a local file ./app/flux-scripts/flux_on_user_created.js is created with a stub function.

Output:

| SUCCESS: Flux handler initialized
| A new flux handler script with a stub function has been initialized.
|
| Edit the initialized flux handler file
| - ./app/flux-scripts/flux_on_user_created.js

Push the Flux Script

obx app flux:scripts push user.created

This pushes the script to the platform.

Step 4: Add a Template (Key-Based Module)

Templates are key-based and user-identified by name or format.

Initialize a Template

obx app templates init 'My First Template' --format html

What this creates:

1. ./app/templates/a_very_new_template_html.html — the template file
2. ./app/templates/a_very_new_template_html.json — meta file with resource type

Output:

| SUCCESS: Template initialized
| A new template file with an accompanying meta file have been initialized.
|
| Edit the initialized template files
| - ./app/templates/a_very_new_template_html.html
| - ./app/templates/a_very_new_template_html.json

Push the Template

obx app templates push a_very_new_template_html

Step 5: Configure ACL (HTTP-Key-Based Module)

ACL modules define API permissions using HTTP method + route patterns.

Initialize ACL Rules

obx app acl init

Push ACL Rules

obx app acl push post@/api/v1/users

This maps to the filesystem file post_api_v1_users.json.

Usage

Running Your First App Locally

Oblax includes a local development server. From your project root:

obx run

What this starts:

• Local Oblax development server ($PORT defaults to 8080)
• Your initialized modules (forms, bookmarks, etc.)
• Live reload as you edit /app files
• API endpoints at http://localhost:8080/api/v1/...

Try it:

1. Ensure you have at least one module initialized (e.g., forms)
2. Run obx run
3. Visit http://localhost:8080 in your browser
4. You should see the Oblax welcome page or your module’s entry point

Application Checklist

Next Steps

Your application is scaffolded and running. Now:

1. Make your first API call — authenticate and interact with your forms data
2. Run your first CLI command — practice CRUD workflows
3. Make your first SDK call — integrate from a web or mobile front-end