Voltra

---

See The Demos

Usage

Install

yarn add @resistdesign/voltra
Copy

Runtime peer dependencies:

• Consumers must provide react (required).
• Web consumers must provide react-dom.
• Native consumers must provide react-native.

Imports

Prefer the public entrypoints below to keep imports stable and IDE auto-imports clean.

The root import @resistdesign/voltra is intentionally unsupported to avoid cross-runtime bundling issues.

Preferred:

import { SimpleCFT } from "@resistdesign/voltra/iac";
import { addDNS } from "@resistdesign/voltra/iac/packs";
Copy

Not supported:

import addDNS from "@resistdesign/voltra/iac/packs/dns";
Copy

Public entrypoints:

• @resistdesign/voltra/api
• @resistdesign/voltra/app
• @resistdesign/voltra/common
• @resistdesign/voltra/web
• @resistdesign/voltra/native
• @resistdesign/voltra/iac
• @resistdesign/voltra/iac/packs
• @resistdesign/voltra/build
• @resistdesign/voltra/health

Common imports by domain:

import { addRoutesToRouteMap, handleCloudFunctionEvent } from "@resistdesign/voltra/api";
import { TypeInfo, TypeInfoORMServiceError } from "@resistdesign/voltra/common";
import { parseTemplate, computeTrackPixels } from "@resistdesign/voltra/app";
import { AutoField, AutoForm, createWebFormRenderer, getEasyLayout } from "@resistdesign/voltra/web";
import { createNativeFormRenderer, makeNativeEasyLayout } from "@resistdesign/voltra/native";
import { SimpleCFT } from "@resistdesign/voltra/iac";
import { addDNS } from "@resistdesign/voltra/iac/packs";
import { getTypeInfoMapFromTypeScript } from "@resistdesign/voltra/build";
import {
  DriverHealthStore,
  TypeInfoORMHealthMonitor,
} from "@resistdesign/voltra/health";
Copy

ORM Health Monitoring

@resistdesign/voltra/health adds optional, infrastructure-neutral ORM/index health monitoring. A monitor receives the application's configured ORM plus one driver-backed Health store, then performs bounded/resumable integrity audits, schema-drift reconciliation, retention cleanup, and strongly validated repairs.

Slow or failed ORM operations can be recorded separately through TypeInfoORMHealthOperationRecorder. Native MCP helpers can expose bounded Health preview/repair tools through the normal Voltra RouteMap authorization model; destructive MCP repair is opt-in.

See examples/api/orm-health-monitoring.ts and the live demo under site/api/health.ts.

Optional Cognito Request Authentication

When a gateway should allow requests through, handleCloudFunctionEvent can resolve authentication separately from event normalization. Missing or invalid authentication is treated as anonymous: public routes can still run, while protected routes continue to enforce their normal Voltra route auth rules.

For Cognito user pools, AWS.getCognitoAuthInfo validates the incoming bearer token and maps its subject and groups to Voltra AuthInfo. Voltra uses AWS's aws-jwt-verify internally, caches verifier instances, and leaves JWKS discovery, fetching, caching, key rotation, signature validation, and Cognito claim validation to that AWS-maintained verifier. Consumers only provide the user pool id, app client id, and accepted token type:

import {
  AWS,
  handleCloudFunctionEvent,
} from "@resistdesign/voltra/api";

const getAuthInfo = (event: AWS.IAWSCloudFunctionEvent) =>
  AWS.getCognitoAuthInfo(event, {
    userPoolId: process.env.USER_POOL_ID as string,
    clientId: process.env.USER_POOL_CLIENT_ID as string,
    tokenUse: "id",
  });

export const handler = (event: AWS.IAWSCloudFunctionEvent) =>
  handleCloudFunctionEvent(
    event,
    AWS.normalizeCloudFunctionEvent,
    routes,
    [process.env.CLIENT_ORIGIN as string],
    undefined,
    false,
    getAuthInfo,
  );
Copy

Use a gateway authorizer instead when unauthenticated requests must be rejected before they reach the cloud function. See examples/api/cognito-pass-through-auth.ts for a complete routing example.

IaC Auth/Gateway Example

addGateway authorizer provider ARNs can use CloudFormation intrinsics:

import { addGateway } from "@resistdesign/voltra/iac/packs";
import { SimpleCFT } from "@resistdesign/voltra/iac";

