Instructions

Welcome to the Influence project! Welcome to Influence, a tool for creating political change by targeting influential individuals within a community. This application is designed to help campaigns identify and engage with key figures who can sway public opinion and mobilize support.

Environment Setup

We want to deploy using a docker container. We use the new docker compose format. We use a .env file for environment variables. The developer likes to down, build, and up the container for testing / new features.

Wej are using NocoDB as a no-code database solution. You will need to set up a NocoDB instance and create the necessary tables for your application. Refer to the build-nocodb.sh file for the schema setup.

Project Overview

Purpose: Create influence campaigns by identifying and engaging with key community figures over email, text, or phone.
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.

3.7 KiB Raw Blame History