# RESTForge Platform

[![npm version](https://img.shields.io/npm/v/@restforgejs/platform.svg)](https://www.npmjs.com/package/@restforgejs/platform)
[![Node.js Version](https://img.shields.io/node/v/@restforgejs/platform.svg)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-commercial-blue.svg)](https://restforge.dev)
[![Access](https://img.shields.io/badge/access-early%20access-orange.svg)](https://restforge.dev)

> *Schema-Driven Platform for Full-Stack Applications*

RESTForge is the schema-driven platform for building full-stack applications from a single source of truth. As an umbrella brand, RESTForge brings together complementary products: **RESTForge Runtime Server**, the deterministic backend infrastructure platform; **RESTForge CLI**, the backend API generator; and **RESTForge Designer**, the frontend generator.

This package is the **RESTForge Runtime Server**. It executes the JavaScript modules produced from schema configuration, providing routing, validation, caching, distributed locking, idempotency, and other reliability primitives required by production-grade backend APIs.

> **Scope Notice:** RESTForge Platform is a backend framework and code generator for full-stack Node.js applications. It is not an API testing tool, API client, request inspector, or HTTP debugging utility. The platform's purpose is to generate and run production backend APIs from schema configuration, not to consume or test third-party APIs.

---

## Access & Availability

RESTForge is currently in **closed evaluation** with a select group of early adopters. The platform is feature-complete and currently being evaluated by early adopters.

Access requires a valid license key:

- **Early Access Program** — Limited slots for volunteer evaluators providing structured feedback. [Apply at restforge.dev](https://restforge.dev)
- **Commercial Trial** — Coming soon. Register interest at [restforge.dev](https://restforge.dev) to be notified when trial licenses open to the public.
- **Commercial License** — Available upon general release.

> **Note:** Installing this package without a valid license key will not grant runtime access. The package is published on npm to simplify distribution for authorized evaluators.

---

## Core Values

| Pillar | Meaning |
|--------|---------|
| **Pragmatic** | Real solutions to real problems engineering teams face every day |
| **Efficient** | Minimal effort, maximum output, from schema to production application in minutes |
| **Reliable** | Production-ready, with built-in reliability primitives for real-world scenarios |

---

## Why RESTForge

RESTForge is built for engineering teams that value time and want **full control over generated code**. Unlike ORMs that hide SQL or low-code platforms that constrain flexibility, RESTForge generates standard JavaScript that can be read, debugged, and extended with familiar Node.js tooling. Generated code runs on the RESTForge runtime, which is an intentional infrastructure component rather than an abstraction that obscures how the application works.

- **Auto-generated endpoints** from schema configuration handle CRUD scaffolding, letting teams focus on business rules
- **Equal multi-database support** across PostgreSQL, MySQL, and Oracle
- **Consistent API standard** through a universal URL pattern and unified response envelope
- **Production-grade primitives** for cache, distributed lock, idempotency, and rate limiting
- **Readable generated code** that works with standard debuggers, profilers, and linters

---

## Key Capabilities

### Automatic API Generation
Endpoints are generated by **RESTForge CLI** from schema configuration per business entity, then executed by this runtime. Coverage includes standard CRUD operations plus advanced actions such as composite master-detail, workflow transitions, and import/export.

### Action-Based Endpoints
All operations follow a universal pattern `POST /api/{project}/{endpoint}/{action}`. This design supports complex filters, large payloads, and nested conditions without URL length limitations.

### Declarative Validation
Field validation is defined in the schema, keeping rules centralized and easy to maintain. Supports rich data types, flexible constraints, automatic sanitization, custom error messages, and integrity helpers such as bcrypt password hashing and UUID auto-generation.

### Database Schema Lifecycle
Schema management is supported end-to-end through dedicated CLI commands: `schema init` for scaffolding new definitions, `schema validate` for static checks, `schema generate-ddl` for SQL output, `schema migrate` for applying changes to live databases, and `schema introspect` for reverse-engineering existing databases. Schema definitions serve as the same source of truth that feeds endpoint generation, keeping the data model and API surface consistent.

### Built-in Reliability Primitives
Redis-backed components integrated at the framework level: automatic caching with invalidation, per-record distributed locks, idempotency protection on mutations, configurable rate limiting, and unique ID generation with a reservation lifecycle. The `fieldPolicy` mechanism adds row-locking and audit logging for critical columns through declarative configuration.

### Background Jobs & Data Transfer
Job scheduler based on BullMQ for cron and manual triggers, Excel export as async jobs, and three-step Excel import (upload, preview, commit) with lookup resolution and upsert strategies.

### Advanced Operations
Atomic master-detail transactions, workflow state machine with rule-validated transitions, and automatic scope filters for multi-tenant or business-context isolation.

### Security & Access Control
Built-in row-level security via Request Scope, applying per-request filters derived from JWT context (such as `app_id`, `branch_id`, or `company_id`) for multi-tenant, multi-branch, and multi-company scenarios. HTTP security headers (Helmet integration) are available without external dependencies. Enforcement happens at the backend rather than the client side, applying consistently across all endpoints.

### Real-time Data Synchronization
Live Sync broadcasts data-change notifications over WebSocket pub/sub on every successful CREATE, UPDATE, or DELETE operation. Subscribed clients receive notifications automatically without polling. The dedicated Live Sync process runs separately from the backend API, is cluster-ready via Redis pub/sub, and requires API Key authentication for connection.

---

## Design Philosophy

### Code Generation, Not Runtime Interpretation
Schema configuration is translated into JavaScript source code at build time. The runtime executes already-prepared code, avoiding parsing overhead on every request and keeping stack traces readable in the team's own modules.

### Action-Based Endpoint Pattern
Action-based endpoints replace the traditional HTTP-verb dispatch. This trade-off is deliberate: the practical needs of engineering teams take precedence over strict architectural conformity, especially for complex queries, large payloads, and composite operations.

### Equal Multi-Database Support
Each supported database has its own template generator and dialect adapter. Teams get SQL optimized for their database of choice (PostgreSQL, MySQL, Oracle) rather than a lowest-common-denominator abstraction.

---

## Scalability & High Availability

RESTForge is designed stateless, so horizontal scaling is the primary path for capacity growth. A layered HA strategy is applied, where each layer can stand on its own and subsequent layers add resilience incrementally: cluster mode, process management, zero-downtime deploy, reverse proxy, graceful shutdown, multi-server, database HA, and Redis HA.

---

## Extensibility

| Extension Point | Purpose |
|-----------------|---------|
| **Component Engine** | Lifecycle hooks before and after CRUD operations for validation, audit logging, and event publishing |
| **Custom Processor** | Free-form endpoints outside the standard CRUD pattern, declarative SQL or JavaScript |
| **Server Plugin** | Server-level extensions for middleware, background jobs, and global initialization |
| **Service Injection** | Access to `db`, `logger`, `redis`, `cache`, and other services without hardcoded paths |

---

## Out of Scope

Understanding the platform's boundaries is as important as understanding its capabilities. The following are intentionally not part of RESTForge and should be provided separately:

- OAuth or OIDC identity provider
- GraphQL endpoints
- Service mesh or API gateway functionality
- API testing, API client, or HTTP request inspection tooling — RESTForge is a backend runtime that produces and serves backend APIs, not a client that consumes or tests them

---

## License

RESTForge is proprietary commercial software.

- **Trial / Evaluation** — permitted for non-commercial evaluation, learning, and proof-of-concept purposes.
- **Commercial Use** — production deployment, revenue-generating applications, and internal business use require a valid commercial license.

Redistribution, reverse engineering, and removal of copyright notices are prohibited.

For licensing inquiries, visit [restforge.dev/licensing.html](https://restforge.dev/licensing.html).

See the `LICENSE.md` file included in this package for the full license agreement.

Copyright © 2026 RESTForge Development Team. All rights reserved.

---

## Trademark Notice

"RESTForge" and the names of its component products (Runtime Server, CLI, Designer) refer to the schema-driven backend platform and full-stack code generator distributed through the npm packages under the `@restforgejs/*` scope by the RESTForge Development Team. The mark identifies a platform builder, backend runtime, and code generation framework. It is not associated with products in unrelated categories such as API testing tools, API clients, or HTTP request inspection utilities.

---

## Security Notice

RESTForge is a commercial framework. Automated supply-chain scanners (Socket.dev, Snyk, and similar tools) may flag characteristics that are **intentional design decisions**, including obfuscated code, a `preinstall` script, network access, and dynamic code execution patterns produced by the obfuscator.

See [SECURITY.md](./SECURITY.md) for the full security policy, including:

- Supported versions and update channels
- Vulnerability reporting procedure and response timeline
- Detailed explanation of each scanner finding and why it is not a vulnerability
- Package integrity verification procedure
- Runtime security characteristics

Independent scanner scores (Socket.dev, as of publish):

| Metric | Score |
|--------|-------|
| Vulnerability | 100 / 100 |
| Quality | 99 / 100 |
| Maintenance | 95 / 100 |

No known CVEs or runtime vulnerabilities are present in this package. For security disclosures, please contact the team via [restforge.dev](https://restforge.dev) or refer to [SECURITY.md](./SECURITY.md).
