AI-assisted architectural visualizer that turns 2D floor plans into top‑down 3D renders using the Puter platform.

---

Preview / Screenshot 🖼️

---

What This Project Is 🧭

• A React Router (SSR) web app for uploading floor plans and generating photorealistic 3D top‑down renders.
• Uses Puter authentication, hosting, and KV storage to manage user projects and images.
• Calls Puter AI (txt2img) to generate the rendered view and presents a before/after comparison UI.

---

Tech Stack 🧰

Core Framework

• React 19
• React Router 7 (SSR)

UI / Rendering

• Tailwind CSS (via @tailwindcss/vite and app/app.css)
• react-compare-slider (before/after comparison)
• lucide-react (icons)

AI / ML

• Puter AI txt2img (provider: Gemini, model: gemini-2.5-flash-image-preview)

Infrastructure

• Puter JS SDK (@heyputer/puter.js) for auth, hosting, KV storage, filesystem, and worker calls

Tooling

• Vite
• TypeScript
• ESLint + Prettier

---

Architecture Overview 🧩

The app is rendered via React Router SSR and performs most data operations in the browser using the Puter SDK. Projects are saved through a Puter Worker API that stores metadata in Puter KV, while images are hosted in Puter Hosting/FS.

graph TD
  User[User] --> UI[React Router UI]
  UI --> Auth[Puter Auth]
  UI --> AI[Puter AI txt2img]
  UI --> Worker[Puter Worker API]
  UI --> Hosting[Puter Hosting/FS]
  Worker --> KV[Puter KV Storage]

---

Project Structure 🗂️

.
├─ app/
│  ├─ app.css
│  ├─ root.tsx
│  └─ routes/
├─ components/
├─ constants/
├─ lib/
│  ├─ ai.action.ts
│  ├─ puter.action.ts
│  ├─ puter.hosting.ts
│  └─ puter.worker.js
├─ utils/
├─ public/
├─ .env.example
├─ react-router.config.ts
├─ vite.config.ts
└─ package.json

• app/ React Router routes, layout, and global styles.
• components/ Reusable UI pieces (navbar, upload, buttons).
• constants/ App constants and the AI prompt.
• lib/ Puter integration, AI generation, and the worker script.
• utils/ Hosting helpers and image conversions.
• public/ Static assets.

---

Core Modules 🧱

app/root.tsx

Purpose: Global layout, app-wide auth state, and outlet context for routes. Interactions: Calls Puter auth helpers from lib/puter.action.ts and provides auth context to routes. Design decisions: Centralizes auth refresh and exposes signIn/signOut to all routes via outlet context.

app/routes/home.tsx

Purpose: Landing page, upload entry point, and project listing for signed-in users. Interactions: Uses Upload component and calls createProject + getProjects from lib/puter.action.ts. Design decisions: Creates a project immediately after upload and navigates to the visualizer route.

app/routes/visualizer.$id.tsx

Purpose: Project visualizer/editor view with AI generation and before/after comparison. Interactions: Fetches project data via getProjectById, triggers generate3DView, then saves via createProject. Design decisions: Auto-generates if no render exists and provides share/export actions on the client.

lib/ai.action.ts

Purpose: Generates 3D renders using Puter AI (txt2img). Interactions: Called from the visualizer route; uses the prompt from constants/index.ts. Design decisions: Normalizes source images to data URLs before sending to the AI provider.

lib/puter.action.ts

Purpose: Puter auth and project CRUD through the worker API. Interactions: Uses lib/puter.hosting.ts to host images and PUTER_WORKER_URL from constants/index.ts. Design decisions: Ensures images are hosted before saving project metadata.

lib/puter.worker.js

Purpose: Puter Worker API for saving and retrieving projects in Puter KV. Interactions: Invoked by lib/puter.action.ts via puter.workers.exec. Design decisions: Uses a project key prefix and returns JSON responses for list/get/save.

---

Runtime Flow 🔁

sequenceDiagram
  participant U as User
  participant UI as React Router UI
  participant PAuth as Puter Auth
  participant PAI as Puter AI
  participant PWorker as Puter Worker API
  participant PHost as Puter Hosting/FS
  participant PKV as Puter KV

  U->>UI: Upload floor plan
  UI->>PAuth: Sign in (if needed)
  UI->>PHost: Upload source image
  UI->>PWorker: Save project metadata
  PWorker->>PKV: Store project
  UI->>PAI: Generate 3D render
  UI->>PHost: Upload rendered image
  UI->>PWorker: Update project
  UI-->>U: Show before/after comparison

---

Setup & Installation ⚙️

Prerequisites:

• Node.js (LTS recommended)
• npm

Install dependencies:

npm install

---

Running the Project ▶️

Development:

npm run dev

Production build:

npm run build

Run the production server:

npm run start

Optional checks:

npm run lint
npm run typecheck

---

Configuration 🔐

Environment variables (see .env.example):

Variable	Description	Required
VITE_PUTER_WORKER_URL	URL of the deployed Puter Worker providing /api/projects/* endpoints	Yes

---

Usage ✍️

• Open the app and sign in with Puter.
• Upload a floor plan image (JPG/PNG).
• The app creates a project and opens the visualizer.
• The AI-generated render appears and can be compared against the original.
• Use export to download the render or share the project URL.

---

Limitations ⚠️

• Project history and persistence require a working VITE_PUTER_WORKER_URL.
• The app depends on Puter services (auth, hosting, KV, AI); offline use is not supported.
• AI generation failures are only surfaced in the console (no user-facing retry UI).

---

Future Improvements (Optional) 🔮

• Add user-facing error and retry flows for AI generation and uploads.
• Expose project visibility controls and sharing beyond the current URL flow.
• Add lightweight caching or thumbnails for faster project lists.

---

License 📄

MIT License. See .