# neracu/nullrift_ui architecture

> Architecture diagram of the GitHub repository neracu/nullrift_ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neracu/nullrift_ui
- Repository: https://github.com/neracu/nullrift_ui

## Overview

1. **What this repo is**
   - NullRift UI is a **Next.js App Router** application built around one core product flow: turn a natural-language prompt into a UI component, preview it interactively, tune it visually, then export it in multiple formats.
   - The architecture is centered on a **browser-driven builder workspace** backed by a small set of server API routes and an external AI service.

2. **Top-level application surfaces**
   - `src/app/page.tsx`, `src/app/pricing/page.tsx`, and `src/components/landing/*` form the **marketing/landing experience**.
   - `src/app/login/page.tsx` and `src/components/login-signup.tsx` provide an **authentication-facing UI**, though no backend auth implementation is visible in this tree.
   - `src/app/builder/*` is the **main product surface** where generation, preview, tuning, and export happen.

3. **Server boundary: API routes**
   - The backend surface is small and lives under `src/app/api`:
     - `generate/route.ts` handles component generation requests.
     - `export/route.ts` handles exporting generated output.
     - `health/route.ts` is a basic runtime/uptime check.
   - This suggests a mostly **thin server layer**: the heavy lifting is in shared libraries, with the API acting as an orchestration boundary.

4. **AI generation pipeline**
   - The watsonx integration in `src/lib/watsonx/*` is the external AI boundary:
     - `client.ts` likely wraps HTTP calls to IBM watsonx.ai.
     - `iam-token.ts` handles credential/token acquisition.
     - `prompts.ts`, `parser.ts`, and `types.ts` define the prompt contract and response interpretation.
   - Environment variables in `.env.local.example` show the required runtime config: API key, project ID, model ID, API URL, and app URL.

5. **Builder workspace orchestration**
   - `src/app/builder/page.tsx` and `src/app/builder/builder-client.tsx` are the central coordination layer for the product.
   - The builder UI is split into focused panels/components under `src/components/builder/*`:
     - prompt input
     - generation loading/error/success states
     - style, structure, behavior, and tuning controls
     - component library selection
     - preview canvas and preview controls
     - code viewer and export modal
   - This separation implies a **stateful client workspace** with a coordinated set of controls rather than a single monolithic editor.

6. **Preview subsystem**
   - `src/lib/preview/*` is a distinct subsystem for rendering generated components safely and interactively:
     - `renderer.tsx` renders the preview.
     - `state-manager.ts` tracks preview state and interactions.
     - `iframe-bridge.ts` indicates the preview is isolated through an **iframe-based message bridge**.
     - `types.ts` defines the preview contract.
   - The UI components in `src/components/builder/preview-*` are the visible layer on top of this subsystem, enabling responsive/testing-oriented preview behavior.

7. **Tuning and transformation pipeline**
   - `src/lib/tuning/*` is where generated component structure gets adjusted after generation:
     - style transformations
     - structure editing
     - behavior schema and validation
     - field insertion/merge logic
     - layer/order and contrast utilities
   - This is an important architectural boundary: the app does not just regenerate from scratch for every change; it appears to **transform an intermediate component model** to support visual fine-tuning.

8. **Component library and code generation**
   - `src/lib/library/component-library.ts` plus `src/hooks/use-component-library.ts` support a **prebuilt template/library concept** that can seed or influence generation.
   - `src/lib/generator/code-builder.ts` is the core code assembly layer, likely turning structured component data into final source code.
   - `src/lib/builder/framework-preview-code.ts` and `src/lib/builder/generation-stages.tsx` suggest the generation flow has explicit stages and framework-specific preview helpers.

9. **Export subsystem**
   - Export is separated from generation in `src/lib/export/*`:
     - `react-exporter.ts`
     - `vue-exporter.ts`
     - `html-exporter.ts`
     - `index.ts`
   - `src/types/export.ts` defines the export contract.
   - This means the system likely generates or normalizes an internal representation first, then fan-outs into **multiple output formats** at export time.

