# Map 

Map is BNKops canvassing application. It is built from the ground up to serve our community (Edmonton). 

## Prerequisites
- Docker and Docker Compose installed
- NocoDB instance with API access
- Domain name (optional but recommended for production)

## NocoDB Table Setup

### Required Columns

!!! warning "Case Sensitive" 
    When entering in the required columns, make sure that you enter in exact information. Case sensitivity matters for mapping the values to the map itself. 

Create a table in NocoDB with these required columns. The format here is the `Name of the column - column type - details`:

1. **Geo-Location** (geo-data) - Format: "latitude;longitude"
2. **latitude** (Decimal) - Precision: 10, Scale: 8
3. **longitude** (Decimal) - Precision: 11, Scale: 8

### Recommended Columns

- First Name (Text)
- Last Name (Text)
- Email (Email)
- Phone (Phone)
- Unit Number (Text)
- Address (LongText)
- Support Level (Single Select) - Values (only enter numbers): 
  - 1 `Strong Support (Green)`
  - 2 `Moderate Support (Yellow)`
  - 3 `Low Support (Orange)`
  - 4 `No Support (Red)`
- Sign (Checkbox)
- Sign Size (Single Select) - Values: Small, Medium, Large
- Notes (LongText)

## Login Sheet Setup
Create a separate table for authorized users with:
- Email (Email) - Primary column
- Name (Text) - Optional

## API Token Setup

1. In NocoDB, click user icon → Account Settings
2. Go to "API Tokens" tab
3. Create new token with read/write permissions for both tables

## 6. Finding NocoDB IDs

- **Project and Table IDs**: Use the full NocoDB view URL in `NOCODB_VIEW_URL`
- **Login Sheet ID**: Use the full URL to your login sheet in `NOCODB_LOGIN_SHEET`

## Environment Configuration

!!! note "Config" 
    The `./config.sh` should have created a new `.env` file. If `.env` file is present, and it has properly defined domain, skip to step 2

1. Copy the example env file:

```bash
cp .env.example .env
```

2. Edit .env with your NocoDB details:
```env
NOCODB_API_URL=https://your-nocodb-instance.com/api/v1
NOCODB_API_TOKEN=your-api-token-here
NOCODB_VIEW_URL=https://your-nocodb-instance.com/dashboard/#/nc/project-id/table-id
NOCODB_LOGIN_SHEET=https://your-nocodb-instance.com/dashboard/#/nc/project-id/login-sheet-id

# Server Configuration
PORT=3000
NODE_ENV=production

# Session Secret (generate with: openssl rand -hex 32)
SESSION_SECRET=your-secure-random-string

# Map Defaults
DEFAULT_LAT=53.5461
DEFAULT_LNG=-113.4938
DEFAULT_ZOOM=11

# Optional: Map Boundaries
# BOUND_NORTH=53.7
# BOUND_SOUTH=53.4
# BOUND_EAST=-113.3
# BOUND_WEST=-113.7

# Domain Settings (for cookies)
COOKIE_DOMAIN=.yourdomain.com
ALLOWED_ORIGINS=https://map.yourdomain.com,http://localhost:3000
```

## Running the Application

### Development Mode
```bash
cd app
npm install
npm run dev
```

### Production with Docker
```bash
docker-compose up -d
```

## First Run

1. Access the application at `http://localhost:3000` (or your domain)
2. Login with an email from your authorized users list
3. Verify locations appear on the map

## Maintenance

- To clear the geocoding cache, restart the application
- To update the application:
  ```bash
  docker-compose down
  git pull origin main
  docker-compose up -d --build
  ```

## Troubleshooting

- **Locations not showing**: Verify table has required columns and API token has read permissions
- **Cannot add locations**: Check API token has write permissions
- **Authentication issues**: Verify login sheet is properly configured

## Security Recommendations

1. Use HTTPS in production
2. Regularly rotate API tokens
3. Restrict API token permissions to only what's needed
4. Set appropriate CORS and cookie domains
5. Keep dependencies updated

The application will automatically:

- Parse project/table IDs from view URLs
- Sync geo fields between different formats
- Cache geocoding results for performance
- Rate limit API endpoints
- Validate all inputs