Architecture Overview

Every Velox TS application is built from procedures — type-safe functions that define your business logic once and expose it through multiple protocols and frontiers simultaneously. Your architecture is shaped by two independent choices: how clients talk to your API, and how (or whether) you deliver a frontend.

The Core Abstraction: Procedures

At the heart of Velox TS is the procedure — a type-safe function that can be exposed as both tRPC and REST:

import { resourceSchema, resource } from '@veloxts/router';

// Define resource schema with field visibility
const UserSchema = resourceSchema()
  .public('id', z.string())
  .public('name', z.string())
  .authenticated('email', z.string())
  .build();

const getUser = procedure()
  .input(z.object({ id: z.string() }))
  .query(async ({ input, ctx }) => {
    const user = await ctx.db.user.findUniqueOrThrow({
      where: { id: input.id }
    });
    return resource(user, UserSchema.public);
  });

This single definition generates:

• tRPC endpoint — Full type inference for TypeScript clients
• REST endpoint — GET /api/users/:id for any HTTP client
• Context-dependent outputs — Different fields based on user access level

Because the same procedures power every architecture, your choices come down to two questions.

Two Choices, One Procedure Layer

API Protocol: tRPC, REST, or Both

These options are non-exclusive. A single set of procedures can expose tRPC endpoints, REST endpoints, or both at the same time. You don’t have to pick one — and in fact, serving both protocols from the same procedures is the default.

Tip

Dual-protocol (tRPC + REST from the same procedures) is the default behavior, not a special configuration. You get both unless you explicitly opt out of one.

Protocol	Best for	Learn more
tRPC	TypeScript clients, full type inference	tRPC API
REST	Non-TS clients, mobile apps, public APIs, OpenAPI	REST API
Both	Different consumers with different needs (the default)	Hybrid

Frontend Delivery: SPA or RSC

This choice is mutually exclusive — pick one project shape when you scaffold your application.

Frontend	Project shape	Process model	Learn more
Vite SPA	Monorepo with apps/api + apps/web	Two processes	SPA + Backend
RSC (Vinxi)	Single package, file-based routing	One process	Full-stack RSC

Note

If you only need an API with no frontend, use the --default or --auth template and skip the web app. It’s the SPA architecture without the SPA.

Pick a Template

By use case

• Building a backend for a TypeScript SPA? Use --default or --trpc
• Building a full web app with SSR? Use --rsc or --rsc-auth
• Need authentication? Use --auth or --rsc-auth
• All your consumers are TypeScript? Use --trpc
• Need OpenAPI docs or non-TS clients? Use --default or --auth

All templates

Template	Frontend	Protocol	Auth	Command
Default	Vite SPA	REST (+ tRPC ready)	No	npx create-velox-app my-app
Auth	Vite SPA	REST (+ tRPC ready)	JWT	npx create-velox-app my-app --auth
tRPC	Vite SPA	tRPC only (+ REST ready)	No	npx create-velox-app my-app --trpc
RSC	RSC (Vinxi)	REST (embedded)	No	npx create-velox-app my-app --rsc
RSC + Auth	RSC (Vinxi)	REST + auth (embedded)	JWT	npx create-velox-app my-app --rsc-auth

Tip

Templates are starting points. You can add tRPC to a REST template or REST to a tRPC template at any time.

Technology Stack

Layer	Technology
HTTP Server	Fastify
RPC	tRPC
Validation	Zod
ORM	Prisma
Full-stack	Vinxi + React 19

Deep Dives

API Protocol

REST API Naming conventions, OpenAPI generation, and custom routes.

tRPC API End-to-end type safety for TypeScript clients.

Hybrid Serve REST and tRPC from the same procedures.

Frontend Delivery

SPA + Backend Separate frontend and backend with a type-safe client.

Full-stack RSC Unified codebase with React Server Components and Vinxi.