prabsstack

PrabsStack

A revolutionary primitive-driven, deterministic architecture framework for building scalable, type-safe, and observable full-stack applications.

Overview

PrabsStack is a full-stack TypeScript framework built around seven composable primitives that enforce strict separation of concerns and deterministic execution flows. Unlike traditional frameworks, PrabsStack provides a structured, auditable path from request to response through a 9-stage pipeline, making complex applications easier to reason about, test, and maintain.

Core Philosophy

• Primitive-Driven Architecture: Seven fundamental building blocks that compose into complete applications
• Deterministic Flow: Every request follows a predictable, auditable pipeline
• Type-Safety First: Full TypeScript support with strict mode by default
• Observable by Design: Built-in structured logging, tracing, and metrics
• Security Hardened: Authentication, authorization, rate limiting, and input validation out of the box

Quick Start

Installation

# Install globally (recommended)
npm install -g prabsstack

# Create new project
prabs create my-app
cd my-app

# Install dependencies
npm install

# Start development servers
prabs dev

Your application is now running:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000

Alternative: NPX (No Installation)

npx prabsstack create my-app
cd my-app
npm install
prabs dev

The Seven Primitives

PrabsStack's architecture is built on seven composable primitives:

1. Pulse - Versioned Contracts

Immutable, versioned contracts defining request/response boundaries with full schema validation.

export const todoCreatePulse = definePulse({
  pulseId: 'todo.create',
  version: '1.0.0',
  description: 'Create a new todo item',
  input: TodoCreateInput,
  output: TodoCreateOutput,
});

2. Conduit - HTTP Bindings

Registry-based HTTP routing that connects Pulses to handlers with type safety.

conduitRegistry.register(
  createHttpBinding('/api/todos', 'POST', todoCreatePulse, todoCreateWeave, {
    cors: defaultCors,
    contentType: defaultContentTypes,
  })
);

3. Weave - Business Logic

Pure functions containing business logic with deterministic execution and automatic audit trails.

export const todoCreateWeave = defineWeave<TodoCreateInput, TodoCreateOutput>({
  id: 'todo.create',
  version: '1.0.0',
  execute: async (input, context) => {
    const todo = await createTodo(input);
    return { id: todo.id, createdAt: todo.createdAt };
  },
});

4. Drift - Deterministic Pipeline

A 9-stage pipeline orchestrating request processing with hooks at each stage:

• Parse - Extract and parse request data
• Decode - Deserialize input according to contract
• Validate - Schema and business rule validation
• Authorize - Permission checks via Guardrails
• Transform - Input normalization
• Execute - Business logic via Weave
• Audit - Logging and tracing
• Encode - Serialize output
• Respond - Send HTTP response

5. Guardrails - Security Layer

Declarative security policies for authentication, authorization, rate limiting, and more.

const guardrails = buildGuardrails({
  jwt: { secret: process.env.JWT_SECRET!, algorithms: ['HS256'] },
  rateLimit: { windowMs: 60000, max: 100 },
  cors: { origins: ['http://localhost:5173'] },
});

6. Glyph - Auto-Generated Clients

Type-safe, auto-generated client libraries from Pulse contracts.

const client = createGlyphClient(todoCreatePulse, transport);
const result = await client.call({ title: 'New todo', description: 'Details' });

7. Orbit - Reactive State Management

Observable state atoms for reactive data flows in frontend and mobile applications.

const title = createOrbit('');
const asyncState = createOrbitAsync<TodoRecord | null>(null);

title.subscribe((value) => console.log('Title changed:', value));
await asyncState.execute(fetchTodoData());

Features

Developer Experience

• ✅ Comprehensive CLI - prabs create, prabs dev, prabs build, prabs glyph
• ✅ Hot Reload - Instant feedback during development
• ✅ Type-Safe - End-to-end TypeScript with strict mode
• ✅ Auto-Generated Clients - No manual API client code
• ✅ Template Batteries Included - Backend, frontend, mobile, shared code

Production Ready

• ✅ Multi-Database Support - PostgreSQL, MySQL, SQLite, Supabase, in-memory
• ✅ JWT Authentication - Secure token-based auth
• ✅ RBAC - Role-based access control
• ✅ Rate Limiting - Request throttling and DDoS protection
• ✅ Input Validation - Schema-based validation with detailed errors
• ✅ Structured Logging - JSON logs with trace IDs
• ✅ Error Sanitization - Prevents information leakage
• ✅ Graceful Shutdown - Clean server termination

Architecture

• ✅ Deterministic Flows - Predictable execution paths
• ✅ Audit Trails - Complete request/response logging
• ✅ Contract Drift Detection - Breaking change detection
• ✅ Observable State - Reactive programming support
• ✅ Modular Design - Use only what you need
• ✅ Zero Vendor Lock-in - Standard Node.js and TypeScript

Project Structure

