obix-template-node

OBIX Heart UX — Node.js app template
Data-oriented · Accessibility-first · #NoGhosting protocol built-in

A batteries-included starter for building full-stack Node applications with the @obinexusltd/obix mono-repo libraries. The template wires together:

• Core runtime — typed state machine with named policy guards
• Server — Express REST API backed by SQLite (WAL mode)
• UI — minimal DOM renderer, no virtual DOM, subscription-driven
• CLI — commander + inquirer terminal interface

Folder structure

obix-template-node/
├── src/
│   ├── core/
│   │   ├── types.ts       ← domain types (Item, Team, actions, events)
│   │   ├── runtime.ts     ← AppRuntime: dispatch, reduce, subscribe, policies
│   │   ├── policies.ts    ← #NoGhosting compliance, escalations, reports
│   │   └── index.ts       ← createApp() factory + public re-exports
│   ├── ui/
│   │   ├── renderer.ts    ← ObixNode → DOM, mount(), card/badge/button helpers
│   │   └── main.ts        ← browser entry point, seeds state, renders UI
│   ├── server/
│   │   ├── database.ts    ← better-sqlite3 persistence layer
│   │   └── app.ts         ← Express server, REST routes, hydrate-on-boot
│   └── cli/
│       └── index.ts       ← commander CLI: team/item/compliance/status
├── package.json
├── tsconfig.json
└── README.md

Quick start

# 1. Install dependencies
npm install

# 2. Build TypeScript
npm run build

# 3. Start the API server  (default port 3000)
npm start

# — or — run in watch mode during development
npm run dev

# 4. Use the CLI
npm run cli -- team create
npm run cli -- item create
npm run cli -- compliance violations
npm run cli -- status

Using the REST API

# Health check
curl http://localhost:3000/health

# Create a team
curl -X POST http://localhost:3000/api/teams \
  -H "Content-Type: application/json" \
  -d '{"name":"My Team","description":"OBIX demo"}'

# Create an item
curl -X POST http://localhost:3000/api/items \
  -H "Content-Type: application/json" \
  -d '{"title":"First item","teamId":"<teamId>","createdBy":"me","priority":"high"}'

# Check #NoGhosting violations
curl http://localhost:3000/api/compliance/violations

Core concepts

Controller → Control → Controllee

OBIX uses the bioware model:

| Layer | Role | In this template | |---|---|---| | Controller | Captures intent / input | CLI prompts, HTTP request bodies | | Control | Computes the transition | AppRuntime.dispatch() + reducer | | Controllee | Applies the output | DOM renderer / SQLite writes |

#NoGhosting policy

Every dispatch() runs named policy guards before notifying subscribers. Add your own in core/runtime.ts:

runtime.addPolicy('my_rule', (state) => {
  // return false to halt and surface the violation
  return myCondition(state);
});

validateCompliance() and checkEscalations() in core/policies.ts run the same guards on demand and return typed violation/escalation objects.

State machine

Swap out the domain types in core/types.ts to model your own entities. The AppAction discriminated union, the reducer in runtime.ts, and the DB schema in database.ts are the three places you need to touch when adding a new entity.

Adapting the template

1. Rename Item → your entity in src/core/types.ts
2. Add actions to AppAction and cases to the reducer in runtime.ts
3. Add DB table in database.ts migrate()
4. Add REST routes in server/app.ts
5. Add CLI commands in cli/index.ts
6. Add policy guards via runtime.addPolicy()

Scripts

| Script | What it does | |---|---| | npm run build | Compile TypeScript → dist/ | | npm run dev | tsx watch the server | | npm start | Run compiled server | | npm run cli -- <cmd> | Run CLI via tsx | | npm test | Vitest test suite | | npm run clean | Remove dist/ |

OBINexus lineage

This template is part of the OBINexus Heart UX mono-repo (@obinexusltd/obix). It follows the same Controller → Control →

Maintainer: Nnamdi Michael Okpala [email protected]
License: MIT