10. **Shared UI and design system**
   - Reusable UI primitives live in `src/components/ui/*`, aligned with the presence of Radix-style components and shadcn-like patterns.
   - Decorative/marketing-specific effects are in `src/components/aceternity/*` and landing-specific sections in `src/components/landing/*`.
   - Global styling is handled through `src/app/globals.css`, `tailwind.config.ts`, and `postcss.config.js`, so Tailwind is part of the app’s main rendering and theming model.

11. **Cross-cutting client behavior**
   - Several hooks provide app-wide interaction behavior:
     - `use-preview` for preview state/control
     - `use-tuning` for tuning workflow
     - `use-keyboard-shortcuts` for builder shortcuts
     - `use-mobile` for responsive behavior
   - `src/components/providers/toast-provider.tsx` and `src/components/error-boundary.tsx` handle global UX concerns like notifications and failure containment.

12. **Config and content model**
   - `src/config/*` stores product-level constants and presentation data such as site metadata, prompt examples, pricing plans, watsonx settings, and export modal theme data.
   - This keeps the app’s configuration and static content separate from the builder logic, which is useful for diagramming as a **shared config layer**.

13. **Testing and quality boundaries**
   - The repo includes both **unit tests** and **integration tests** under `tests/`.
   - Coverage focuses on core architecture seams: generator logic, preview state management, tuning utilities, and watsonx client/parser/prompts.
   - This strongly suggests the main risk areas are the **AI integration**, **stateful preview behavior**, and **code transformation logic**, not just UI rendering.

14. **Deployment/runtime shape**
   - The runtime is a standard Next.js/React/TypeScript stack with server routes and client-heavy builder interactions.
   - External service dependency is primarily **IBM watsonx.ai**; no database or message broker is visible in this repository tree.
   - The architecture is therefore best diagrammed as a **single web application** with a small server API layer and one major external AI dependency, rather than as a distributed backend system.

