App Development

Create a new app

oi init my-app

This creates a new app directory with the standard structure:

my-app/
├── oikapi.json          # App metadata
├── tables/              # Table definitions
├── roles/               # Role definitions
└── permissions/         # Permission grants

Apps can also include optional rules/ (business rules) and demo-data/ directories, which the platform recognizes when present. Use a template to scaffold a richer starting point:

oi init my-app --template crm     # CRM starter (customers, contacts, deals)
oi init my-app --template tasks   # Task management starter

Development workflow

Watch mode

oi dev my-app

Watches your app directory and auto-syncs changes to the connected server. Edit a table definition, save, and see it reflected immediately.

Manual sync

# Push local changes to server
oi push my-app

# Pull server state to local
oi pull my-app

Defining tables

Create JSON files in the tables/ directory:

tables/projects.json

{
  "name": "projects",
  "display_name": "Projects",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true
    },
    {
      "name": "budget",
      "type": "decimal",
      "config": {"precision": 10, "scale": 2}
    },
    {
      "name": "status",
      "type": "enum",
      "config": {"options": ["draft", "active", "completed"]}
    }
  ]
}

Building packages

# Validate structure
oi validate my-app

# Build distributable package
oi build my-app

This creates a .oikapp file that can be installed on any oikapi instance or published to the marketplace.

Auto-prefixing

Table definition files use short names (for example, projects). The backend applies an application-scoped prefix automatically when the package is installed — for instance, a projects table in an app with prefix pm becomes the PostgreSQL table pm_projects. No renaming happens during oi build.

When writing references inside your app’s definitions, use the short name for same-app resources and dot notation for cross-app resources:

• Same-app reference: "target_table": "tasks" (resolved to the app-prefixed table at install time)
• Cross-app reference: "target_table": "system.users" (the system. prefix is preserved as-is)