Cursor for Architecture MVP

A 3D web application for architectural design using natural language commands with real-time daylight simulation and AI-powered command parsing.

🏗️ Architecture

This is a monorepo project with three main components:

ycwinter2026/
├── frontend/          # React + Vite + Tailwind + Three.js
├── backend/           # FastAPI + OpenAI API
├── shared/            # Shared types and schemas
├── README.md          # This file
└── NOTES.md           # Detailed development notes

🚀 Tech Stack

Frontend

• React - UI framework
• Vite - Build tool and dev server
• Tailwind CSS - Utility-first styling
• Three.js - 3D rendering
• @react-three/fiber - React renderer for Three.js
• @react-three/drei - Useful helpers for React Three Fiber

Backend

• FastAPI - Modern Python web framework
• OpenAI API - Natural language processing
• Pydantic - Data validation
• Uvicorn - ASGI server

Shared

• TypeScript types - Type definitions for frontend
• Pydantic schemas - Data schemas for backend

🎯 Features

Core Features

• 3D Building Visualization - Interactive architectural models
• Natural Language Commands - Type or speak to modify buildings
• AI-Powered Parsing - OpenAI integration for intelligent command understanding
• Voice Input - Web Speech API support
• Real-time Daylight Analysis - Dynamic sun positioning and shadow simulation
• Building Modifications - Extend/shorten walls, add windows, change height

Block Editing System (NEW! 🎉)

• Drag and Drop - Drag blocks from palette into 3D scene
• Direct Manipulation - Move, rotate, and scale with transform controls
• Intelligent Selection - Click to select, Shift+click for multi-select
• Property Editing - Real-time property panel for selected blocks
• Alignment Tools - Align and distribute blocks automatically
• Grid Snapping - Configurable grid for precise placement (default 0.5m)
• AI Layout Assistant - Optimize alignment and spacing with AI
• Full Undo/Redo - 50-step history for all block operations
• Keyboard Shortcuts - Professional workflow with hotkeys

3D Compass & Navigation

• Live Orientation Display - Always-visible compass in top-right corner
• Cardinal Directions - Color-coded arrows (N=red, E=yellow, S=blue, W=green)
• Click-to-Face - Click any direction to smoothly rotate camera
• Spatial Commands - Use directions in commands: "extend north wall 2 meters"
• Real-time Sync - Compass rotates with camera for accurate orientation

🛠️ Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.9+
• OpenAI API key

Automated Setup (Recommended)

./setup.sh

This will:

• Set up Python virtual environment
• Install all dependencies (backend and frontend)
• Create .env template

Then:

1. Add your OpenAI API key to backend/.env
2. Start backend: cd backend && source venv/bin/activate && uvicorn main:app --reload
3. Start frontend: cd frontend && npm run dev

Manual Setup

1. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp env.example .env
# Edit .env and add your OPENAI_API_KEY
uvicorn main:app --reload

Backend runs at: http://localhost:8000

2. Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs at: http://localhost:5173

💬 Example Commands

Try these commands in the application:

• "extend east wall by 3 meters"
• "shorten north wall by 1 meter"
• "add window to south wall"
• "set building height to 4 meters"
• "move sun to afternoon"

Using the 3D Compass

The compass in the top-right corner helps you understand orientation:

1. Navigate: Click N, E, S, or W to smoothly rotate the camera to face that direction
2. Orient: Watch the compass rotate as you move the camera to always know which way you're facing
3. Command spatially: Use cardinal directions in commands (e.g., "extend north wall by 2 meters")
4. Quick reference: Color-coded arrows (North=red, East=yellow, South=blue, West=green)

📁 Project Structure

/frontend

• React-based UI with Three.js integration
• Command input (text and voice)
• 3D scene visualization
• Real-time building updates

/backend

• FastAPI REST API
• OpenAI GPT-4 integration for command parsing
• Daylight analysis algorithms
• Building state management

/shared

• /types - TypeScript type definitions
  • building.ts - Building model types
  • commands.ts - Command action types
  • daylight.ts - Daylight analysis types
• /schemas - Python Pydantic schemas
  • api.py - API request/response models

🔧 Development

Running Both Services

Terminal 1 (Backend):

cd backend && uvicorn main:app --reload

Terminal 2 (Frontend):

cd frontend && npm run dev

Building for Production

Frontend:

cd frontend && npm run build

The frontend dev server proxies /api requests to the backend automatically.

📝 Configuration

• Frontend: Configure in frontend/vite.config.js
• Backend: Configure in backend/main.py (CORS, etc.)
• Tailwind: Configure in frontend/tailwind.config.js

🤝 API Integration

The frontend communicates with the backend via REST API:

• Command parsing: POST /api/parse-command
• Daylight analysis: POST /api/analyze-daylight

See backend/main.py for full API documentation.

🧱 Block Editing Usage Guide

Getting Started with Blocks

The block editing system allows you to directly manipulate architectural elements in 3D. Here's how to use it:

1. Adding Blocks

From Palette:

