Project structure — Noderyx Documentation

01

The directory map

The layout is deliberately flat. There is no hidden convention directory and no code generation you cannot read.

PROJECT

app/
  Commands/     runnable tasks: noderyx run reports:send
  Controllers/  request handlers grouped by resource
  Middleware/   cross-cutting request behavior
  Models/       database records
  Observers/    model lifecycle hooks
database/
  migrations/   timestamped schema changes
  seeders/      repeatable sample or reference data
public/         static assets served under /public
resources/views/
  errors/       403, 404, 500, 502 pages
  *.noderframe  your pages
packages/       local packages, loaded automatically
server.js       entry point
noderyx.config.js
.env            environment values, never committed

02

app/ — the code you write

Everything under app/ is plain ES modules. Generators create the files, but nothing is magic about them: you import and wire them yourself in server.js.

Controllers/ Classes extending Controller. Routed with UserController.handle("index").

Models/ Classes extending Model with a table and a fillable allowlist.

Middleware/ Classes with async handle(context, next). Registered through app.use().

Observers/ Lifecycle hooks: creating, created, updating, updated, deleting, deleted.

Commands/ Objects with name, description, and run(args), executed by noderyx run.

03

resources/views/ — Noderframe sources

Views compile to HTML on the server and to native widgets for device builds. A file's path becomes its route-friendly name: resources/views/docs/page.noderframe renders as docs/page.

app/Controllers/DocsController.js

return this.render("docs/page", { title: "Packages" });

NOTE

The errors/ directory is used automatically for 403, 404, 500, and 502 responses—edit those views to match your brand.

04

public/ — static assets

Files here are served under /public with correct content types, ETags, and production caching. Path traversal, null bytes, and encoded escapes are refused before anything is read.

cool.css — the design system, safe to extend or replace.
site.js — theme toggle, copy buttons, and declarative data-noderyx actions.
untitled-live.js — the development reload client; never injected in production.
generated/ — output of npm run build, safe to delete and rebuild.

05

database/ — schema and data

Migrations are timestamped files exporting up(db) and, ideally, down(db). Seeders export run(db). Both receive the same adapter your models use, so the same code works on MySQL, PostgreSQL, and MongoDB.

PROJECT

database/
  migrations/20260714090000_create_users.js
  seeders/UserSeeder.js

NOTE

The migrations and seeders paths are configurable in noderyx.config.js.

06

server.js — the entry point you own

Nothing is hidden behind a bootstrapper. The file reads configuration, builds the app, registers routes and services, loads packages, and listens.

server.js

const app = noderyx({
  requireAppKey: true,
  name: config.app.name,
  environment: config.app.environment,
  views: fileURLToPath(new URL("./resources/views", import.meta.url)),
  public: fileURLToPath(new URL("./public", import.meta.url)),
  security: config.security
});

app.provide("ai", ai(config.ai));
app.get("/", HomeController.handle("index"));
await loadPackages(app, config.packages, { config });
app.listen(port, host);

NOTE

Register application routes before loadPackages() so your own paths keep priority over a package's.

07

noderyx.config.js — one place for configuration

The config module turns environment variables into typed values with the envBoolean, envNumber, and envList helpers. Each block feeds a specific subsystem.

app Name, environment, debug, URL, timezone, locale, log level.

packages Published packages to enable, with per-application options.

ai Provider, credentials, model, effort, verbosity, limits, timeouts.

database Driver-specific connection values, chosen by DB_TYPE.

cache Driver, prefix, TTL, item ceiling, and static asset max-age.

mail Transport settings consumed by mail packages.

security App key, proxy trust, body limit, CORS list, rate limit, session cookie.

mobile / native App id, app name, entry view, output directory, and API URL.

08

packages/ — local extensions

Any directory under packages/ that exports a provider is discovered and loaded at startup, with no configuration entry required. It is the fastest way to split a large application into parts.

TERMINAL

npx noderyx make:package billing

NOTE

Restart the development server after creating a package so discovery picks it up.

09

Generated directories

Three directories are produced by tooling. None of them belong in a code review, and all of them can be deleted and rebuilt.

public/generated/ Static HTML from npm run build.

platforms/mobile/ Capacitor project and .mnoderframe payloads from mobile:init.

platforms/native/ React Native screens from native:init. Only theme.js survives a rebuild.

.noderyx/update-backups/ Manifest backups written by the framework updater.