# 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:

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.