new SimpleCFT().applyPack(addGateway, {
  id: "ApiGateway",
  hostedZoneId: { Ref: "HostedZoneId" },
  domainName: { Ref: "ApiDomainName" },
  certificateArn: { Ref: "ApiCertificateArn" },
  cloudFunction: { id: "ApiFunction" },
  authorizer: {
    providerARNs: [{ "Fn::GetAtt": ["MyUserPool", "Arn"] }],
  },
});
Copy

addAuth can pass partial user-management id overrides without changing all defaults:

import { addAuth } from "@resistdesign/voltra/iac/packs";
import { SimpleCFT } from "@resistdesign/voltra/iac";

new SimpleCFT().applyPack(addAuth, {
  userManagementId: "UserPool",
  userManagementIds: {
    userPool: "MyUserPool",
    userPoolClient: "MyUserPoolClient",
  },
  authRoleName: "AuthRole",
  unauthRoleName: "UnauthRole",
  apiCloudFunctionGatewayId: "ApiGateway",
  apiStageName: "prod",
  adminGroupId: "AdminGroup",
  userManagementAdminGroupName: "admins",
  hostedZoneIdParameterName: "HostedZoneId",
  domainNameParameterName: "DomainName",
  sslCertificateId: "CertificateArn",
  mainCDNCloudFrontId: "MainCDN",
  callbackUrls: ["https://example.com/callback"],
  logoutUrls: ["https://example.com/logout"],
});
Copy

---

Build-time Type Parsing (Advanced)

Voltra exposes TypeScript compiler–powered parsing utilities intended only for build-time tooling (scripts, generators, CI).

These APIs depend on the TypeScript compiler and must not be imported into runtime code (e.g. Lambdas, servers, browsers).

Build entrypoint:

import {getTypeInfoMapFromTypeScript} from "@resistdesign/voltra/build";
Copy

Use this entrypoint for:

• Code generation
• Pre-build analysis
• Producing static artifacts (JSON / TS)

Do not import @resistdesign/voltra/build from runtime code.

With our powers combined!

Voltra is a state-of-the-art platform designed to streamline the creation of cloud infrastructure and complex web applications. It features a robust API with RPC, CORS, and versatile authentication options, alongside dynamic app development tools like TypeScript-driven form generation. The platform excels in Infrastructure as Code (IaC), offering features like chainable stacks and comprehensive parameter support. Its intuitive interface simplifies the addition of databases, storage, authentication, and functions through easy-to-use packs. Furthermore, Voltra enhances development workflows with advanced state management, and a smart, lightweight routing system for React front-end apps.

Features

App features include form generation via TypeInfo-driven AutoForm/AutoField with validation, constraints, and relation/custom handlers.

API	App	IaC
RPC	Easy Layout	Full Parameter Support: Groups/Labels/Types/etc...
Auth: Public/Secured/Role Based	State Management	Packs: Easy to add Database/Storage/Auth/Functions/etc...
Routing: Nesting/Handlers/Injected Handlers	Routing: Param Handlers/Parallel Routes/Hooks	Utilities: Patching Stacks/Constants/Standard Includes/etc...
MCP: Native RouteMap protocol + tool routing for LLM clients
ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships	Form Generation: AutoForm/AutoField + constraints/relations	Typed Build Spec Creation
	Form Engine: validation, defaults, denied ops, custom type flow	Typed Resource Parameters

EasyLayout (Web + Native + Core)

EasyLayout now has:

• Shared core parsing/math in @resistdesign/voltra/app (parseTemplate, computeTrackPixels, etc.).
• Web rendering via CSS Grid in @resistdesign/voltra/web.
• Native coordinate computation in @resistdesign/voltra/native.

Reference Examples

• Index: examples/README.md
• Client routing: examples/routing/app-routing.ts
• Backend API routing: examples/api/backend-routing.ts
• Forms: examples/forms/
  • examples/forms/auto-form-validation-customization.tsx
• Layout: examples/layout/
• Common types: examples/common/types.ts
  • examples/common/typeinfo-validation.ts
• Build-time parsing: examples/build/type-parsing.ts

Template syntax

header header, 1fr
side main, 2fr
\ 100px 1fr
Copy

• Row lines: <areas>, <row-track> (row track optional)
• Column line: \ <col-track> <col-track> ...
• Supported units: fr, px, %
• Named areas must form rectangles

Web usage

import { getEasyLayout } from "@resistdesign/voltra/web";