my-app/
├── backend/
│   └── src/
│       ├── bootstrap.ts          # Server initialization
│       ├── domains/               # Feature modules
│       ├── handlers/              # Request handlers
│       ├── logic/                 # Business logic (Weaves)
│       ├── guardrails/            # Security policies
│       └── services/              # Database, external APIs
├── frontend/
│   └── src/
│       ├── main.tsx               # React entry point
│       ├── components/            # UI components
│       ├── orchestrators/         # Business logic coordination
│       ├── hooks/                 # React hooks (useOrbit)
│       └── views/                 # Page components
├── mobile/
│   └── src/
│       ├── app.tsx                # React Native entry
│       ├── screens/               # Mobile screens
│       ├── orchestrators/         # Business logic
│       └── widgets/               # Reusable components
├── shared/
│   ├── contracts/                 # Pulse definitions
│   ├── codecs/                    # Data transformations
│   ├── schemas/                   # Validation schemas
│   ├── policies/                  # RBAC policies
│   └── transport/                 # HTTP/WS config
└── prabs.config.ts                # Framework configuration

CLI Commands

Project Management

prabs create <app-name>     # Create new project
prabs dev [target]          # Start development servers
                           # Targets: backend, frontend, mobile, all
prabs build                 # Build for production

Code Generation

prabs glyph                 # Generate typed clients from Pulses

Quality Assurance

prabs pulse:check           # Validate contracts, detect drift
prabs guard                 # Security audit and linting

Configuration

prabs.config.ts

export default {
  name: 'my-app',
  version: '1.0.0',
  targets: {
    backend: { port: 3000, tls: { enabled: false }, dist: './dist/backend' },
    frontend: { port: 5173, dist: './dist/frontend' },
    mobile: { port: 19006, dist: './dist/mobile' },
  },
  env: {
    secrets: ['JWT_SECRET', 'DATABASE_URL'],
    maps: {
      backend: ['JWT_SECRET', 'DATABASE_URL'],
      frontend: [],
      mobile: [],
    },
  },
};

Environment Variables

# Server
PORT=3000
HOST=0.0.0.0
NODE_ENV=development

# Database (choose one)
DATABASE_TYPE=memory
# DATABASE_URL=postgresql://user:pass@localhost:5432/db
# SUPABASE_URL=https://xxx.supabase.co
# SUPABASE_API_KEY=xxx

# Security
JWT_SECRET=your-secret-key-here
API_KEY=your-api-key-here

# Logging
LOG_LEVEL=info
AUDIT_SINK=console

Example: Building a Feature

1. Define Contract (shared/contracts/user.ts)

import { definePulse } from 'prabsstack/pulse';
import { UserCreateInput, UserCreateOutput } from '../codecs/user.js';

export const userCreatePulse = definePulse({
  pulseId: 'user.create',
  version: '1.0.0',
  description: 'Create a new user',
  input: UserCreateInput,
  output: UserCreateOutput,
  policies: ['authenticated', 'admin'],
});

2. Implement Business Logic (backend/src/logic/user-weave.ts)

import { defineWeave } from 'prabsstack/weave';

export const userCreateWeave = defineWeave({
  id: 'user.create',
  version: '1.0.0',
  execute: async (input, context) => {
    const hashedPassword = await hashPassword(input.password);
    const user = await db.users.create({
      email: input.email,
      password: hashedPassword,
      name: input.name,
    });
    
    context.logger.info('User created', { userId: user.id });
    return { id: user.id, email: user.email };
  },
});

3. Register Conduit (backend/src/bootstrap.ts)

conduitRegistry.register(
  createHttpBinding('/api/users', 'POST', userCreatePulse, userCreateWeave, {
    cors: defaultCors,
    contentType: defaultContentTypes,
  })
);

4. Use in Frontend (frontend/src/orchestrators/userOrchestrator.ts)

import { createGlyphClient, FetchGlyphTransport } from 'prabsstack/glyph';
import { userCreatePulse } from 'shared/contracts/user.js';

const transport = new FetchGlyphTransport('http://localhost:3000');
const client = createGlyphClient(userCreatePulse, transport);

export async function createUser(data: UserCreateInput) {
  const result = await client.call(data, { 
    idempotencyKey: crypto.randomUUID() 
  });
  
  if (result.success) {
    return result.data;
  }
  throw new Error(result.error?.hint || 'Failed to create user');
}

Testing

import { test } from 'node:test';
import { createTestHarness } from 'prabsstack/testing';
import { userCreatePulse } from './contracts/user.js';

test('creates user successfully', async () => {
  const harness = createTestHarness(userCreatePulse, userCreateWeave);
  
  const result = await harness.execute({
    email: '[e-mail]',
    password: 'SecurePass123!',
    name: 'Test User',
  });
  
  assert.ok(result.success);
  assert.equal(result.data.email, '[e-mail]');
});

Deployment

Build

prabs build

Production Environment

# Set production environment
export NODE_ENV=production
export DATABASE_URL=postgresql://...
export JWT_SECRET=$(openssl rand -base64 32)

# Start server
node dist/backend/bootstrap.js

Docker

FROM node:18-alpine
WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY dist ./dist
COPY prabs.config.ts ./

EXPOSE 3000
CMD ["node", "dist/backend/bootstrap.js"]

Community & Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

We welcome contributions! Please see our contributing guidelines for:

• Code style and standards
• Pull request process
• Development setup
• Testing requirements

License

MIT © PrabsStack Team

Built with ❤️ by developers, for developers.

Start building deterministic, observable, and secure applications today with PrabsStack.