Instructions

Welcome to the Map project! This application is a canvassing tool for political campaigns, built to be robust, maintainable, and easy to extend. Please read these instructions carefully before contributing.

Project Overview

Purpose: Visualize, manage, and update canvassing locations and volunteer shifts on an interactive map.
Backend: Node.js/Express, with NocoDB as the database (REST API).
Frontend: Vanilla JS, Leaflet.js for mapping, modular code in /public/js.
Admin Panel: Accessible via /admin.html for managing start location, walk sheet, and settings.

Key Principles

Separation of Concerns: Keep logic for API, UI, and data management in their respective files/modules.
Security: Never expose sensitive credentials. All API calls to NocoDB go through the backend.
Scalability: Write code that is easy to extend (e.g., adding new location fields, new admin features).
User Experience: Prioritize clear feedback, error handling, and mobile responsiveness.

Directory Structure

app/ - Node.js backend (Express server, routes, controllers, services, utils)
app/public/ - Frontend static files (HTML, CSS, JS)
app/public/js/ - Modular JavaScript for map, UI, auth, etc.
app/controllers/ - Express controllers for business logic
app/routes/ - Express routers for API endpoints
app/services/ - Backend services (NocoDB, geocoding, QR code)
app/utils/ - Shared backend utilities

Development Rules

No inline event handlers. Always use addEventListener in JS files.
Update documentation. Always update README.md and files-explainer.md when adding features or files.
Consistent style. Follow the existing code style and naming conventions.
Error handling. Always provide user feedback for errors (both backend and frontend).
Environment variables. Use .env for secrets/config, never hardcode sensitive data.
Testing. Test new features locally and ensure they do not break existing functionality.

How to Add a Feature

First look through the existing codebase to understand where similar logic is implemented. You can find a full listing of the files in the files-explainer.md file.

When adding a new feature, follow these steps:

Plan: Decide where your logic belongs (backend controller, frontend JS, etc).
Backend: Add/modify controllers, services, and routes as needed. Use NocoDB API via the service layer.
Frontend: Add/modify JS modules in /public/js. Update HTML/CSS as needed.
Document: Update README.md and files-explainer.md.
Test: Manually test your feature in both desktop and mobile views.
Pull Request: Submit your changes for review.

Common Tasks

Add a new location field: Update NocoDB schema, backend helpers, and frontend forms.
Add a new admin feature: Add a new section to /admin.html, backend route/controller, and frontend JS.
Change map behavior: Update /public/js/map-manager.js and related modules.

Contact

If you have questions, reach out to the lead developer or open an issue in the repository.

Happy coding!

3.1 KiB Raw Blame History