Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 152 additions & 0 deletions .claude.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# OPTIMAP - Claude Code Configuration

This file contains project-specific guidance for Claude Code when working with the OPTIMAP codebase.

## Project Overview

OPTIMAP is a Django-based geospatial metadata portal for scientific publications. It provides interactive mapping, publication metadata management, and geocoding services.

## Local Library Policy

### Policy Statement

**All external JavaScript and CSS libraries MUST be served locally from the `publications/static/` directory. CDN dependencies are NOT allowed in production.**

### Rationale

1. **Privacy & GDPR Compliance**: Serving libraries from CDNs may leak user IP addresses and browsing behavior to third parties
2. **Reliability**: Eliminates dependency on external CDN availability and potential network issues
3. **Performance**: Local libraries are served from the same origin, reducing DNS lookups and connection overhead
4. **Security**: Prevents supply chain attacks from compromised CDN resources
5. **Offline Development**: Enables development without internet connectivity

### Implementation

All external libraries are managed through the `publications/static/download_libraries.sh` script:

```bash
cd publications/static/
bash download_libraries.sh
```

This script downloads all required libraries to the appropriate directories:
- JavaScript files → `publications/static/js/`
- CSS files → `publications/static/css/`
- Images → `publications/static/css/images/`
- Fonts → `publications/static/css/fonts/`

### Currently Managed Libraries

#### Core Libraries
- jQuery 3.4.1
- Bootstrap 4.4.1 (JS and CSS)
- Popper.js 2.x (for Bootstrap tooltips)
- Font Awesome 4.7.0 (CSS and fonts)

#### Mapping Libraries
- Leaflet 1.9.4 (core mapping library)
- Leaflet Draw 1.0.4 (geometry drawing)
- Leaflet Fullscreen 3.0.2 (fullscreen control)
- Leaflet Control Geocoder 2.4.0 (location search/gazetteer)

#### UI Components
- Bootstrap Datepicker 1.9.0

### Adding New External Libraries

When adding a new external library to OPTIMAP:

1. **Update `download_libraries.sh`**:
- Add wget commands to download the library files
- Include version numbers in echo statements
- Download source maps if available
- Download any required assets (images, fonts, etc.)

2. **Download the library**:
```bash
cd publications/static/
bash download_libraries.sh
```

3. **Update templates to reference local files**:
```django
<!-- CORRECT: Use local static files -->
<link rel="stylesheet" href="{% static 'css/library.css' %}" />
<script src="{% static 'js/library.js' %}"></script>

<!-- INCORRECT: Never use CDN URLs -->
<link rel="stylesheet" href="https://cdn.example.com/library.css" />
<script src="https://cdn.example.com/library.js"></script>
```

4. **Test thoroughly**:
- Verify the library loads correctly
- Check browser console for 404 errors
- Ensure all assets (images, fonts) load properly
- Test in both development and production environments

5. **Commit all files**:
- Commit both the download script AND the downloaded library files
- Library files should be checked into version control

### Version Control

- All library files are committed to the repository
- This ensures reproducible builds and consistent deployments
- Update libraries deliberately and test thoroughly before committing new versions

### Exception Policy

CDN usage is only acceptable in these limited cases:
- Temporary development/testing (must be replaced before production)
- Services that cannot be self-hosted (e.g., Google reCAPTCHA)
- External APIs that require CDN delivery (must be documented)

Any exceptions must be:
1. Documented in this file with justification
2. Reviewed by the project maintainer
3. Include a plan for eventual local hosting if possible

## Development Guidelines

### File Organization

- Custom JavaScript: `publications/static/js/map-*.js`
- Custom CSS: `publications/static/css/*.css`
- Templates: `publications/templates/`
- Views: `publications/views*.py`

### Map Architecture

The interactive map consists of several modular components:

- `map-popup.js` - Popup content generation
- `map-interaction.js` - Click handling and overlapping features
- `map-keyboard-navigation.js` - Keyboard accessibility
- `map-search.js` - Publication search/filtering
- `map-gazetteer.js` - Location search (geocoding)
- `map-zoom-to-all.js` - Zoom to all features control
- `main.js` - Map initialization and orchestration

### Accessibility

OPTIMAP follows WCAG 2.1 AA standards:

- Focus indicators are only visible in high contrast mode (`body.high-contrast`)
- All interactive elements must have ARIA labels
- Screen reader announcements for dynamic content
- Keyboard navigation support for all map features

### Testing

Before committing changes:

1. Test with high contrast mode enabled
2. Test keyboard navigation
3. Test with screen reader (if possible)
4. Verify no console errors
5. Check all CDN links have been replaced with local files

## Contact

For questions about this configuration, contact the OPTIMAP development team at [email protected].
19 changes: 18 additions & 1 deletion .claude/settings.local.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,14 @@
"Bash(python manage.py:*)",
"Bash(python -m py_compile:*)",
"Bash(python:*)",
"Read(//home/daniel/git/geoextent/geoextent/lib/**)",
"Read(//home/daniel/git/geoextent/**)",
"Bash(docker compose run:*)",
"Bash(docker compose exec:*)",
"Bash(docker compose:*)",
"Bash(OPTIMAP_LOGGING_LEVEL=WARNING python manage.py test tests.test_geoextent)",
"Bash(OPTIMAP_LOGGING_LEVEL=WARNING python manage.py test tests.test_geoextent.GeoextentRemoteGetTest)",
"Bash(geoextent:*)"
"Bash(node --check:*)",
"Bash(find:*)",
"Bash(OPTIMAP_LOGGING_LEVEL=WARNING python manage.py test:*)",
Expand All @@ -25,7 +33,16 @@
"Bash(bash:*)",
"Bash(./create_wikibase_property.sh:*)",
"Bash(python3:*)",
"Bash(pkill:*)"
"Bash(pkill:*)",
"Bash(wget:*)"
"Bash(geoextent:*)",
"Bash(curl:*)",
"Bash(python3:*)",
"Read(//home/daniel/.cache/**)",
"Bash(gh pr list:*)",
"Bash(gh pr view:*)",
"Bash(OPTIMAP_LOGGING_LEVEL=WARNING python manage.py test tests)",
"Bash(export OPTIMAP_LOGGING_LEVEL=WARNING)"
],
"deny": [],
"ask": []
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,5 @@ certbot/www/
publications/management/commands/marine_regions_iho.geojson

publications/management/commands/world_continents.geojson

.claude/temp.md
Loading
Loading