Skip to content

Architecture and layers ​

Rangka OS is organised in seven layers. An upper layer may use a lower one, never the reverse.

LayerHoldsFilesWho changes it
6 · PresentationThemes, layouts, pages built from UI blocksthemes/*.rk, layouts/*.rkOwner, Rangka AI (low risk)
5 · Modules and appsModules: models, views, rules, flows, roles, print formats, imports, processes. Apps: the modules they use, menu, dashboards, home, onboardingmodules/<module>/**.rk, apps/<app>/**.rkApp authors
4 · OrganisationInstalled apps, plan, config, company overlays, the company's own tables and automations; organisations and members are dataconfig.rk, features.rk, custom/*.rk, models/x_*.rk, flows/*.rkOwner, Rangka AI (medium risk)
3 · IntegrationsBusiness connectors<connector>/connector.rkAdmin
2 · System capabilitiesdb, cache, queue, scheduler, realtime, files, search, notify, auth, secrets, audit, observabilitysystem.rkAdmin only
1 · KernelLoader, validator, migrations, CEL, REST + MCP, event bus, permissionsthe rangka binaryRangka OS releases
0 · DeployDocker, Helm, desktop, partner one-click, Rangka Clouddeploy/ profilesOutside the OS

Two rails run alongside: Rangka Console reads every layer for maintenance, and Rangka AI writes layers 4–6 through change sets only. People use the web app at /app/; the kernel serves it and the Console (/console/) from rangka-os/web.

An installation ​

An installation is a site folder plus the apps, modules and connectors it uses. config.rk names apps; the kernel installs the modules each app lists and everything those modules require, dependencies first. The example sites live in rangka-apps/examples/sites/ (kopi-senja, demo-jasa, demo-fnb), their demo data in rangka-apps/examples/fixtures/.

text
rangka-apps/examples/sites/kopi-senja/
  system.rk        # layer 2: which capabilities and drivers
  features.rk      # layer 4: plans and the apps they allow
  config.rk        # layer 4: installed apps, locale, tax, approvers, theme, layout
  custom/          # layer 4: overlays — company fields and rules on module models
  models/, flows/  # layer 4: the company's own tables (x_…) and automations (contract 0016), when it has any
  themes/          # layer 6
  layouts/         # layer 6
rangka-apps/apps/{crm,jasa_proyek,fnb_cabang}/       # layer 5: apps (menu, dashboards, home, onboarding)
rangka-apps/modules/{contacts,invoicing,stock,…}/    # layer 5: modules (models, rules, flows, roles)
rangka-connectors/<connector>/                       # layer 3

The kernel finds modules/ next to the apps folder (--modules or RANGKA_MODULES to use another one).

Inside the kernel ​

text
 .rk files ──► loader (strict YAML, line:col) ──► schema + meaning checks ──► metadata
                                                                              │
          ┌──────────────────────────┬──────────────────────┬──────────────────┤
          ▼                          ▼                      ▼                  ▼
   migrations (Postgres)   lifecycle engine (CEL)   REST /api/v1 + SSE     MCP /mcp
                                     │
                     queue · scheduler · cache · audit · Rangka ID

The web app's client engine (web/app/engine.js, which grew out of the browser prototype) and the Python validator (tools/rangka_validate.py) are the reference semantics; the kernel's tests check it matches them, including dashboard numbers and validator output byte for byte (make compare-python).

Relationship to Omilo ​

Omilo is a sister project: a company OS of AI helpers. Rangka is the business-apps OS of records, stock and money. Omilo signs in with Rangka ID and reaches Rangka through MCP; Rangka never depends on Omilo.

Rangka OS is source-available under the Elastic License 2.0 (ELv2). Free to self-host.