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     # Legacy JS + CSS watching
+npm run dev-with-css:ts  # TypeScript backend + 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.
-```bash
-# Build TypeScript (production)
-npm run build:ts
+Both backend and frontend are written in TypeScript.
 
-# Build everything (TypeScript + CSS)
-npm run build
+**Backend TypeScript (Node.js):**
+```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)
-The application is a full Progressive Web App with offline capabilities and progressive enhancement:
+### Frontend (TypeScript + Progressive Web App)
+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:**
-- **public/app.js**: Main implementation using Leaflet.js
-  - Auto-detects available geocoding services (Mapbox preferred, Nominatim fallback)
-  - Interactive map with real-time updates
-  - Autocomplete and form validation
-  
-- **public/app-mapbox.js**: Mapbox GL JS implementation for enhanced features
-- **public/app-google.js**: Google Maps implementation (alternative)
-- **public/admin.js**: Admin panel functionality
-- **public/utils.js**: Shared utilities across implementations
+**TypeScript Frontend Architecture:**
+- **src/frontend/**: TypeScript frontend source code
+  - **main.ts**: Main application entry point with Leaflet.js
+  - **admin.ts**: Admin panel functionality
+  - **privacy.ts**: Privacy policy page
+  - **shared/**: Shared components and utilities
+    - **header.ts**: Shared header component with i18n
+    - **footer.ts**: Shared footer component
+- **public/dist/**: Compiled JavaScript output (via esbuild)
+  - **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
-9. **Graceful Degradation**: Fallback geocoding providers and error handling
-10. **Automated Maintenance**: Cron-based cleanup of expired reports
-11. **Accessibility-First**: noscript fallbacks and server-side static map generation
-12. **Offline-First Design**: Service worker caching with automatic updates
+8. **Frontend TypeScript Compilation**: Modern esbuild-based frontend bundling with TypeScript
+9. **Shared Component Architecture**: Reusable TypeScript components across pages
+10. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios
+11. **Graceful Degradation**: Fallback geocoding providers and error handling
+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`