1. Look for the 🧱 Blocks section in the right sidebar
2. Choose from: Wall, Window, Door, Column, Text Label, or Guide Line
3. Drag the block type onto the 3D canvas
4. The block will snap to the grid automatically

Grid Snapping:

• Default grid size: 0.5 meters
• Toggle with the 📐 Snap button or press G
• Helps maintain alignment and proportions

2. Selecting Blocks

• Click a block to select it (blue outline appears)
• Shift+Click to add to selection (multi-select)
• Escape to clear selection
• Click empty space to deselect all

3. Transform Controls

Once a block is selected, use transform controls to modify it:

Keyboard Shortcuts:

Key	Mode	What it does
W	Translate	Move block in 3D space
E	Rotate	Rotate around center point
R	Scale	Resize uniformly or per-axis

Mouse Controls:

• Drag colored arrows/rings/handles to transform
• Hold Shift while dragging for fine control
• Transform controls appear on the selected block

4. Editing Properties

When blocks are selected, a ⚙️ Properties panel appears below the palette:

Single Selection:

• Edit dimensions (length, width, height)
• Change colors
• Modify type-specific properties
• Lock/unlock blocks

Multi-Selection:

• Use alignment buttons:
  • Align Left - Stack on left edge
  • Align Right - Stack on right edge
  • Align Center - Center all blocks
  • Distribute H - Equal horizontal spacing
  • Distribute V - Equal vertical spacing

5. AI Layout Assistant

Use AI to automatically optimize block placement:

Quick Actions (at bottom of screen):

• ✨ Align selected - AI determines best alignment
• ✨ Distribute evenly - AI creates equal spacing
• ✨ Snap to grid - AI snaps to nearest grid points

How it works:

1. Select the blocks you want to optimize
2. Click an AI quick action button
3. AI analyzes the layout and returns changes
4. Changes are applied automatically
5. Use Ctrl+Z to undo if needed

6. Keyboard Shortcuts Reference

Shortcut	Action
Delete or Backspace	Delete selected blocks
Ctrl+D (Cmd+D on Mac)	Duplicate selected blocks
G	Toggle grid snap on/off
W	Switch to translate mode
E	Switch to rotate mode
R	Switch to scale mode
Escape	Clear selection
Ctrl+Z	Undo last action
Ctrl+Y	Redo action

7. Block Types and Properties

Wall:

• Length: 1-20 meters
• Height: 2-10 meters
• Thickness: 0.1-0.5 meters
• Use for: Exterior walls, partitions

Window:

• Width: 0.6-3 meters
• Height: 0.6-2.5 meters
• Sill Height: 0.5-1.5 meters
• Use for: Natural light, views

Door:

• Width: 0.7-1.5 meters
• Height: 2-2.4 meters
• Use for: Entries, passages

Column:

• Radius: 0.1-1 meter
• Height: 2-10 meters
• Use for: Structural support

Text Label:

• Content: Any text
• Font Size: 0.2-2 units
• Use for: Annotations, labels

Guide Line:

• Length: 1-50 meters
• Type: Horizontal or Vertical
• Use for: Alignment guides

8. Workflows

Creating a Simple Room:

1. Drag 4 Wall blocks to form a rectangle
2. Use Align tools to ensure walls connect
3. Add Window blocks to walls for light
4. Add a Door block for entry
5. Use AI Align to perfect alignment

Repeating Elements:

1. Create one element (e.g., column)
2. Select and press Ctrl+D to duplicate
3. Move duplicate to new position
4. Repeat as needed
5. Select all copies
6. Use Distribute H or Distribute V for equal spacing

Precision Work:

1. Toggle Snap ON for grid alignment
2. Use W mode and arrow keys for precise movement
3. Edit exact dimensions in Properties panel
4. Use AI Snap to Grid to fix minor misalignments

9. Tips and Best Practices

• Start with grid snap ON for aligned layouts
• Use Shift+Click to select multiple blocks before alignment
• Duplicate (Ctrl+D) is faster than dragging new blocks
• Lock blocks in Properties to prevent accidental changes
• Use guides to mark important alignments
• AI actions are faster than manual alignment
• Undo (Ctrl+Z) works for all operations
• Save often - blocks persist in browser storage

10. Troubleshooting

Block won't select:

• Make sure you're clicking the block, not empty space
• Check if block is locked in Properties

Transform not working:

• Press W, E, or R to activate transform mode
• Make sure exactly one block is selected

AI actions doing nothing:

• Select at least 2 blocks before using align/distribute
• Check that OpenAI API key is configured in backend

Grid snap not working:

• Press G to toggle, check if button shows "Snap: ON"
• Grid only affects translation, not rotation/scale

📖 Documentation

For detailed development notes, architectural decisions, and implementation details, see NOTES.md.

🔐 Environment Variables

Backend (.env)

OPENAI_API_KEY=your_key_here

🎨 UI/UX

• Modern dark theme
• Responsive design
• Real-time feedback
• Intuitive controls
• Keyboard shortcuts (Enter to submit)
• Voice input button

🧪 Testing

(To be implemented)

📄 License

(To be added)