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, volunteer shifts, and geographic overlays 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, cuts, 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.
Documentation: Keep code well-documented and maintain the Instructions.md, README.md and files-explainer.md files.
Modularity: Use modular JavaScript to keep code organized and reusable; try to avoid large monolithic scripts keeping functionality separated by feature with files no longer than 500 lines.

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.
Pagination Use pagination for API endpoints returning large datasets to avoid performance issues. For example, getAll should be getAllPaginated

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.
Add a new cut property: Update the cuts table schema, cutsController.js, and admin-cuts.js form.
Modify cut drawing behavior: Update /public/js/cut-drawing.js and related cut modules.
Add a new shift feature: Update shiftsController.js for backend logic, shifts.js for authenticated users, and use publicShiftsController.js for public-facing functionality.
Modify public signup flow: Update /public/js/public-shifts.js, publicShiftsController.js, and related email templates in /templates/email/.

Key Features

Public Shift Signup: Visitors can view and sign up for volunteer shifts without requiring an account. Temporary accounts are automatically created during signup with shift-based expiration.
Admin Shift Management: Admins can toggle shift visibility, generate shareable public links, and manage volunteer signups through the admin panel.
Email Confirmation System: Automated email confirmations sent to volunteers with account credentials, shift details, and login instructions.
Rate Limiting: Built-in spam protection for public signup endpoints to prevent abuse.
Responsive Design: All pages optimized for mobile and desktop viewing with accessible interfaces.

Contact

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

Happy coding!

4.8 KiB Raw Permalink Blame History