const { layout: Layout, areas } = getEasyLayout(undefined, undefined, {
  gap: 12,
  padding: 16,
})`
  header header, 1fr
  side main, 2fr
  \ 1fr 2fr
`;
Copy

Native usage

import { makeNativeEasyLayout } from "@resistdesign/voltra/native";

const layout = makeNativeEasyLayout(`
  header header, 100px
  side main, 1fr
  \\ 1fr 2fr
`);

const coords = layout.computeNativeCoords({
  width: 320,
  height: 240,
  padding: 12,
  gap: 8,
});
Copy

Web vs Native

Runtime	Rendering model	Output
Web	CSS Grid (browser layout engine)	CSS template strings
Native	Computed absolute layout	{ left, top, width, height } per area

Routing (Web + Native)

Voltra routing uses the same Route API across app/web/native. Use the platform barrel for root Route so runtime mechanics are auto-wired. The routing model is path/history based on every platform.

Reference example: examples/routing/app-routing.ts

import { Route } from "@resistdesign/voltra/web";

<Route>
  <Route path="/" exact>
    <HomeScreen />
  </Route>
  <Route path="/login" exact>
    <LoginScreen />
  </Route>
  <Route path="/signup" exact>
    <SignUpScreen />
  </Route>
</Route>;
Copy

import { Route } from "@resistdesign/voltra/native";

<Route>
  <Route path="/" exact>
    <HomeScreen />
  </Route>
</Route>;
Copy

On native, Voltra provides the missing browser-like pieces:

• history-style path state for environments without the browser History API
• deep-link URL ingress so app opens behave like web navigations
• hardware back wiring into that same history model
• the native barrel auto-selects browser behavior on React Native web targets and native-history behavior on mobile targets

How it works:

• Root <Route> (no path) is provider mode.
• Nested <Route path="..."> entries are matcher mode.
• Shared app routing matches normalized path strings on every platform.
• Web already receives a browser pathname.
• Native provides the browser-like history/path source that mobile lacks.
• Native deep-link ingress is mapped into that same path/history model.
• Strategy is auto-selected:
  • DOM + History API => browser history strategy.
  • Otherwise => in-memory native strategy.
• Native strategy automatically wires Android hardware back to route history.
  • If Voltra can go back (history.index > 0), it consumes the event and navigates back.
  • If Voltra cannot go back, the event is not consumed so OS/native container behavior continues.

Optional back affordances:

• adapter.back?.() navigates backward when supported.
• adapter.canGoBack?.() reports whether back navigation is currently possible.

Escape hatches (root-only):

• initialPath sets fallback startup path when no ingress URL exists.
• adapter allows full custom adapter control.
• ingress supports deep-link ingress wiring (getInitialURL, subscribe, URL mapping, push/replace mode).

If you are looking for backend request routing (Cloud Function/API event routing), see:

• examples/api/backend-routing.ts

Form Suites (Web + Native + BYOCS)

Voltra's form system is split into a platform-agnostic core and platform suites:

• Core contracts live under src/app/forms/core (field kinds, suite resolution, renderer factories).
• Web DOM suite lives under src/web/forms.
• React Native suite lives under src/native/forms.

Web Usage

import { createWebFormRenderer } from "@resistdesign/voltra/web";

const { AutoField } = createWebFormRenderer();
Copy

Override a single renderer:

import { withRendererOverride } from "@resistdesign/voltra/app";
import { createWebFormRenderer } from "@resistdesign/voltra/web";

const { AutoField } = createWebFormRenderer({
  suite: withRendererOverride("string", (ctx) => {
    return <input value={(ctx.value as string) || ""} onChange={(e) => ctx.onChange(e.target.value)} />;
  }),
});
Copy

Native Usage

import { createNativeFormRenderer } from "@resistdesign/voltra/native";

const { AutoField } = createNativeFormRenderer();
Copy

BYOCS (Bring Your Own Component Suite)

Provide partial overrides (renderers and/or primitives). Missing renderers are filled from the default suite and validated.

import { createWebFormRenderer } from "@resistdesign/voltra/web";

const { AutoField } = createWebFormRenderer({
  suite: {
    primitives: {
      Button: ({ children }) => <button className="my-button">{children}</button>,
    },
    renderers: {
      boolean: (ctx) => (
        <label>
          <input
            type="checkbox"
            checked={!!ctx.value}
            onChange={(e) => ctx.onChange(e.target.checked)}
          />
          {ctx.label}
        </label>
      ),
    },
  },
});
Copy

Relation + Custom Type Hooks