Main entry points: [`src/app/builder/builder-client.tsx`](https://github.com/neracu/nullrift_ui/blob/main/src/app/builder/builder-client.tsx) (Builder client), [`tests/unit/generator/code-builder.test.ts`](https://github.com/neracu/nullrift_ui/blob/main/tests/unit/generator/code-builder.test.ts) (Core tests), [`src/app/api/generate/route.ts`](https://github.com/neracu/nullrift_ui/blob/main/src/app/api/generate/route.ts) (Generate API), [`src/lib/generator/code-builder.ts`](https://github.com/neracu/nullrift_ui/blob/main/src/lib/generator/code-builder.ts) (Code builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App surfaces"]
  node_n_app_root["App root<br/>Next.js shell<br/>[layout.tsx]"]
  node_n_marketing["Landing pages<br/>Marketing routes<br/>[page.tsx]"]
  node_n_login["Login page<br/>Auth UI<br/>[page.tsx]"]
  node_n_builder_route["Builder page<br/>Workspace route<br/>[page.tsx]"]
end

subgraph group_g_builder["Builder workspace"]
  node_n_builder_client["Builder client<br/>Workspace orchestrator<br/>[builder-client.tsx]"]
  node_n_builder_panels["Builder panels<br/>UI panels<br/>[prompt-input.tsx]"]
  node_n_library["Component library<br/>Template source"]
end

subgraph group_g_ai["AI and generation"]
  node_n_api_generate["Generate API<br/>Route handler<br/>[route.ts]"]
  node_n_watsonx_client["Watsonx client<br/>AI adapter<br/>[client.ts]"]
  node_n_watsonx_contract["Prompt contract<br/>AI schema<br/>[prompts.ts]"]
  node_n_codegen["Code builder<br/>Code assembly<br/>[code-builder.ts]"]
end

subgraph group_g_preview["Preview subsystem"]
  node_n_preview_core["Preview core<br/>Preview engine<br/>[index.ts]"]
  node_n_preview_ui["Preview UI<br/>Preview controls<br/>[preview-canvas.tsx]"]
end

subgraph group_g_tuning["Tuning pipeline"]
  node_n_tuning_core["Tuning core<br/>Transform pipeline<br/>[index.ts]"]
end

subgraph group_g_export["Export pipeline"]
  node_n_api_export["Export API<br/>Route handler<br/>[route.ts]"]
  node_n_exporters["Exporters<br/>Format adapters<br/>[index.ts]"]
end

subgraph group_g_shared["Shared UI and config"]
  node_n_shared_ui["UI primitives<br/>Design system<br/>[button.tsx]"]
  node_n_shared_hooks["Client hooks<br/>Interaction hooks<br/>[use-preview.ts]"]
  node_n_shared_config["Product config<br/>Static config<br/>[site.ts]"]
end

subgraph group_g_quality["Testing"]
  node_n_tests["Core tests<br/>Unit/integration"]
end

node_n_app_root -->|"hosts"| node_n_marketing
node_n_app_root -->|"hosts"| node_n_login
node_n_app_root -->|"hosts"| node_n_builder_route
node_n_builder_route -->|"mounts"| node_n_builder_client
node_n_builder_client -->|"composes"| node_n_builder_panels
node_n_builder_client -->|"drives"| node_n_preview_ui
node_n_builder_client -->|"applies"| node_n_tuning_core
node_n_builder_client -->|"seeds"| node_n_library
node_n_builder_client -->|"requests"| node_n_api_generate
node_n_builder_client -->|"exports"| node_n_api_export
node_n_api_generate -->|"calls"| node_n_watsonx_client
node_n_watsonx_client -->|"uses"| node_n_watsonx_contract
node_n_api_generate -->|"assembles"| node_n_codegen
node_n_codegen -->|"feeds"| node_n_exporters
node_n_api_export -->|"dispatches"| node_n_exporters
node_n_preview_ui -->|"uses"| node_n_preview_core
node_n_preview_core -->|"reflects"| node_n_tuning_core
node_n_tuning_core -->|"shapes"| node_n_codegen
node_n_library -->|"influences"| node_n_watsonx_contract
node_n_shared_hooks -->|"supports"| node_n_builder_client
node_n_shared_ui -->|"supports"| node_n_builder_panels
node_n_shared_config -->|"configures"| node_n_marketing
node_n_shared_config -->|"configures"| node_n_api_generate
node_n_shared_config -->|"configures"| node_n_api_export
node_n_tests -->|"covers"| node_n_codegen
node_n_tests -->|"covers"| node_n_preview_core
node_n_tests -->|"covers"| node_n_tuning_core
node_n_tests -->|"covers"| node_n_watsonx_contract

click node_n_app_root "https://github.com/neracu/nullrift_ui/blob/main/src/app/layout.tsx"
click node_n_marketing "https://github.com/neracu/nullrift_ui/blob/main/src/app/page.tsx"
click node_n_login "https://github.com/neracu/nullrift_ui/blob/main/src/app/login/page.tsx"
click node_n_builder_route "https://github.com/neracu/nullrift_ui/blob/main/src/app/builder/page.tsx"
click node_n_builder_client "https://github.com/neracu/nullrift_ui/blob/main/src/app/builder/builder-client.tsx"
click node_n_builder_panels "https://github.com/neracu/nullrift_ui/blob/main/src/components/builder/prompt-input.tsx"
click node_n_api_generate "https://github.com/neracu/nullrift_ui/blob/main/src/app/api/generate/route.ts"
click node_n_api_export "https://github.com/neracu/nullrift_ui/blob/main/src/app/api/export/route.ts"
click node_n_watsonx_client "https://github.com/neracu/nullrift_ui/blob/main/src/lib/watsonx/client.ts"
click node_n_watsonx_contract "https://github.com/neracu/nullrift_ui/blob/main/src/lib/watsonx/prompts.ts"
click node_n_codegen "https://github.com/neracu/nullrift_ui/blob/main/src/lib/generator/code-builder.ts"
click node_n_preview_core "https://github.com/neracu/nullrift_ui/blob/main/src/lib/preview/index.ts"
click node_n_preview_ui "https://github.com/neracu/nullrift_ui/blob/main/src/components/builder/preview-canvas.tsx"
click node_n_tuning_core "https://github.com/neracu/nullrift_ui/blob/main/src/lib/tuning/index.ts"
click node_n_library "https://github.com/neracu/nullrift_ui/blob/main/src/lib/library/component-library.ts"
click node_n_exporters "https://github.com/neracu/nullrift_ui/blob/main/src/lib/export/index.ts"
click node_n_shared_ui "https://github.com/neracu/nullrift_ui/blob/main/src/components/ui/button.tsx"
click node_n_shared_hooks "https://github.com/neracu/nullrift_ui/blob/main/src/hooks/use-preview.ts"
click node_n_shared_config "https://github.com/neracu/nullrift_ui/blob/main/src/config/site.ts"
click node_n_tests "https://github.com/neracu/nullrift_ui/blob/main/tests/unit/generator/code-builder.test.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_app_root,node_n_marketing,node_n_login,node_n_builder_route,node_n_shared_ui,node_n_shared_hooks,node_n_shared_config toneBlue
class node_n_builder_client,node_n_builder_panels,node_n_library,node_n_tests toneAmber
class node_n_api_generate,node_n_watsonx_client,node_n_watsonx_contract,node_n_codegen toneMint
class node_n_preview_core,node_n_preview_ui toneRose
class node_n_tuning_core toneIndigo
class node_n_api_export,node_n_exporters toneTeal
```

## Components

### App surfaces

Marketing, auth, pricing, and the builder workspace routes.

- [App root](https://github.com/neracu/nullrift_ui/blob/main/src/app/layout.tsx): Next.js shell · Global app layout, styling, and shared providers for the Next.js runtime. · `src/app/layout.tsx`
- [Landing pages](https://github.com/neracu/nullrift_ui/blob/main/src/app/page.tsx): Marketing routes · Homepage and pricing entry points for the public site experience. · `src/app/page.tsx`
- [Login page](https://github.com/neracu/nullrift_ui/blob/main/src/app/login/page.tsx): Auth UI · Authentication-facing page and signup/login surface. · `src/app/login/page.tsx`
- [Builder page](https://github.com/neracu/nullrift_ui/blob/main/src/app/builder/page.tsx): Workspace route · Top-level builder route that hosts the main product workflow. · `src/app/builder/page.tsx`

### Builder workspace

Client-side orchestration and the interactive UI panels for generation, tuning, preview, and export.

- [Builder client](https://github.com/neracu/nullrift_ui/blob/main/src/app/builder/builder-client.tsx): Workspace orchestrator · Client-side state and coordination for generation, preview, tuning, and export. · `src/app/builder/builder-client.tsx`
- [Builder panels](https://github.com/neracu/nullrift_ui/blob/main/src/components/builder/prompt-input.tsx): UI panels · Prompt, controls, preview, code, and export components composing the workspace. · `src/components/builder/prompt-input.tsx`
- [Component library](https://github.com/neracu/nullrift_ui/blob/main/src/lib/library/component-library.ts): Template source · Prebuilt component library used to seed or influence generation. · `src/lib/library/component-library.ts`

### AI and generation

Watsonx integration and prompt-to-code generation pipeline.

- [Generate API](https://github.com/neracu/nullrift_ui/blob/main/src/app/api/generate/route.ts): Route handler · Server endpoint for component generation requests. · `src/app/api/generate/route.ts`
- [Watsonx client](https://github.com/neracu/nullrift_ui/blob/main/src/lib/watsonx/client.ts): AI adapter · HTTP boundary to IBM watsonx.ai and token handling. · `src/lib/watsonx/client.ts`
- [Prompt contract](https://github.com/neracu/nullrift_ui/blob/main/src/lib/watsonx/prompts.ts): AI schema · Prompt templates, parsing, and types for model requests and responses. · `src/lib/watsonx/prompts.ts`
- [Code builder](https://github.com/neracu/nullrift_ui/blob/main/src/lib/generator/code-builder.ts): Code assembly · Turns structured component data into final source code. · `src/lib/generator/code-builder.ts`

### Preview subsystem

Isolated rendering and state management for interactive component preview.

- [Preview core](https://github.com/neracu/nullrift_ui/blob/main/src/lib/preview/index.ts): Preview engine · Iframe bridge, renderer, and state manager for safe interactive preview. · `src/lib/preview/index.ts`
- [Preview UI](https://github.com/neracu/nullrift_ui/blob/main/src/components/builder/preview-canvas.tsx): Preview controls · Visible preview canvas, frame, and control components in the builder. · `src/components/builder/preview-canvas.tsx`

### Tuning pipeline

Transformations that refine the generated component model before preview or export.

- [Tuning core](https://github.com/neracu/nullrift_ui/blob/main/src/lib/tuning/index.ts): Transform pipeline · Style, structure, behavior, and merge utilities for editing generated components. · `src/lib/tuning/index.ts`

### Export pipeline

Format-specific exporters and export contracts.

- [Export API](https://github.com/neracu/nullrift_ui/blob/main/src/app/api/export/route.ts): Route handler · Server endpoint for exporting generated output. · `src/app/api/export/route.ts`
- [Exporters](https://github.com/neracu/nullrift_ui/blob/main/src/lib/export/index.ts): Format adapters · React, Vue, and HTML exporters for final output generation. · `src/lib/export/index.ts`

### Shared UI and config

Reusable UI primitives, cross-cutting hooks, and product configuration.

- [UI primitives](https://github.com/neracu/nullrift_ui/blob/main/src/components/ui/button.tsx): Design system · Reusable component primitives and shared visual building blocks. · `src/components/ui/button.tsx`
- [Client hooks](https://github.com/neracu/nullrift_ui/blob/main/src/hooks/use-preview.ts): Interaction hooks · Shared hooks for preview, tuning, keyboard shortcuts, and responsive behavior. · `src/hooks/use-preview.ts`
- [Product config](https://github.com/neracu/nullrift_ui/blob/main/src/config/site.ts): Static config · Site metadata, prompt examples, pricing, export theme, and watsonx settings. · `src/config/site.ts`

### Testing

Unit and integration coverage around the main architecture seams.

- [Core tests](https://github.com/neracu/nullrift_ui/blob/main/tests/unit/generator/code-builder.test.ts): Unit/integration · Coverage for generation, preview state, tuning logic, and watsonx integration seams. · `tests/unit/generator/code-builder.test.ts`

## Connections

- App root → Landing pages: hosts · The global app shell serves the public marketing pages.
- App root → Login page: hosts · The global app shell serves authentication pages.
- App root → Builder page: hosts · The global app shell serves the builder workspace route.
- Builder page → Builder client: mounts · The builder route delegates to the client orchestrator.
- Builder client → Builder panels: composes · The client workspace composes the interactive builder panels.
- Builder client → Preview UI: drives · Workspace state feeds the preview-facing UI.
- Builder client → Tuning core: applies · Workspace edits flow through the tuning pipeline.
- Builder client → Component library: seeds · Library templates can influence the generated component.
- Builder client → Generate API: requests · The builder sends generation requests to the server route.
- Builder client → Export API: exports · The builder invokes export through the server route.
- Generate API → Watsonx client: calls · Generation requests are forwarded to the watsonx boundary.
- Watsonx client → Prompt contract: uses · The AI client depends on the prompt and parsing contract.
- Generate API → Code builder: assembles · Generated structured output is turned into code.
- Code builder → Exporters: feeds · Code generation output is reused by export adapters.
- Export API → Exporters: dispatches · The export route selects the appropriate output format.
- Preview UI → Preview core: uses · The visible preview layer sits on top of the preview engine.
- Preview core → Tuning core: reflects · Preview state is updated as tuning changes the component model.
- Tuning core → Code builder: shapes · Tuning transformations alter the model before code assembly.
- Component library → Prompt contract: influences · Library concepts inform prompt and generation structure.
- Client hooks → Builder client: supports · Client hooks provide shortcuts, preview control, and responsiveness.
- UI primitives → Builder panels: supports · Reusable UI primitives underpin the builder interface.
- Product config → Landing pages: configures · Marketing pages use shared site and pricing content.
- Product config → Generate API: configures · Server generation behavior uses shared watsonx settings.
- Product config → Export API: configures · Export presentation and modal theme are driven by shared config.
- Core tests → Code builder: covers · Tests exercise core code assembly behavior.
- Core tests → Preview core: covers · Tests exercise preview state and bridging behavior.
- Core tests → Tuning core: covers · Tests exercise tuning and merge utilities.
- Core tests → Prompt contract: covers · Tests exercise prompt parsing and watsonx client behavior.
