Instructions

Welcome to the BNKops Influence project! Welcome to BNNKops 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

NocoDB Development Best Practices

Field Naming and Access

Use Column Titles, Not Column Names: NocoDB expects column titles (e.g., "Campaign Slug") in API calls, not column names (e.g., "slug")
Consistent Mapping: Always map between your application's field names and NocoDB's column titles in the service layer
Where Clauses: Use column titles in where conditions: (Campaign Slug,eq,value) not (slug,eq,value)

System Fields

Avoid System Field Conflicts: Never create user-defined fields with names like created_at, updated_at as they conflict with NocoDB system fields
Use System Fields: Leverage NocoDB's automatic system fields (CreatedAt, UpdatedAt, CreatedBy, etc.) instead of creating your own
Sorting: Sort by system field titles: -CreatedAt not -created_at

Select Field Configuration

Use colOptions: For SingleSelect and MultiSelect fields, always use colOptions with an options array
Never use dtxp: The dtxp parameter is deprecated and causes corrupted select options

Example Structure:

{
  "uidt": "SingleSelect",
  "colOptions": {
    "options": [
      {"title": "draft", "color": "#d0f1fd"},
      {"title": "active", "color": "#c2f5e8"}
    ]
  }
}

Table Management

Clean Recreation: When fixing table schema issues, delete and recreate tables rather than trying to modify corrupted structures
Environment Cleanup: Remove duplicate table IDs from .env files to avoid using old/deleted tables
Restart After Changes: Always restart the application after table recreation to pick up new table IDs

API Endpoints

Use Correct API Versions:
- Data operations: /db/data/v1/{projectId}/{tableId}
- Meta operations: /db/meta/tables/{tableId}
Field Validation: Test field access directly via NocoDB API before implementing in application logic
Error Handling: NocoDB returns specific error codes like FIELD_NOT_FOUND, TABLE_NOT_FOUND - handle these appropriately

Debugging Tips

Direct API Testing: Use curl to test NocoDB API directly before implementing in application
Check Table Metadata: Use /db/meta/tables/{tableId} to inspect actual column names and titles
Verify System Fields: Check which fields are marked as "system": true to avoid conflicts
Log API Responses: Always log NocoDB API responses during development to understand the exact data structure returned

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.

Visuals

We want a clean modern look. We use Leaflet.js for mapping. We use vanilla JS for the frontend. We want a responsive design that works well on both desktop and mobile. We want clear feedback for user actions (loading spinners, success/error messages). We want error handling to provide appropriate feedback when errors occur (both backend and frontend).

6.5 KiB Raw Blame History