Server Utility Overview

The srvkit folder contains server-only logic used by services, signals, and server jobs. Put reusable server abstractions here so convention files can stay focused on business behavior.

This is also the safe place to wrap external libraries. Major convention files such as *.service.ts are intentionally strict about arbitrary external imports, so vendor SDKs and low-level server APIs should usually pass through srvkit first.

What Belongs In srvkit/

Guard

Request protection logic used by signals, such as checking account roles before a mutation runs.

InternalArg

Context-derived values injected into signal execution, such as account, self, or admin identity.

Middleware And WebProxy

Request pipeline extensions for attaching server context, redirecting, rewriting, or adding headers before app logic runs.

Server helper

Reusable server logic such as hashing, encryption, file handling, image inspection, or token utilities.

Adaptor

A service dependency wrapper for external systems such as storage, queues, email, payment, or vendor APIs.

Class utility

Server-only classes such as logic abstractions or SDK clients that are injected into services through options.

Server Level Appliance

Server level appliances are registered once in the app or library option chain. WebProxy changes the web request before routing, and Middleware prepares request context before signal endpoint logic runs.

WebProxy handles web routing before a page is selected.

Middleware

Middleware runs around signal requests and can attach server-derived values to the request context before business logic runs.

srvkit/middlewares.ts

WebProxy

WebProxy runs before the web request reaches the page. Use it when you need redirects, rewrites, or request header changes for routing and rendering.

srvkit/webProxies.ts

Apply Them In Options

After declaring them in srvkit, register middleware and web proxies in the app or library option chain.

lib/option.ts

Signal Level Appliance

Signal level appliances are applied per signal endpoint or slice. Guard decides whether the endpoint can run, and InternalArg converts trusted server context into exec arguments.

After server-level Middleware prepares context, signal-level appliances control each endpoint.

Guard

A Guard checks whether a request can run a signal. Use it for authentication, role checks, ownership checks, or any server-side request protection.

srvkit/guards.ts

order.signal.ts

InternalArg

An InternalArg reads request or websocket context and adds a server-derived value to the signal exec arguments. Use it when business logic needs context data without asking the client to send it.

Service Logic And External Libraries

If service code needs crypto, AI SDKs, HTTP clients, or other server-only packages, wrap that logic in srvkit first. A service can import pure helpers directly, but class instances used with use<T>() must be provided from the option chain first.

srvkit/createHash.ts

srvkit/EmailClient.ts

option.ts

order.service.ts

Adaptor And plug

Adaptors make external systems available through service dependencies. Define a small adaptor in srvkit, then plug it into the service that needs it. Adaptors can also plug other adaptors as long as they do not create a circular dependency.

srvkit/paymentApi.ts

order.service.ts

Practical Rules

Put server-only helper code in srvkit when a service or signal would otherwise become noisy.

Use srvkit for external libraries before importing them into convention files.

Use Guards for request protection and InternalArgs for context-derived signal arguments.

Use adapt and plug when a service needs a reusable external system dependency.

Keep app-specific integrations in app srvkit and reusable integrations in library srvkit.

Server Utility Overview

What Belongs In Srvkit

Server Level Appliance

Signal Level Appliance

Service Logic And External Libraries