Map Maker Development Assistant
An AI assistant specialized in developing a browser-based printable/exportable map creation application built on OpenStreetMap data with a Flask backend and React frontend.
Project Architecture
This skill helps you work with a full-stack mapping application with:
**Backend**: Python Flask API in `api/` directory with SQLite storage**Frontend**: TypeScript + React UI in `frontend/` directory**Map Data**: OpenStreetMap integration**Deployment**: Local Flask development, containerized WSGI for productionMap Structure Hierarchy
The application uses a nested map structure:
1. **Projects** (root level)
2. **Region Maps** (multiple per project, with boundaries)
3. **Suburb Maps** (within region boundaries, separately editable)
4. **Smaller Maps** (within suburbs, own boundaries)
5. **Annotation Layers** (editable per map)
Python Backend Guidelines
When working on Python/Flask backend code:
Code Standards
Follow PEP 8 style guide strictlyLines must not exceed 79 charactersUse type hints from the `typing` module (e.g., `List[str]`, `Dict[str, int]`)Prefer classes over standalone functionsLines should contain code OR be completely blank (no whitespace-only lines)Function Formatting
```python
def calculate_area(
radius: float
) -> float:
"""
Calculate the area of a circle given the radius.
Parameters:
radius (float): The radius of the circle.
Returns:
float: The area of the circle, calculated as π * radius^2.
"""
import math
return math.pi * radius ** 2
```
Class Formatting
Each argument on a separate line for methodsComprehensive docstrings following PEP 257Clear attribute and method documentationUse async/await patterns where appropriate```python
class MapProcessor:
"""
Process OpenStreetMap data for region boundaries.
Attributes:
config (str): Configuration settings for map processing
Methods:
__init__: Initialize the processor
process_region: Process a region map boundary
"""
def __init__(
self,
config: str,
) -> None:
"""Initialize the map processor."""
self.config = config
async def process_region(
self,
region_id: str
) -> None:
"""Process a region map."""
try:
# Implementation here
pass
except Exception as e:
print(f"❌ Processing failed: {e}\n")
```
Documentation
Clear, concise comments for each functionDescriptive function names with type hintsDocument design decisions in commentsPrioritize readability and maintainabilityTypeScript Frontend Guidelines
When working on TypeScript/React frontend code:
Core Principles
Target TypeScript 5.x / ES2022Use pure ES modules (never CommonJS)Respect existing architecture before adding new patternsPrioritize maintainability and clarityNaming Conventions
PascalCase: classes, interfaces, enums, type aliasescamelCase: variables, functions, methodskebab-case: filenames (e.g., `map-layer.ts`, `region-selector.ts`)No interface prefixes (avoid `IMapData`, just use `MapData`)Type Safety
Avoid `any`; prefer `unknown` with type narrowingUse discriminated unions for events and state machinesCentralize shared types to avoid duplicationAsync & Error Handling
Use `async/await` consistentlyWrap awaits in try/catch with structured errorsGuard edge cases early to avoid deep nestingDebounce configuration updatesDispose resources deterministicallyArchitecture Patterns
Keep transport, domain, and presentation layers decoupledFollow existing dependency injection patternsSingle-purpose modulesProvide lifecycle hooks (`initialize`, `dispose`)UI Components
Sanitize user content before renderingKeep UI layers thin; push logic to servicesUse events/messaging to decouple UI from business logicTesting
Add/update unit tests when modifying codeIntegration tests for cross-module behaviorAvoid brittle timing; use fake timersRun test scripts before submittingSecurity Practices
Input Validation
Validate and sanitize all external inputUse schema validators or type guardsEncode untrusted content before rendering HTMLData Protection
Use parameterized queries for SQLiteNever hardcode secretsLoad secrets from secure sourcesUse vetted crypto libraries onlyDependencies
Patch dependencies promptlyMonitor security advisoriesRequest least-privilege scopesPerformance Guidelines
Lazy-load heavy dependenciesDefer expensive work until neededBatch or debounce high-frequency eventsTrack resource lifetimes to prevent leaksApply retries and backoff to network callsDocumentation Requirements
JSDoc for all public APIsInclude `@remarks` or `@example` when helpfulUpdate architecture docs for significant changesRemove stale comments during refactorsDocument new configuration keysDevelopment Workflow
1. **File Organization**: Place code in `api/` or `frontend/` directories with appropriate `docs/` subdirectories
2. **Code Style**: Run lint/format scripts before submitting
3. **Testing**: Add tests for new features and bug fixes
4. **Documentation**: Update relevant docs in `docs/` folders
Common Tasks
Adding a New Map Layer
1. Define SQLite schema in backend
2. Create Flask API endpoint with proper validation
3. Build React component with TypeScript types
4. Add tests for both frontend and backend
5. Document the layer type in project docs
Integrating OpenStreetMap Data
1. Use existing OSM integration patterns
2. Validate and normalize external responses
3. Map errors to domain shapes
4. Add retry logic with backoff
5. Cache responses appropriately
Creating Region Boundaries
1. Validate boundary coordinates
2. Store in SQLite with proper indexing
3. Ensure nested map boundaries respect parent boundaries
4. Render boundaries in React with proper sanitization
Important Reminders
Each environment (region/suburb/smaller maps) must respect its parent's boundariesAnnotation layers are independently editable per mapFollow the existing folder structure in `frontend/` and `api/`Consult `docs/` folders for feature-specific documentationTest locally with Flask before containerizing