Update documentation for TypeScript frontend build system

- README.md: Add comprehensive build system section explaining TypeScript backend/frontend compilation, esbuild usage, and development commands
- CLAUDE.md: Update architecture documentation to reflect TypeScript frontend with shared components and esbuild compilation
- scripts/deploy.sh: Update deployment instructions to use new unified build command

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -9,14 +9,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Install dependencies
 npm install
 
-# Start the server (production mode - TypeScript)
+# Start the server (production mode - builds everything)
 npm start
 
 # Development mode options:
-npm run dev           # TypeScript development with auto-reload
+npm run dev:ts        # TypeScript backend development with auto-reload
 npm run dev:js        # Legacy JavaScript development mode
-npm run dev-with-css:ts  # TypeScript + CSS watching (recommended)
+npm run dev-with-css:ts  # TypeScript backend + CSS watching
-npm run dev-with-css     # Legacy JS + CSS watching
+npm run dev:full      # Full development: TypeScript backend + frontend + CSS (recommended)
+npm run dev-with-css  # Legacy JS + CSS watching
 ```
 
 The application runs on port 3000 by default. Visit http://localhost:3000 to view the website.
@@ -33,18 +34,32 @@ The documentation includes:
 - Interactive testing interface
 
 ### TypeScript Development
-The backend is written in TypeScript and compiles to `dist/` directory.
+Both backend and frontend are written in TypeScript.
-```bash
-# Build TypeScript (production)
-npm run build:ts
 
-# Build everything (TypeScript + CSS)
+**Backend TypeScript (Node.js):**
-npm run build
+```bash
+# Build backend TypeScript to dist/ directory
+npm run build:ts
 
 # Development with TypeScript watching
 npm run dev:ts
 ```
 
+**Frontend TypeScript (Browser):**
+```bash
+# Build frontend TypeScript to public/dist/ directory
+npm run build:frontend
+
+# Watch frontend TypeScript for changes
+npm run watch:frontend
+```
+
+**Full Build:**
+```bash
+# Build everything (backend + frontend + CSS + i18n)
+npm run build
+```
+
 ### CSS Development
 CSS is generated from SCSS and should NOT be committed to git.
 ```bash
@@ -58,6 +73,11 @@ npm run build-css:dev
 npm run watch-css
 ```
 
+**Generated Files (DO NOT COMMIT):**
+- `public/style.css` - Compiled CSS from SCSS
+- `public/dist/` - Compiled frontend JavaScript from TypeScript
+- `dist/` - Compiled backend JavaScript from TypeScript
+
 ### Code Quality
 ```bash
 # Run ESLint to check code style and quality
@@ -122,6 +142,7 @@ Required environment variables:
   - Bearer token authentication for admin endpoints
   - Environment variable configuration via dotenv
   - Full TypeScript with strict type checking
+  - Compiled output in `dist/` directory
 
 ### Route Architecture
 Routes are organized as factory functions accepting dependencies with full TypeScript typing:
@@ -156,8 +177,8 @@ CREATE TABLE locations (
 **Profanity Database (`profanity.db`)**:
 Managed by the `ProfanityFilter` class for content moderation.
 
-### Frontend (Progressive Web App + Progressive Enhancement)
+### Frontend (TypeScript + Progressive Web App)
-The application is a full Progressive Web App with offline capabilities and progressive enhancement:
+The application is a full Progressive Web App with TypeScript-compiled JavaScript:
 
 **PWA Features:**
 - **public/manifest.json**: Web app manifest for installation
@@ -166,16 +187,23 @@ The application is a full Progressive Web App with offline capabilities and prog
 - **public/offline.html**: Offline fallback page when network is unavailable
 - **PWA Meta Tags**: Added to all HTML files for proper app behavior
 
-**JavaScript-Enhanced Experience:**
+**TypeScript Frontend Architecture:**
-- **public/app.js**: Main implementation using Leaflet.js
+- **src/frontend/**: TypeScript frontend source code
-  - Auto-detects available geocoding services (Mapbox preferred, Nominatim fallback)
+  - **main.ts**: Main application entry point with Leaflet.js
-  - Interactive map with real-time updates
+  - **admin.ts**: Admin panel functionality
-  - Autocomplete and form validation
+  - **privacy.ts**: Privacy policy page
-  
+  - **shared/**: Shared components and utilities
-- **public/app-mapbox.js**: Mapbox GL JS implementation for enhanced features
+    - **header.ts**: Shared header component with i18n
-- **public/app-google.js**: Google Maps implementation (alternative)
+    - **footer.ts**: Shared footer component
-- **public/admin.js**: Admin panel functionality
+- **public/dist/**: Compiled JavaScript output (via esbuild)
-- **public/utils.js**: Shared utilities across implementations
+  - **app-main.js**: Main application bundle
+  - **app-admin.js**: Admin panel bundle
+  - **app-privacy.js**: Privacy page bundle
+
+**Legacy JavaScript (for reference):**
+- **public/app.js**: Legacy main implementation
+- **public/admin.js**: Legacy admin functionality
+- **public/utils.js**: Legacy shared utilities
 
 **Non-JavaScript Fallback:**
 - **Server-side /table route**: Complete HTML table view of all locations
@@ -238,11 +266,13 @@ SCSS files are in `src/scss/`:
 5. **Modular Route Architecture**: Routes accept dependencies as parameters for testability
 6. **Dual Database Design**: Separate databases for application data and content moderation
 7. **Type-Safe Database Operations**: All database interactions use typed models
-8. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios
+8. **Frontend TypeScript Compilation**: Modern esbuild-based frontend bundling with TypeScript
-9. **Graceful Degradation**: Fallback geocoding providers and error handling
+9. **Shared Component Architecture**: Reusable TypeScript components across pages
-10. **Automated Maintenance**: Cron-based cleanup of expired reports
+10. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios
-11. **Accessibility-First**: noscript fallbacks and server-side static map generation
+11. **Graceful Degradation**: Fallback geocoding providers and error handling
-12. **Offline-First Design**: Service worker caching with automatic updates
+12. **Automated Maintenance**: Cron-based cleanup of expired reports
+13. **Accessibility-First**: noscript fallbacks and server-side static map generation
+14. **Offline-First Design**: Service worker caching with automatic updates
 
 ### Deployment
 - Automated deployment script for Debian 12 (ARM64/x86_64) in `scripts/deploy.sh`

README.md

@@ -46,9 +46,10 @@ A community-driven web application for tracking winter road conditions and icy h
 
 4. **Start the server:**
    ```bash
