Building Apps

oikapi apps are self-contained bundles of tables, roles, permissions, business rules, and optional web interfaces that can be installed on any oikapi instance. You author an app as a directory of JSON (and optional script) files, test it against a live instance, and build it into a distributable .oikapp package.

Getting started

# Scaffold a new app
oi init my-app
cd my-app

oi init accepts a --template (-t) flag to start from a richer starting point — basic (default), multi-app, crm, or tasks.

App metadata

Every app has an oikapi.json manifest at its root. In source form it’s a flat document:

{
  "format": 1,
  "provider": "oikapi",
  "name": "my-app",
  "display_name": "My Application",
  "version": "1.0.0",
  "description": "What this app does",
  "category": "business",
  "icon": "AppIcon",
  "color": "amber",
  "default_route": "table:projects",
  "author": "Your Name",
  "license": "MIT",
  "tags": ["keyword1", "keyword2"],
  "dependencies": [],
  "cross_app_access": []
}

icon must be a phosphor-icons name (e.g. UsersThreeIcon). When you build the app, this manifest is compiled into the package’s own manifest — see Package Format for the on-disk structure of a built .oikapp.

Development cycle

1. Define tables – add JSON files to tables/
2. Define roles – add JSON files to roles/
3. Set permissions – configure permissions/default.json
4. Add business rules – optional, in rules/
5. Add workflows – optional, in workflows/
6. Test live – use oi dev to sync and test against a running server
7. Build – run oi build to create a distributable .oikapp package
8. Publish – upload to the marketplace with oi publish

See Organizing Your Code for the full directory layout.

Dependencies and cross-app access

There are two ways an app can relate to another:

• dependencies declare apps that must be installed first. List them as @provider/name strings; they’re resolved automatically at install time.
• cross_app_access declares that your app needs to read or write tables that belong to another app. Set required: true if the integration is mandatory, or false if it is optional. Each entry names the provider app; the specific tables and operations are declared in the compiled package manifest and reviewed during install.

{
  "dependencies": [
    "@oikapi/crm"
  ],
  "cross_app_access": [
    {
      "provider_app": "core",
      "required": false
    }
  ]
}

App segregation means a business rule can only reach tables in its own app plus system tables — cross-app access is how you grant the exceptions. See Applications.

Demo data

Include sample data in demo-data/ for demos and evaluation:

demo-data/projects.json

{
  "table": "projects",
  "records": [
    {"title": "Sample Project", "status": "active", "budget": "10000.00"}
  ]
}

Demo data is packaged alongside the app and managed separately once installed — list or remove it with oi app demo without touching real records.