Projects

Overview

A project is the fundamental unit of organization in Oblax. Every application you build lives inside a project. A project owns a deterministic local /app directory layout, an oblax.json manifest, and a set of module definitions that describe your data model. On the platform side, a project owns a remote workspace that stores your deployed resources, access rules, and runtime configuration.

Projects sit inside organizations. When you create an account, the platform provisions a default organization and assigns you the ORG_OWNER role. You can then create multiple projects within that organization, each with its own modules, ACL rules, and environment configuration.

Project Structure

Every project root contains two core components:

The oblax.json Manifest

The manifest is your project’s single source of truth. It declares the project name, description, and version.

{
  "name": "my-first-project",
  "description": "My first Oblax project",
  "version": "0.1.0"
}

The /app Filesystem

All application data plane definitions live inside your local /app directory. Each module maps to a subdirectory:

/app
  /forms        → ID-based CRUD collections (<form_id>.json)
  /bookmarks    → ID-based CRUD collections (<bookmark_id>.json)
  /flux         → Key-based semantic singletons (<event_name>.json)
  /templates    → Key-based semantic singletons (<template_name>.json)
  /acl          → HTTP-key-based route maps (<method_route>.json)

Your local /app directory is the single source of truth. Changes you make locally sync to the platform when you run obx app <module> push, and updates made online mirror back when you run obx app <module> pull.

Creating a Project

Oblax supports two creation paths: a quick CLI command for developers who want to start immediately, and a guided web flow for teams that need more configuration up front.

Simple Create (CLI)

The CLI path provisions both your remote platform workspace and your local filesystem scaffold in one command.

obx project create my-first-project

Output:

| SUCCESS: Project created
| Project "my-first-project" created successfully.
|
| Details:
| - Directory: ./my-first-project
| - Config: oblax.json
| - Data Plane: ./app
|
| → Run `cd my-first-project` to enter your workspace

Guided Create (Web Interface)

The web interface walks you through project creation with a form-based flow. You choose a project name, select modules, and configure environments before the platform provisions your workspace.

Project Lifecycle

Projects and Organizations

A project always belongs to exactly one organization. The creator of a project is automatically assigned the PROJ_ADMIN role. Organization owners and admins can invite other users to collaborate on a project, each receiving a project-level role that determines their access.

Where to next