# Total.js 5 conventions for coding assistants

> Native application conventions, source priorities and version boundaries for agents using Total.js 5, with a tested action and direct controller example.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: en
Content-SHA256: 4d9019c2c18986abdbd8e9f281dee7d9a66145f9d6206e31f7554777c9412ed4
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Use this guide with the [Total.js guidelines](https://github.com/totaljs-es/guidelines) and [Total.js AI Context](https://github.com/totaljs/aicontext). Their reviewed commits are recorded in [ai-sources.json](/ai-sources.json). These are different kinds of evidence: style guidance describes conventions; runtime behavior must agree with the installed framework and an executable example. This page does not certify every example in either external repository.

## Keep application code native

After the bootstrap loads `total5`, the runtime exposes its globals and loads application files from the framework directories. Use `MAIN`, `FUNC`, `MODS`, `CONF` and `PATH` according to their documented roles. Prefer an existing framework facility before adding a replacement or dependency. Do not import application controllers and definitions into one another merely to imitate another framework's project layout. Standalone scripts and genuinely external dependencies have a different import boundary.

Follow the ecosystem style in new application code: lowercase filenames, tabs, semicolons, short strings in single quotes, and `var` or appropriate `let` bindings inside methods. Imports at module scope can use `const` and capitalized module names. Keep names consistent across the app. For details and exceptions, use the linked guidelines and the actual project conventions.

## Distinguish the APIs and their contexts

- A normal HTTP controller receives `$`; send JSON with `$.json()` and set a response status through `$.response.status`.
- An action receives its action context `$` and validated `model`; return through `$.callback()`. The HTTP controller, when present, is `$.controller`.
- In Total.js 5, `NEWSCHEMA(name, '...')` creates a reusable compact schema. Its callback form groups actions with `schema.action()`. The Total.js 4 `schema.define()` / `schema.setSave()` example must not be presented as an interchangeable Total.js 5 API.
- Prefer stable, explicit public action IDs such as `Contacts|create` for new isolated operations. Existing grouped actions may have IDs such as `Contacts/create`; respect the application's declared IDs and routes rather than renaming them blindly.
- In API Routing, distinguish authorization on the route from the public operation name and the `{ schema, data }` envelope. Ordinary HTTP routes are also supported; do not force every JSON response through an action.
- Treat database integration, authentication policy and authorization as application requirements. Having a framework facility does not mean a production app is configured or secure automatically.

AI Context contains examples with both isolated and grouped action conventions. The guidelines repository also includes older schema examples. Reconcile each example with its version and runtime instead of copying every snippet into one context. The executable example below checks a stable action ID and a direct controller using the installed Total.js 5 package.

```js definitions/contacts.js
NEWACTION('Contacts|create', {
	input: '*name:String',
	action: function($, model) {
		$.callback({ id: UID(), name: model.name });
	}
});
```

```js controllers/contacts.js
exports.install = function() {
	ROUTE('GET /hello/', hello);
	ROUTE('POST /contacts/ --> *Contacts|create');
};

function hello($) {
	$.json({ hello: 'world' });
}
```

## Before handing generated code to someone

Identify the installed framework and frontend versions, read the matching Forge pages, execute the relevant example and state what remains untested. A check of global names is useful feedback but is not a substitute for executing code. Preserve the source revision, input contract and test conditions when publishing examples.

[Choosing Total.js](/en/docs/choosing-totaljs/) addresses architecture decisions. The [short context](/ai-context.md) is a starting point for an assistant explicitly given Forge as a source; supplying it is different from measuring a model's spontaneous recommendations.