🏠 AI house map planner

Proportional residential 2D floor plan generation with structural staircase vertical locking and Vastu Shastra orientation rules.

Figure 1: Main layout generator screen showing custom plot inputs, design engine switches, interactive canvas, Vastu indicators, and multi-floor planning option.

---

Table of contents

• Project overview
• Live demo and visuals
• Tech stack and choices
• Core features
• Architecture and project structure
• State management and data flow
• API reference
• Local installation and setup
• Configuration and customization
• Known limitations and troubleshooting
• Security and privacy notes
• Future roadmap
• Contributing
• License

---

Project overview

AI house map planner is a web-based layout drafting tool designed for individual plot owners to visualize proportional residential floor plans. The application maps custom plot widths and depths in feet alongside orientation directions, producing architectural drawings with door placements, window apertures, and scale indicators. It addresses the cost overhead and design friction of early-stage home building by enabling users to iterate on draft layouts that conform to traditional Vastu Shastra guidelines before hiring drafting professionals.

This application serves as an instant structural plan visualizer that accelerates early layout validation for homebuilders, mitigating architectural design iterations and overhead costs.

---

Live demo and visuals

This application runs locally. The main workspace displays a control panel on the left with dimension sliders and building presets, accompanied by a dynamic SVG canvas on the right that renders room layouts in real-time.

To run and see the application locally, execute the development command:

npm run dev

Then navigate to http://localhost:3000 in your web browser.

---

Tech stack and choices

---

Core features

Multi-floor layout generation ⭐

• What it does: Generates vertically-aligned multi-story blueprints (up to 3 levels) locking the staircase footprint.
• User experience: Users choose the number of stories via the settings panel, design the ground level, and swap tabs to lazily construct subsequent stories with locked staircase boundaries.

- Staircase coordinates are shared and remain fixed across all floors to maintain structural vertical alignment. - Floor transitions dynamically swap ground-level zones like parking and main kitchens for balconies and lounges on upper levels.

High-resolution SVG/PNG exporter ⭐

• What it does: Compiles client-side vector files and super-samples graphics onto a canvas context for PNG downloads.
• User experience: Users click the download toolbar buttons to retrieve scalable vector or high-resolution raster plan files.

- SVG export packages the canvas node into a standalone XML vector file containing styles. - PNG export draws elements onto an offscreen canvas at a 4x resolution scale factor, outputting sharp raster graphics.

Vastu Shastra layout alignment ⭐

• What it does: Applies traditional orientation guidelines to quadrant calculations for room and door offsets.
• User experience: Users enable the guidelines switch to prioritize positioning master bedrooms in the southwest and kitchens in the southeast, with a toggleable 3x3 overlay grid for verification.

- Vastu orientation coordinates align according to the cardinal direction facing the main access road. - Built-in grid overlay allows structural inspection of quadrant alignments in real time.

Adaptive room sizing & dropping ⭐

• What it does: Adjusts room footprint calculations dynamically based on plot dimensions. If total minimum required area exceeds 90% of usable plot area, it recursively drops rooms by priority (pooja → servant quarters → extra bathroom → bedroom 3 → parking → bedroom 2 → garden) before partitioning the layout tree.
• User experience: Standard dimension sliders automatically adapt, preventing invalid overlapping layout configurations on tight plots.

Proportional CAD rendering & dynamic labels ⭐

• What it does: Uses area-based scaling factor parameters (<80, <120, <180 sq ft) and a position clamp helper (clampedRect) to prevent furniture symbols from overlapping walls. Adapts text size dynamically and abbreviates labels (e.g. "MB", "WC", "K") in narrow room cells.
• User experience: Blueprint drawings look highly professional, clear, and clean on any monitor size or screen resolution.

Door & window geometry constraints

• What it does: Automatically computes door/window apertures. Places bedroom doors in the middle third only (avoiding headboards), kitchen doors away from counters, and bathroom doors on corridor/bedroom walls only.
• User experience: Door swing arcs automatically orient to rest flat against adjacent corners, and use SVG <clipPath> masks to avoid wall collisions. Tight layouts automatically fallback to dashed sliding indicators with "↔" text markers.

Strict validation pipeline

• What it does: Evaluates layout plans against a strict flat 0.3 ft sizing tolerance. Verifies Ground Floor corridor existence for plots > 600 sqft and returns validation failures if a bathroom door shares a wall directly with a kitchen or dining room.

---

Architecture and project structure

The application is structured as a client-server single-page Next.js web application. The React client captures plot parameters and forwards them via POST requests to the API route handler, which determines if layout generation should run locally via procedural math rule files or server-side via Gemini API calls, validating all coordinates before returning the payload.

