Routes and pages, one access rule underneath.

What it is for

Every screen a customer sees, and every call the screens make to the server, is a route in the apps/ui/app tree. The routes decide which organisation is shown, which lens or review is open, and whether the reader may access the page. Session, profile and access explains identity. This page lists each route and how it handles requests.

What the app tree is

The web application uses the Next.jsNext.jsThe web framework used to build and run the NovusLens interface. It provides pages, server code and request handlers. App Router. A folder under apps/ui/app containing page.tsx defines a page. A route.ts defines a handler that returns data or files. Three files wrap every page: layout.tsx (the root layout), error.tsx (the error screen) and global-error.tsx (the fallback when the root layout itself fails).

Most pages are server componentsServer componentAn interface component prepared on the server before the resulting page is sent to the browser.. They read the signed-in viewer, load the organisation through a single load path, and render or refuse before any HTMLHTMLHypertext Markup Language: the format used to describe a web page's content and structure. is sent. Each page that reads the request’s search parameters exports dynamic = "force-dynamic", so it is rendered per request and never served from a build-time copy.

The route table

Where a page says viewer (dev only), the parameter is honoured only outside the customer profileDeployment profileA setting that selects customer or development behaviour. Customer mode refuses development credentials and uses the signed-in session as the identity., and only when no session cookieCookieA small value a browser keeps and sends back to a website. NovusLens uses a signed cookie to remember the signed-in account. is present. In the customer profile it is ignored. The rule is in resolveViewer in lib/session.ts.

How the lens works on /

The home page reads the URL and decides what to show. The steps run in this order.

1. No organisation. Without org, the page redirects to /twins. There is no default organisation.
2. Viewer and access. The viewer is resolved from the session, then (dev only) from viewer, then (dev only) from the cxo-{org} convention. The organisation is then loaded through loadTwinForPage. The access-refusal component shows signed-out, not-authorised or forgotten states. The rest of the page does not render.
3. Redirect to the overview. When none of lens, view, cell or drill is present, the page redirects to /overview with org and viewer carried over. A tab parameter on its own does not prevent this redirect.
4. The picture. view=telemetry selects the measured picture. Any other value, or none, selects told.
5. Drill and cell. drill opens the units inside a cell only when it names a cell whose parent is in the snapshot. cell selects a cell only when it exists in the snapshot. Anything else is ignored.
6. Lens. lens is used when it is one of the values in the LENSES set in app/page.tsx: twin, map, alignment, governance, domains, ask, timeline and knowledge. Any other value gives twin. The tab value is passed to the view as its starting tab.

The alias routes depend on this. /meaning sets lens=knowledge, so the knowledge libraryKnowledge libraryThe organisation’s written procedures and definitions. Each entry records its source, date and who can read it. NovusLens cites these entries as supplied information. opens on the home page. /search sets lens=ask and section=search, which opens the search section of Ask and find.

Interfaces

Route handlers that serve files

/help-docs/[name] accepts only names matching lower-case letters, digits, underscores and hyphens followed by .html. Without a viewer it redirects to /login with status 303. The user and operations manual names redirect to /docs/manuals/…, retaining browser fragments. Other names read their legacy file; a missing file returns 404. File responses are private, no-store.

/help-images/[name] accepts only lower-case letters, digits and hyphens followed by .png. Without a viewer it returns 401 with a sentence asking the reader to sign in. A missing file returns 404. Responses are private, max-age=3600.

The legacy reference and picture handlers read from the help-docs and help-images folders under the application’s working directory. The route comments say those folders are copied in by scripts/guide_documents.py; the application itself does not write them.

Brief routes

/brief/download needs org, or it returns 400. It resolves the viewer, with the dev-only default, and returns 401 when there is none. In the customer profile a request with no session therefore receives 401. It builds an HTML attachment named after the organisation. It records the file hashHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records. and a new export identifier, and includes a /brief/status link. A refusal from the access layer returns 403.

/brief/status takes the export identifier and reports one of three outcomes: the tracked records are unchanged, they have been superseded, or current support could not be established. It states that the comparison does not certify the brief’s conclusions.

Application programming interface (API) routes

The identity rules behind these routes, including why the reasoning proxyProxyA service that receives a request and forwards it to another service. The NovusLens web proxy adds the signed-in identity and service token. overwrites any viewer the caller names, are described in session, profile and access.

Layout and error pages

layout.tsx wraps every page. It passes the session identity to client providers. A flag enables the development viewer fallback only outside the customer profile. It also renders the account menu. The document title is “NovusLens — Live Twin”.

error.tsx is the error screen. It is a client componentClient componentAn interface component whose interactive code runs in the browser.. It shows “We can’t load your organisation right now”, a reload button and a /login link. Its support reference uses the error digest or organisation-unavailable.

global-error.tsx is the fallback when the root layout fails. It renders its own html and body and then the same content as error.tsx.

The app tree has no not-found.tsx, so an unknown path uses Next.js’s default not-found response.

Invariants and failure behaviour

• A page never defaults to an organisation or an account. Without org the page goes to /twins. Without a session in the customer profile the page shows a refusal or a sign-in link.
• Every organisation page takes the same path through loadTwinForPage, so a refusal looks the same on every page.
• Parameters that name a cell, a finding or a lens are checked against the data before they are used. An unknown value is ignored rather than shown.
• A failure to reach the database or the reasoning service is not a refusal. Page failures reach error.tsx or appear as messages, as in the activity log. The contextual-help APIAPIApplication programming interface: a defined way for one program to request data or actions from another. returns JSON 503 for an unavailable Guide database. The bundled documentation remains readable.
• The login form throttles attempts per account and per source address. Five failures in ten minutes lock out further attempts for that account or address. A wrong passphrase and an unknown account get the same message.