Renderers emit actions via:

• onRelationAction(payload) for relation fields
• onCustomTypeAction(payload) for custom types

Use these to wire modals, selectors, or editors without baking UI into the core engine.

Centralized Validation

All TypeInfo data-item validation can be run directly from @resistdesign/voltra/common:

import { validateTypeInfoDataItem } from "@resistdesign/voltra/common";
Copy

validateTypeInfoDataItem supports:

• field-level customValidatorMap callbacks that return ErrorDescriptor
• tags.validation field options:
  • validateHidden
  • validateReadonly
  • emptyArrayIsValid

AutoForm passes validation through the same centralized logic and supports:

• customValidatorMap for app-specific rules
• translateValidationErrorCode for UI-facing messages
• multiple value-level errors per field
• per-index array item errors for array fields

Validation error maps can include both value-level errors and array item errors:

{
  errorMap: {
    title: [
      { code: "MISSING_FIELD_VALUE" },
      { code: "VALUE_DOES_NOT_MATCH_PATTERN" }
    ],
    tags: [
      { code: "INVALID_TYPE" },
      {
        itemErrorMap: {
          0: [{ code: "NOT_A_STRING" }],
          2: [
            { code: "NOT_A_STRING" },
            { code: "INVALID_CUSTOM_TYPE" }
          ]
        }
      }
    ]
  }
}
Copy

• Field-level multiple errors are represented by multiple ErrorDescriptor entries in the field array.
• Array item errors are represented by itemErrorMap[index] = ErrorDescriptor[].

Error-code constants are split by purpose:

• PRIMITIVE_ERROR_MESSAGE_CONSTANTS keys follow typeof (string, number, boolean)
• DENIED_TYPE_OPERATIONS keys follow TypeOperation (CREATE, READ, UPDATE, DELETE)
• ERROR_MESSAGE_CONSTANTS exposes canonical code-keyed entries (for example NOT_A_STRING, DENIED_TYPE_OPERATION_CREATE)

Docs Site

The docs site is both reference documentation and a canonical usage example. Key pieces:

• Astro app in site/app builds the UI into site-dist/app via yarn site:build:app.
• API bundle for the docs site is built by yarn site:build:api (see site/build-api.mjs) and written to site-dist/api.
• The IaC demo template is generated by yarn site:build:iac from site/iac/index.ts and written to site-dist/iac/index.yml.
• Production demo deployment runs entirely in GitHub Actions: IaC is built and deployed first, then the app and API are built and deployed after the CloudFormation update is stable. The demo stack does not provision CodeBuild or CodePipeline deployment resources.

API docs flow:

1. yarn doc generates TypeDoc output into docs/.
2. yarn doc-to-site copies docs/ into site-dist/app/.
3. yarn site:build:app runs Astro and then yarn finalize-site to refresh the docs site with API docs.

IaC Type Generation

IaC types are generated from the AWS CloudFormation resource specification. When updating, follow this flow:

1. Download the latest CloudFormation resource specification JSON from AWS (region: us-east-1).
2. Replace the contents of src/iac/types/CloudFormationResourceSpecification.ts with the JSON payload (as the exported data).
3. Run yarn iac:types:gen to regenerate dist/IaCTypes.ts.
4. Verify dist/IaCTypes.ts looks correct, then commit both files.

Notes:

• src/iac/types/IaCTypes.ts and src/iac/types/CloudFormationResourceSpecification.ts are generated artifacts; do not edit by hand.
• The generator entrypoint is src/iac/types/generate.ts and uses src/iac/types/Renderers.ts for output.

Releasing

Voltra publishes npm packages from GitHub Releases. The release tag is used verbatim as the npm package version, so it must be valid SemVer without a leading v.

Stable releases

Use tags like:

3.0.0
Copy

Pre-releases (alpha, beta, rc)

Use tags like:

3.0.0-alpha.0
3.0.0-beta.1
3.0.0-rc.1
Copy

When the GitHub Release is marked as a prerelease, the npm publish step uses the next dist-tag instead of latest. Consumers can install prereleases with:

yarn add @resistdesign/voltra@next
Copy

Project

Build and test commands

yarn build
yarn test
yarn test:gen
yarn doc
yarn start
yarn site:build:app
Copy

Contribution guidelines

• Use Conventional Commits (feat:, fix:, doc:, chore:) with optional scopes.
• Keep subjects imperative and concise.
• Include test commands run (or reasons for skipping) in PR descriptions.