Organizing Your Code

oikapi apps are directories with a standard structure. You develop locally, test against a live instance, and optionally publish to the marketplace.

App directory structure

Every app follows the same layout:

my-app/
├── oikapi.json              # App metadata (name, version, dependencies)
├── tables/                  # Table definitions (JSON)
│   └── *.json
├── roles/                   # Role definitions
│   └── *.json
├── permissions/             # Permission grants
│   └── default.json
├── rules/                   # Business rules (optional)
│   └── *.json
├── workflows/               # Workflow definitions (optional)
│   └── *.json
└── demo-data/               # Sample data for demos (optional)
    └── *.json

Tip

Run oi init my-app to scaffold this structure automatically. Pass --template (-t) to start from a richer starting point — for example oi init my-app -t crm. Available templates: basic (default), multi-app, crm, and tasks.

Note

oi init scaffolds tables/, roles/, and permissions/. The other directories above (rules/, workflows/, demo-data/, plus view and form directories such as presets/ and form_views/) are optional — add them as your app grows.

Single app per repo

The simplest approach – one git repo contains one app:

my-app/                      # Root of the git repo
├── oikapi.json
├── tables/
├── roles/
├── permissions/
└── ...

oi init my-app
cd my-app
git init

Best for: Independent apps, small teams, open-source contributions, apps you want to version and release separately.

Multiple apps in one repo

For related apps, use a monorepo with each app in its own subdirectory:

my-apps/                     # Root of the git repo
├── invoicing/
│   ├── oikapi.json
│   ├── tables/
│   └── ...
├── reporting/
│   ├── oikapi.json
│   ├── tables/
│   └── ...
└── README.md

The CLI commands work the same – just point at the subdirectory:

oi dev invoicing
oi push reporting
oi build invoicing

Best for: Related apps that share dependencies, larger teams, internal app suites where you want a unified workflow.

Note

oikapi’s own first-party suites (CRM, Sales, ITSM, CMDB, Inventory, and more) are developed as a single monorepo of apps using this pattern. See Core Apps for the catalog.

Development workflow

1. Create your app with oi init or manually
2. Define tables as JSON files in tables/
3. Test live with oi dev my-app – watches for changes and auto-syncs to your connected instance
4. Iterate – edit table definitions, add roles, write business rules
5. Build with oi build my-app to create a distributable .oikapp package
6. Publish to the marketplace if you want to distribute it

# Full workflow
oi init my-app
cd my-app

# ... edit tables, roles, rules ...

oi dev my-app              # Live sync while developing
oi validate my-app         # Check for errors
oi build my-app            # Package as my-app-1.0.0.oikapp

See App Development for the full CLI reference and Package Format for details on the .oikapp archive structure.

Installing your app

Once built, install your package on any oikapi instance:

# From a local .oikapp file
oi app install ./my-app-1.0.0.oikapp

# Directly from a source directory (builds, then installs)
oi app install ./my-app

Demo data bundled with the package is managed separately after install — use oi app demo to list or remove it.

Auto-prefixing

When an app is installed, all resource names are automatically prefixed with the app name to prevent conflicts between apps on the same instance:

Source file	Installed as
tables/projects.json	myapp_projects
roles/manager.json	myapp_manager
Reference to "tasks"	myapp_tasks
Reference to "system.users"	system.users (preserved)

You write clean, unprefixed names in your source files. The builder handles the rest.