prabsstack

PrabsStack

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

Table of Contents

• Overview
• Core Concepts
• Features
• Quick Start
• Installation
• Architecture
• CLI Commands
• Project Structure
• Documentation
• Contributing
• License

Overview

PrabsStack is a framework that reimagines application architecture around seven composable primitives: Pulse (versioned contracts), Conduit (registry-based HTTP binding), Weave (business logic with audit trails), Drift (deterministic pipeline), Guardrails (security enforcement), Glyph (auto-generated typed clients), and Orbit (observable state management).

Unlike traditional frameworks that blur responsibility boundaries, PrabsStack enforces strict separation of concerns through primitive-driven design, enabling teams to reason about code, scale operations, and build with confidence.

Why PrabsStack?

• Deterministic Architecture: Every interaction follows a predictable, auditable pipeline
• Type-Safe: Full TypeScript support with strict mode enabled by default
• Observable: Built-in structured logging, tracing, and metrics collection
• Secure by Default: Security policies, JWT enforcement, CORS configuration, rate limiting
• Developer-Friendly: Auto-generated clients, comprehensive CLI, clear error messages
• Production-Ready: Battle-tested patterns for real-world applications

Core Concepts

The Seven Primitives

• Pulse - Versioned, immutable contracts defining request/response boundaries
• Conduit - Registry-based HTTP bindings connecting contracts to handlers
• Weave - Pure business logic with deterministic execution and audit logging
• Drift - 9-stage deterministic pipeline orchestrating request processing
• Guardrails - Security layer enforcing authentication, authorization, and rate limiting
• Glyph - Auto-generated, type-safe client libraries from Pulse contracts
• Orbit - Observable state atoms for reactive state management

Design Principles

• Responsibility Isolation: Each primitive has a single, well-defined purpose
• Explicit Over Implicit: Configuration is explicit, magic is minimized
• Observability First: Every operation generates structured, traceable logs
• Security First: Security policies are non-optional and explicitly configured
• Determinism: Same inputs always produce same outputs under identical conditions
• Testability: Each layer can be tested independently in isolation

Features

✅ Type-Safe Contracts: Define APIs with Pulse, get automatic validation
✅ Deterministic Pipelines: 9-stage Drift pipeline ensures predictable behavior
✅ Auto-Generated Clients: Glyph generates type-safe clients from contracts
✅ Security Policies: Role-based access control, JWT validation, CORS configuration
✅ Audit Trails: Weave logs all business logic execution with context
✅ Observable State: Orbit provides reactive state with automatic tracking
✅ Structured Logging: JSON logs with trace IDs for complete observability
✅ Rate Limiting: Built-in protection against abuse and resource exhaustion
✅ Error Sanitization: Prevents information leakage in error responses
✅ Comprehensive CLI: Commands for scaffolding, development, building, and more

Quick Start

Using NPX (Recommended)

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

Open http://localhost:5173 in your browser.

Manual Setup

# Clone or download PrabsStack
git clone https://github.com/yourusername/prabsstack.git
cd prabsstack

# Install dependencies
npm install

# Build the framework
npm run build

# Create a new project
npm run build && node dist/cli/index.js create my-app

Installation

Requirements

• Node.js: 18.0.0 or higher
• npm: 8.0.0 or higher (or yarn/pnpm)
• TypeScript: 5.0 or higher

From NPM (when published)

npm install -g prabsstack

From Source

git clone https://github.com/yourusername/prabsstack.git
cd prabsstack
npm install
npm run build
npm link

Then use:

prabsstack create my-app

Architecture

Layers

PrabsStack follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────┐
│  Client Layer (Web/Mobile)                          │
│  - Glyph (Auto-generated clients)                   │
│  - Orbit (State management)                         │
└────────────────────┬────────────────────────────────┘
                     │ HTTP/WebSocket
