The Blueprint Engine - UI Frame (Frontend)

Welcome to the uiframe of The Blueprint Engine! This frontend is built using Next.js 16 (App Router), React, and Shadcn UI. It is designed to connect seamlessly to the NestJS engine backend.

This README focuses strictly on setting up and configuring the frontend dashboard environment.

🚀 Getting Started

Prerequisites

• Bun (Recommended) or Node.js (v20+)
• The engine backend should be running on http://localhost:5201 for the API calls to succeed.

1. Installation

Clone the repository and install the dependencies using Bun:

cd uiframe
bun install

2. Environment Configuration

Create a .env.local file in the root of the uiframe directory. The primary configuration needed is pointing the dashboard to the backend engine.

# Point to your local NestJS Engine instance
NEXT_PUBLIC_API_BASE_URL=http://localhost:5201/api/v1

3. Running the Development Server

Start the development server. By default, we have configured it to run on port 5200 to avoid conflicts with the backend.

bun run dev

Open http://localhost:5200 in your browser. You should see the dashboard!

🏢 Multi-Tenancy Architecture

This frontend supports a multi-tenant architecture out-of-the-box, matching the backend engine's tenant capabilities.

• Login Flow: When users log in, they must provide an accountId (or __root__ for platform admins).
• Session Management: Once authenticated, the JWT token provided by the backend contains the tenant scope. All subsequent API calls automatically inherit this scope.
• Tenant Context: The UI conditionally renders tenant-specific actions versus platform-wide actions depending on the user's role and account scope.

🛠️ Built-In Generators

We have created specialized CLI tools to speed up your frontend development.

Dynamic Form Generator

Generate full Zod validation schemas and react-hook-form UI components instantly using JSON metadata.

1. Create a schema.json:

{
  "entityName": "Product",
  "fields": [
    { "name": "title", "type": "string", "required": true, "ui": "input" },
    { "name": "price", "type": "number", "ui": "number-input" }
  ]
}

2. Run the generator:

bun run generate:form --schema=schema.json

This automatically outputs a wired-up React component and Schema into src/components/forms/.

📁 Project Structure

• src/app/(main): The primary dashboard pages (Users, Roles, Auth, Settings, CRM, etc.).
• src/lib/api-client.ts: The core Fetch wrapper configuring JWT tokens, interceptors, and error handling for the backend engine.
• src/components/ui: The Shadcn UI primitive components.
• scripts/: Custom CLI tools for code generation.

🤝 Need Help?

Ensure your backend engine is running. For any UI-specific component modifications, refer to the Shadcn UI documentation.