FloorPlanner - Standalone React Application

A professional floor planning application with floating panels, 3D visualization, and collaboration features.

Features

• 🏗️ Intuitive Drag & Drop Interface - One-click wall placement with automatic alignment
• 🎨 Real-time 3D Visualization - Instant 2D-to-3D sync without rendering delays
• 🎯 Floating Panel System - Repositionable, resizable panels with shadcn UI
• 🤝 Real-time Collaboration - Multi-user editing with shared cursors
• 📐 Automated Measurements - Auto-calculated dimensions and clearance validation
• 📤 Advanced Export - 8K renders, PDFs, and virtual walkthroughs
• 📱 Mobile Optimized - Touch controls and responsive design
• 🔧 CAD Import - Support for DXF, DWG, IFC, and Revit formats

Quick Start

Prerequisites

• Node.js 18+
• npm or pnpm

Installation

# Clone the repository
git clone <repository-url>
cd floorplanner/frontend

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start development server
npm run dev:standalone

The application will be available at http://localhost:5173

Development Scripts

# Development
npm run dev:standalone          # Start standalone development server
npm run dev                     # Start with Django integration

# Building
npm run build:standalone        # Build for standalone deployment
npm run build:django           # Build for Django integration
npm run build                  # Default build

# Testing & Quality
npm run test                   # Run tests
npm run test:watch            # Run tests in watch mode
npm run lint                  # Check code quality
npm run lint:fix             # Fix linting issues
npm run type-check           # TypeScript type checking

# Utilities
npm run preview:standalone    # Preview standalone build
npm run clean                # Clean build directories

Build & Debug Workflows

• Standalone Build: npm run build:standalone (outputs to dist/)
• Django Build: npm run build:django (outputs to ../static/floorplanner/js)
• Preview: npm run preview:standalone (serves production build)
• Bundle Analysis: After build, open dist/bundle-analysis.html for bundle stats
• PWA: Manifest and service worker are auto-injected; see public/manifest.json and public/sw.js
• Production Optimizations: Minification, code splitting, and tree-shaking are enabled by default
• Hot Module Replacement: Enabled in development mode

Configuration

The application uses environment variables for configuration. Copy .env.example to .env and customize:

# Application
VITE_APP_TITLE=FloorPlanner
VITE_APP_VERSION=1.0.0

# API Configuration
VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_URL=ws://localhost:3001/ws

# Authentication
VITE_ENABLE_AUTH=false
VITE_AUTH_PROVIDER=local

# Features
VITE_ENABLE_COLLABORATION=true
VITE_ENABLE_3D_VIEW=true
VITE_ENABLE_EXPORT=true
VITE_ENABLE_CAD_IMPORT=true

# Storage
VITE_STORAGE_TYPE=localStorage
VITE_AUTO_SAVE_INTERVAL=30000

# Development
VITE_DEBUG_MODE=true
VITE_MOCK_API=true

Environment Variables

The following environment variables are used for configuration. Set these in your .env file:

Variable	Description	Example Value
VITE_APP_TITLE	Application title	FloorPlanner
VITE_APP_VERSION	Application version	1.0.0
VITE_API_BASE_URL	API base URL	http://localhost:3001/api
VITE_WS_URL	WebSocket URL	ws://localhost:3001/ws
VITE_ENABLE_AUTH	Enable authentication (true/false)	false
VITE_AUTH_PROVIDER	Auth provider (local, firebase, auth0)	local
VITE_ENABLE_COLLABORATION	Enable real-time collaboration	true
VITE_ENABLE_3D_VIEW	Enable 3D view	true
VITE_ENABLE_EXPORT	Enable export features	true
VITE_ENABLE_CAD_IMPORT	Enable CAD import	true
VITE_STORAGE_TYPE	Storage type (localStorage, indexedDB)	localStorage
VITE_AUTO_SAVE_INTERVAL	Auto-save interval (ms)	30000
VITE_DEBUG_MODE	Enable debug mode	true
VITE_MOCK_API	Use mock API (true/false)	true

Architecture

Core Technologies

• React 19 - UI framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Tailwind CSS - Styling
• shadcn/ui - UI components
• Zustand - State management
• Konva.js - 2D canvas rendering
• Three.js - 3D visualization
• React Three Fiber - React Three.js integration

Project Structure

src/
├── components/           # React components
│   ├── panels/          # Floating panel components
│   ├── ui/              # shadcn UI components
│   └── ...
├── config/              # Configuration management
├── hooks/               # Custom React hooks
├── services/            # API and external services
├── stores/              # Zustand state stores
├── types/               # TypeScript type definitions
└── utils/               # Utility functions

Floating Panel System

The application features a sophisticated floating panel system with:

• Draggable & Resizable Panels - Move and resize panels anywhere on screen
• State Persistence - Panel positions saved between sessions
• Keyboard Shortcuts - Quick panel operations
• Mobile Responsive - Adaptive layouts for different screen sizes
• Accessibility - Full keyboard navigation and screen reader support

Deployment

Standalone Deployment

1. Build the application:

npm run build:standalone

2. Deploy the dist folder to your web server or CDN

3. Configure your web server to serve index.html for all routes (SPA routing)

Docker Deployment

FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build:standalone

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Vercel/Netlify Deployment

The application is ready for deployment on modern hosting platforms:

• Vercel: Connect your repository and deploy automatically
• Netlify: Drag and drop the dist folder or connect via Git

API Integration

Mock API (Default)

The application includes a mock API service for standalone operation:

• Local Storage - Data persisted in browser
• Simulated Network Delays - Realistic API behavior
• Sample Data - Pre-loaded floor plans and projects

Custom Backend Integration

To integrate with your own backend:

1. Set VITE_MOCK_API=false in .env
2. Update API endpoints in src/config/app.config.ts
3. Implement authentication if needed
4. Update WebSocket configuration for real-time features

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Performance

• Code Splitting - Automatic chunk splitting for optimal loading
• Tree Shaking - Unused code elimination
• Asset Optimization - Compressed images and fonts
• Service Worker - Offline support and caching

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

This project is licensed under the ISC License - see the LICENSE file for details.

Support

For support and questions:

• 📧 Email: support@floorplanner.com
• 📖 Documentation: docs.floorplanner.com
• 🐛 Issues: GitHub Issues

Testing Workflow (2025)

Unit & Integration Tests (Vitest)

• Run all tests: npm run test
• Watch mode UI: npm run test:watch
• Coverage: vitest run --coverage
• Test files: src/components/__tests__/**/*.test.{ts,tsx,js,jsx}

End-to-End (E2E) Tests (Playwright)

• Start dev server: npm run dev:standalone
• Run E2E tests: npx playwright test
• E2E test files: src/e2e/*.spec.ts
• Playwright config: playwright.config.ts

Migration Notes

• Jest and related dependencies have been removed.
• All unit/integration tests should use Vitest syntax (describe, it, expect from vitest).
• E2E tests use Playwright and require the app to be running locally.
• See vitest.config.ts and playwright.config.ts for configuration details.

Troubleshooting

• If tests are not discovered, check file extensions and config include patterns.
• For E2E, ensure the dev server is running before executing Playwright tests.
• For new tests, prefer Vitest for logic/components, Playwright for user flows.