78 lines
4.8 KiB
Markdown
78 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
1. **Plan:** Decide where your logic belongs (backend controller, frontend JS, etc).
|
|
2. **Backend:** Add/modify controllers, services, and routes as needed. Use NocoDB API via the service layer.
|
|
3. **Frontend:** Add/modify JS modules in `/public/js`. Update HTML/CSS as needed.
|
|
4. **Document:** Update `README.md` and `files-explainer.md`.
|
|
5. **Test:** Manually test your feature in both desktop and mobile views.
|
|
6. **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!
|