How neracu/nullrift_ui works
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: builder-client.tsx Builder client · code-builder.test.ts Core tests · route.ts Generate API · code-builder.ts Code builder
Components 20
App surfaces
Marketing, auth, pricing, and the builder workspace routes.
- App root · Global app layout, styling, and shared providers for the Next.js runtime.
src/app/layout.tsx - Landing pages · Homepage and pricing entry points for the public site experience.
src/app/page.tsx - Login page · Authentication-facing page and signup/login surface.
src/app/login/page.tsx - Builder page · 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 · Client-side state and coordination for generation, preview, tuning, and export.
src/app/builder/builder-client.tsx - Builder panels · Prompt, controls, preview, code, and export components composing the workspace.
src/components/builder/prompt-input.tsx - Component library · 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 · Server endpoint for component generation requests.
src/app/api/generate/route.ts - Watsonx client · HTTP boundary to IBM watsonx.ai and token handling.
src/lib/watsonx/client.ts - Prompt contract · Prompt templates, parsing, and types for model requests and responses.
src/lib/watsonx/prompts.ts - Code builder · 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 · Iframe bridge, renderer, and state manager for safe interactive preview.
src/lib/preview/index.ts - Preview UI · 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 · 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 · Server endpoint for exporting generated output.
src/app/api/export/route.ts - Exporters · 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 · Reusable component primitives and shared visual building blocks.
src/components/ui/button.tsx - Client hooks · Shared hooks for preview, tuning, keyboard shortcuts, and responsive behavior.
src/hooks/use-preview.ts - Product 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 · Coverage for generation, preview state, tuning logic, and watsonx integration seams.
tests/unit/generator/code-builder.test.ts
Connections 28
- 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.