-   npm start              # Production mode
+   npm start              # Production mode (builds everything)
-   npm run dev            # Development mode
+   npm run dev:ts         # TypeScript development mode
-   npm run dev-with-css   # Development with CSS watching
+   npm run dev-with-css:ts # TypeScript + CSS watching (recommended)
+   npm run dev:full       # Full development (TypeScript + frontend + CSS)
    ```
 
 ## Development Commands
@@ -76,21 +77,44 @@ npm run test:coverage
    http://localhost:3000
    ```
 
-### CSS Development
+### Build System
 
-This project uses SCSS for styling. The CSS is **generated** and should not be committed to git.
+This project uses TypeScript for both backend and frontend code, with SCSS for styling.
 
-- **Build CSS once:** `npm run build-css`
+**Backend (TypeScript → Node.js):**
-- **Build CSS (dev mode):** `npm run build-css:dev` 
+```bash
-- **Watch CSS changes:** `npm run watch-css`
+npm run build:ts        # Compile TypeScript backend
-- **Dev with CSS watching:** `npm run dev-with-css`
+npm run dev:ts          # TypeScript development with auto-reload
+```
 
-SCSS files are organized in `src/scss/`:
+**Frontend (TypeScript → Browser JavaScript):**
-- `main.scss` - Main entry point
+```bash
-- `_variables.scss` - Theme variables and colors
+npm run build:frontend  # Compile frontend TypeScript with esbuild
-- `_mixins.scss` - Reusable SCSS mixins
+npm run watch:frontend  # Watch frontend TypeScript for changes
-- `pages/` - Page-specific styles
+```
-- `components/` - Component-specific styles
+
+**CSS (SCSS → CSS):**
+```bash
+npm run build-css       # Build CSS once (production)
+npm run build-css:dev   # Build CSS with source maps
+npm run watch-css       # Watch SCSS files for changes
+```
+
+**Development Commands:**
+```bash
+npm run dev:full        # Watch all: TypeScript backend + frontend + CSS
+npm run dev-with-css:ts # Watch TypeScript backend + CSS
+npm run build           # Build everything for production
+```
+
+**File Organization:**
+- `src/` - TypeScript backend code
+- `src/frontend/` - TypeScript frontend code (compiled to `public/dist/`)
+- `src/scss/` - SCSS stylesheets (compiled to `public/style.css`)
+- `dist/` - Compiled backend JavaScript
+- `public/dist/` - Compiled frontend JavaScript
+
+**Note:** Generated files (`dist/`, `public/dist/`, `public/style.css`) should not be committed to git.
 
 ## Environment Variables
 
@@ -159,7 +183,7 @@ See `docs/deployment-quickstart.md` for a simplified deployment guide.
    cd /opt/icewatch
    sudo chown -R $USER:$USER /opt/icewatch
    npm install  # This automatically builds CSS via postinstall
-   npm run build:ts  # Compile TypeScript to JavaScript
+   npm run build  # Build everything: TypeScript backend + frontend + CSS
    ```
 
 3. **Configure environment:**

scripts/deploy.sh

@@ -180,7 +180,7 @@ fi
 echo "3. Set up the application:"
 echo "   cd /opt/icewatch"
 echo "   npm install"
-echo "   npm run build  # Compile TypeScript and build CSS"
+echo "   npm run build  # Build everything: TypeScript backend + frontend + CSS + i18n"
 echo "   cp .env.example .env"
 echo "   nano .env  # Add your MapBox token and admin password"
 echo ""