┌────────────────────┴────────────────────────────────┐
│  Transport Layer                                     │
│  - CORS, CSRF, Content-Type validation             │
│  - Request/Response transformation                 │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────┐
│  Guardrails (Security Layer)                        │
│  - Authentication (JWT/API Key)                    │
│  - Authorization (Role-based)                      │
│  - Rate Limiting                                   │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────┐
│  Drift Pipeline (9 Stages)                          │
│  1. Receive     → 2. Parse    → 3. Validate        │
│  4. Authenticate→ 5. Authorize→ 6. Prepare         │
│  7. Execute     → 8. Transform→ 9. Send            │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────┐
│  Conduit (HTTP Binding)                             │
│  - Route to Handlers                               │
│  - Contract Registry                               │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────┐
│  Weave (Business Logic)                             │
│  - Domain Handlers                                 │
│  - Deterministic Execution                         │
│  - Audit Logging                                   │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────┐
│  Data Layer                                         │
│  - Databases                                       │
│  - External Services                               │
│  - Cache                                           │
└─────────────────────────────────────────────────────┘

CLI Commands

create

Create a new PrabsStack project:

prabsstack create <project-name> [--output-dir]

Generates a complete full-stack project with:

• Backend with Pulse contracts, Weave handlers, Guardrails config
• Frontend with Orbit state, Glyph clients, example orchestrators
• Mobile with offline queue support
• Shared contracts, schemas, and policies
• Tests and configuration files

dev

Start development server with hot reload:

npm run dev

Monitors for changes and rebuilds automatically.

build

Compile TypeScript and prepare distribution:

npm run build

Outputs optimized code to dist/ directory.

glyph

Generate type-safe client from Pulse contracts:

prabsstack glyph <contract-file> [--output-dir]

Generates TypeScript client with full type support.

pulse:check

Validate Pulse contract definitions:

prabsstack pulse:check <contract-file>

Verifies contract structure, versioning, and compatibility.

guard

Validate Guardrails security configuration:

prabsstack guard <config-file>

Checks JWT secrets, CORS origins, rate limit policies.

Project Structure

Generated projects follow this mandatory structure (per REQUIREMENTS.md):

my-app/
├── prabs.config.ts
├── backend/
│   ├── prabs.config.ts
│   ├── src/
│   │   ├── bootstrap.ts          # App initialization
│   │   ├── guardrails/           # Security policies
│   │   ├── domains/              # Domain wiring (Pulse/Weave/Handler sets)
│   │   ├── handlers/             # Conduit-bound handlers
│   │   └── logic/                # Weave implementations (pure logic)
├── frontend/
│   ├── prabs.config.ts
│   ├── src/
│   │   ├── app.tsx              # Root component
│   │   ├── views/               # Screen-level views
│   │   ├── widgets/             # Reusable UI widgets
│   │   └── orchestrators/       # Orbit orchestrators using Glyph clients
├── mobile/
│   ├── prabs.config.ts
│   ├── src/
│   │   ├── app.tsx              # React Native entry
│   │   ├── screens/             # Mobile screens
│   │   ├── widgets/             # Mobile widgets
│   │   └── orchestrators/       # Orbit orchestrators with offline queue
├── shared/
│   ├── contracts/               # Pulses (contracts)
│   ├── schemas/                 # Validation schemas/codecs inputs
│   ├── codecs/                  # Serialization codecs
│   ├── policies/                # RBAC/ABAC policies
│   └── transport/               # Transport constraints (CORS, ctype)
├── tests/
│   └── pulse-flow.test.ts       # Sample contract harness
├── package.json
└── tsconfig.json

Documentation

• GETTING_STARTED.md - Step-by-step guide to build your first app
• ARCHITECTURE.md - Deep dive into design patterns and internals
• API.md - Complete API reference for all primitives
• SECURITY.md - Security best practices and threat model
• CONTRIBUTING.md - Contribution guidelines and development setup
• CHANGELOG.md - Version history and release notes
• VERSIONING.md - Versioning rules (SemVer, contracts, releases)
• REQUIREMENTS.md - Detailed specification document

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of conduct
• Development setup
• Coding standards
• Testing requirements
• Pull request process
• Issue reporting

Quick Development Setup

# Clone repository
git clone https://github.com/yourusername/prabsstack.git
cd prabsstack

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Start development
npm run dev

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation: See /docs directory
• 🐛 Report Issues: Use GitHub Issues
• 💬 Discussions: Use GitHub Discussions
• 📧 Email: [e-mail]

Roadmap

Version 2.0

• GraphQL support via Pulse
• gRPC transport layer
• Enhanced state machine support in Drift
• Plugin system for custom primitives

Version 3.0

• Distributed transaction support
• Advanced caching strategies
• Edge deployment support
• AI/ML integration helpers

PrabsStack - Primitive-Driven Architecture for the Modern Web