.
├── .env.local                  # Local environment variables including Gemini API key
├── AGENTS.md                   # Instructions and rules for assistant engines
├── CLAUDE.md                   # Reference commands list
├── eslint.config.mjs           # Code linter rules configuration
├── next-env.d.ts               # Next.js TypeScript declarations
├── next.config.ts              # Next.js compilation settings
├── package.json                # Project dependencies and runner scripts
├── postcss.config.mjs          # CSS post-processing rules
├── README.md                   # Technical documentation and project walkthrough guide
├── tsconfig.json               # TypeScript compiler config
├── app/                        # Next.js App Router root directory
│   ├── favicon.ico             # Browser tab icon asset
│   ├── globals.css             # Base CSS styles and theme variables
│   ├── layout.tsx              # Root HTML layout container
│   ├── page.tsx                # Main application dashboard controller managing reactive floor states 🌟
│   └── api/                    # API route handlers
│       └── generate/           # Sizing route
│           └── route.ts        # Next.js POST handler calling Gemini or local generators and validating plans
├── components/                 # React user interface components
│   ├── FloorPlanCanvas.tsx     # Canvas rendering vector elements, Vastu grid lines, and download actions
│   └── InputForm.tsx           # Settings panel containing plot configuration sliders and presets
├── lib/                        # Math libraries and verification utilities
│   ├── generator.ts            # Procedural math layouts for ground and upper levels with staircase locks
│   ├── solver.ts               # Layout tree solver, staircase vertical lock, and door/window generator
│   ├── types.ts                # Shared TypeScript structures for PlotInputs, Room, Door, and FloorPlan
│   └── validator.ts            # Geometric room overlap and plot boundary constraint evaluator
└── public/                     # Static assets directory
    ├── aihouseplan.png         # Main application visual display screenshot
    ├── file.svg                # File logo indicator
    ├── globe.svg               # Web globe icon
    ├── next.svg                # Next.js logo
    ├── vercel.svg              # Vercel deployment logo
    └── window.svg              # Window logo indicator

---

State management and data flow

State management

State is centralized in the parent component app/page.tsx using React hooks. The application state stores inputs, floor plans, the current floor tab, loading states, and the locked engine type. This guarantees that coordinate updates immediately propagate to the canvas drawing interface.

• floors: An array containing up to three FloorPlan objects or null representing ground, first, and second floors.
• activeFloor: An integer index tracking the active layout level rendered on the canvas view.
• lockedEngine: A state lock storing "ai" or "procedural" once generation starts, preventing mismatching layout rules.

Data flow walkthrough — generating layout plans

1. The user selects plot dimensions and orientation inputs in components/InputForm.tsx and clicks the generation action button, calling handleSubmit.
2. handleSubmit triggers the callback prop onSubmit, forwarding a PlotInputs object to handleGenerate in app/page.tsx.
3. handleGenerate updates the isLoading state to true, clears the floors state array to [null, null, null], resets activeFloor to 0, and triggers a POST request to the server route /api/generate with the parameters and floor: 0.
4. The handler inside app/api/generate/route.ts parses the JSON payload.
5. If the request calls for the procedural engine or lacks a GEMINIAPIKEY environment variable, the handler invokes generateLocalLayout inside lib/generator.ts.
6. If the request calls for the AI engine, the handler initializes GoogleGenerativeAI, connects to the gemini-2.5-flash model, passes the system prompt configurations enforcing the schema, and extracts the generated JSON coordinates.
7. The coordinates are parsed and evaluated by validateFloorPlan in lib/validator.ts.
8. If validation fails, the handler falls back to procedural rules by calling generateLocalLayout. If it passes, it returns the generated JSON array.
9. handleGenerate updates the floors state array with the new floor coordinates, locks the generator engine state, and resets isLoading to false.
10. The updated floors state triggers a canvas redraw inside components/FloorPlanCanvas.tsx.

---

API reference

Generate layout plan

Generates coordinates for rooms, doors, and windows based on plot size, orientation, and engine requirements.

• Method: POST
• Endpoint: /api/generate
• Request headers: Content-Type: application/json
• Request body:

{
  "lengthFt": 30,
  "breadthFt": 40,
  "orientation": "North",
  "roadFacing": "North",
  "bedrooms": 2,
  "bathrooms": 2,
  "parking": true,
  "garden": false,
  "poojaRoom": true,
  "vastu": true,
  "style": "modern",
  "engine": "ai",
  "floors": 2,
  "familyType": "nuclear",
  "kitchenType": "closed",
  "servantQuarters": false,
  "floor": 0,
  "staircase": null
}

• Response body (200 OK):

{
  "success": true,
  "layout": {
    "floor": 0,
    "plotLength": 30,
    "plotBreadth": 40,
    "rooms": [
      { "id": "living", "label": "Living Room", "x": 1.5, "y": 1.5, "width": 14, "height": 16 },
      { "id": "kitchen", "label": "Kitchen", "x": 16, "y": 1.5, "width": 10, "height": 10 },
      { "id": "bedroom-master", "label": "Master Bedroom", "x": 1.5, "y": 18, "width": 12, "height": 12 },
      { "id": "staircase", "label": "Staircase", "x": 26, "y": 1.5, "width": 4, "height": 9 }
    ],
    "doors": [
      { "room": "living", "wall": "bottom", "position": 6, "width": 3 }
    ],
    "windows": [],
    "staircase": { "x": 26, "y": 1.5, "width": 4, "height": 9 },
    "explanation": "Modern open-style layouts with the kitchen in the Southeast corner."
  },
  "mode": "ai"
}

