Refactor architecture: Add models/services layer and refactor frontend
Major architectural improvements: - Created models/services layer for better separation of concerns - Location model with async methods for database operations - ProfanityWord model for content moderation - DatabaseService for centralized database management - ProfanityFilterService refactored to use models - Refactored frontend map implementations to share common code - MapBase class extracts 60-70% of duplicate functionality - Refactored implementations extend MapBase for specific features - Maintained unique geocoding capabilities per implementation - Updated server.js to use new service architecture - All routes now use async/await with models instead of raw queries - Enhanced error handling and maintainability 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Code
parent
6c90430ff6
commit
a0fffcf4f0
13 changed files with 2170 additions and 184 deletions
143
CLAUDE.md
Normal file
143
CLAUDE.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Running the Application
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start the server (production mode)
|
||||
npm start
|
||||
|
||||
# Start with auto-reload (development mode)
|
||||
npm run dev
|
||||
|
||||
# Development with CSS watching (recommended for frontend work)
|
||||
npm run dev-with-css
|
||||
```
|
||||
|
||||
The application runs on port 3000 by default. Visit http://localhost:3000 to view the website.
|
||||
|
||||
### CSS Development
|
||||
CSS is generated from SCSS and should NOT be committed to git.
|
||||
```bash
|
||||
# Build CSS once (compressed for production)
|
||||
npm run build-css
|
||||
|
||||
# Build CSS with source maps (for development)
|
||||
npm run build-css:dev
|
||||
|
||||
# Watch SCSS files and auto-compile changes
|
||||
npm run watch-css
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run all tests
|
||||
npm test
|
||||
|
||||
# Run tests with coverage report
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Environment Setup
|
||||
Before running the application, you must configure environment variables:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env to add your MapBox token and admin password
|
||||
```
|
||||
|
||||
Required environment variables:
|
||||
- `MAPBOX_ACCESS_TOKEN`: MapBox API token for geocoding (get free token at https://account.mapbox.com/access-tokens/)
|
||||
- `ADMIN_PASSWORD`: Password for admin panel access at /admin
|
||||
- `PORT`: Server port (default: 3000)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Backend (Node.js/Express)
|
||||
- **server.js**: Main Express server with modular route architecture
|
||||
- Uses two SQLite databases: `icewatch.db` (locations) and `profanity.db` (content moderation)
|
||||
- Automatic cleanup of reports older than 48 hours via node-cron
|
||||
- Bearer token authentication for admin endpoints
|
||||
- Environment variable configuration via dotenv
|
||||
|
||||
### Route Architecture
|
||||
Routes are organized as factory functions accepting dependencies:
|
||||
|
||||
- **routes/config.js**: Public API configuration endpoints
|
||||
- **routes/locations.js**: Location submission and retrieval with profanity filtering
|
||||
- **routes/admin.js**: Admin panel functionality with authentication middleware
|
||||
|
||||
### Database Schema
|
||||
**Main Database (`icewatch.db`)**:
|
||||
```sql
|
||||
CREATE TABLE locations (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
address TEXT NOT NULL,
|
||||
latitude REAL,
|
||||
longitude REAL,
|
||||
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
description TEXT,
|
||||
persistent INTEGER DEFAULT 0,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
**Profanity Database (`profanity.db`)**:
|
||||
Managed by the `ProfanityFilter` class for content moderation.
|
||||
|
||||
### Frontend (Vanilla JavaScript)
|
||||
Multiple map implementations for flexibility:
|
||||
|
||||
- **public/app.js**: Main implementation using Leaflet.js
|
||||
- Auto-detects available geocoding services (MapBox preferred, Nominatim fallback)
|
||||
|
||||
- **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
|
||||
- Location management (view, edit, delete)
|
||||
- Persistent location toggle
|
||||
- Profanity word management
|
||||
|
||||
- **public/utils.js**: Shared utilities across implementations
|
||||
|
||||
### API Endpoints
|
||||
|
||||
Public endpoints:
|
||||
- `GET /api/config`: Returns MapBox token for frontend geocoding
|
||||
- `GET /api/locations`: Active locations (< 48 hours old or persistent)
|
||||
- `POST /api/locations`: Submit new location report (with profanity filtering)
|
||||
|
||||
Admin endpoints (require Bearer token):
|
||||
- `POST /api/admin/login`: Authenticate and receive token
|
||||
- `GET /api/admin/locations`: All locations including expired
|
||||
- `PUT /api/admin/locations/:id`: Update location details
|
||||
- `PATCH /api/admin/locations/:id/persistent`: Toggle persistent status
|
||||
- `DELETE /api/admin/locations/:id`: Delete location
|
||||
- Profanity management: `/api/admin/profanity-words` (GET, POST, PUT, DELETE)
|
||||
|
||||
### SCSS Organization
|
||||
SCSS files are in `src/scss/`:
|
||||
- `main.scss`: Entry point importing all other files
|
||||
- `_variables.scss`: Theme colors and configuration
|
||||
- `_mixins.scss`: Reusable style patterns
|
||||
- `pages/`: Page-specific styles (home, admin, privacy)
|
||||
- `components/`: Component styles (navbar, map, cards, forms)
|
||||
|
||||
### Key Design Patterns
|
||||
|
||||
1. **Modular Route Architecture**: Routes accept dependencies as parameters for testability
|
||||
2. **Dual Database Design**: Separate databases for application data and content moderation
|
||||
3. **Graceful Degradation**: Fallback geocoding providers and error handling
|
||||
4. **Automated Maintenance**: Cron-based cleanup of expired reports
|
||||
5. **Security**: Server-side content filtering, environment-based configuration
|
||||
|
||||
### Deployment
|
||||
- Automated deployment script for Debian 12 ARM64 in `scripts/deploy.sh`
|
||||
- Caddy reverse proxy configuration in `scripts/Caddyfile`
|
||||
- Systemd service files for process management
|
||||
Loading…
Add table
Add a link
Reference in a new issue