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>

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 run dev            # Development mode
-   npm run dev-with-css   # Development with CSS watching
+   npm start              # Production mode (builds everything)
+   npm run dev:ts         # TypeScript development mode
+   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`
-- **Build CSS (dev mode):** `npm run build-css:dev` 
-- **Watch CSS changes:** `npm run watch-css`
-- **Dev with CSS watching:** `npm run dev-with-css`
+**Backend (TypeScript → Node.js):**
+```bash
+npm run build:ts        # Compile TypeScript backend
+npm run dev:ts          # TypeScript development with auto-reload
+```
 
-SCSS files are organized in `src/scss/`:
-- `main.scss` - Main entry point
-- `_variables.scss` - Theme variables and colors
-- `_mixins.scss` - Reusable SCSS mixins
-- `pages/` - Page-specific styles
-- `components/` - Component-specific styles
+**Frontend (TypeScript → Browser JavaScript):**
+```bash
+npm run build:frontend  # Compile frontend TypeScript with esbuild
+npm run watch:frontend  # Watch frontend TypeScript for changes
+```
+
+**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:**