---

Local installation and setup

Prerequisites

• Node.js version 18.0.0 or higher
• npm version 9.0.0 or higher

Setup steps

1. Clone the project files:

   git clone https://github.com/itsrajaniket/aihouseplanner.git
   

1. Navigate to the project root directory:

   cd aihouseplanner
   

1. Install dependencies:

   npm install
   

1. Create a .env.local file inside the root folder:

   echo GEMINI_API_KEY=your_gemini_api_key_here > .env.local
   

Environment variables

For connection to the AI engine model endpoints, you must save your developer credentials:

GEMINI_API_KEY=your_gemini_api_key_here

Running in development

To execute the project in development mode:

npm run dev

Running in production

To build and run the optimized application bundle:

npm run build

npm run start

Verification

Open http://localhost:3000 in your web browser. You should see the user settings panel and canvas, showing the initial layout blueprint rendered.

---

Configuration and customization

Usable margin adjustments

To modify the outer setback margin surrounding the rooms, open lib/generator.ts and edit the setback S defined inside checkGeometry and generateLocalLayout (default is 0.5 ft for narrow plots <= 22 ft and 1.5 ft for wide plots):

const S = W <= 22 ? 0.5 : 1.5;

Minimum size bounds for rooms

To adjust baseline room sizing dimensions, edit the minimum width and height values in the getMinArea function inside lib/generator.ts and their validation counterparts inside validateFloorPlan in lib/validator.ts (e.g. Master Bedroom: 11x12 ft, Kitchen: 7x9 ft, Bathroom: 4x6 ft, Staircase: 3.5x8 ft).

SVG scale unit configurations

To alter the SVG canvas scaling factor, edit the constant inside components/FloorPlanCanvas.tsx:

// Change coordinates scale units calculation (default 20 SVG units = 1 foot)
const SC = 20;

---

Known limitations and troubleshooting

Known limitations

• Predefined set of rooms: The generator coordinates layout positions for fixed room identifiers (e.g. living, kitchen, bedroom-master, staircase) and does not support arbitrary custom labels.
• Staircase placement lock: While upper levels lock staircase coordinates vertically to prevent structure mismatches, the initial staircase placement on the ground level is set dynamically by the algorithm and cannot be dragged manually.
• Floating point rounding offsets: Snapping math rounding coordinates to 0.5 ft increments can shift room coordinates by up to 0.1 ft, occasionally triggering boundary validation alerts under AI engine layout models.
• Orthogonal 2D layout constraints: Layout outlines are limited to orthogonal 2D dimensions and do not calculate wall thickness, foundation structure beams, plumbing channels, or 3D elevations.

Common errors and solutions

---

Security and privacy notes

• Credential storage: The GEMINIAPIKEY is loaded from a local environment file .env.local and processed server-side in Next.js API route handlers. It is never exposed, logged, or sent to the client browser.
• Data storage & tracking: No user configuration inputs, plot sizes, or layout calculations are stored in databases. All configurations are handled in-memory and discarded upon closing the tab session. No analytics tracking code is active in the codebase.
• Third-party transmission: Generating layout coordinates via the AI engine sends plot boundaries, selected rooms, and style choices directly to Google Gemini API servers.
• API limits warning: Under heavy rate-limiting on Gemini developer API keys, the application automatically falls back to local rules-based procedural layouts (lib/generator.ts) to ensure the workspace remains responsive.

---

Future roadmap

• [x] Integrate multi-floor tabs supporting up to 3 stories with locked staircase coordinates
• [x] Implement client-side high-resolution PNG canvas exporter with super-sampling
• [x] Add visual Vastu grid guide lines overlay toggle in canvas workspace
• [ ] Add interactive drag-and-drop room sizing handlers directly on the canvas SVG element
• [ ] Create structural columns and plumbing stack layout recommendation markers
• [ ] Add a municipal FAR (Floor Area Ratio) compliance checking calculator panel
• [ ] Integrate 3D visualization model views utilizing Three.js or WebGL canvas renderers

---

Contributing

1. Fork the repository on GitHub.
2. Create your feature branch following the naming convention:

- For new features: feature/short-description - For bug fixes: fix/issue-name

1. Commit your changes with clear messages.
2. Submit a Pull Request to the main branch.

Contributions enhancing layout coordinate mathematical algorithms or Vastu compliance guidelines are welcome.

---

License

This project is private and proprietary. Users are permitted to run and modify the source code locally for personal planning and visualization purposes only. Distribution, hosting, or sale of the layout code is prohibited.