# Geographic Information System (GIS) Architecture Blueprint
## Kampong Speu Provincial Demographic Management System (KSP-DMS)

**Document Code:** KSP-DMS-DOC-GIS-01  
**Technology Stack:** Leaflet JS v1.9 + GeoJSON Boundary Engine + HTML5 Canvas  
**Version:** 1.0 (Draft Proposal)  

---

## 1. GIS Architecture & Philosophy

The GIS component of KSP-DMS provides provincial planners with spatial demographic intelligence while enforcing strict privacy safeguards:

```
+-----------------------------------------------------------------------------------+
|                            DATABASE PERSISTENCE LAYER                             |
|  [communes] & [villages] Tables      [map_boundary_versions] Table                 |
|  - Real-time demographic counts      - Synthetic GeoJSON boundary coordinates     |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                        APPLICATION AGGREGATION ENGINE                             |
|  `GisService::getCommuneChoropleth(districtId, metric)`                           |
|  - Queries database for active population / household counts                      |
|  - Calculates demographic density: `count / square_km`                            |
|  - Normalizes metric into statistical color bins (ColorBrewer Quintiles)          |
|  - Strips all individual PII and personal identifiers                             |
|  - Merges aggregated attributes into GeoJSON `properties` object                  |
+-----------------------------------------------------------------------------------+
                                          |
                                [JSON Output]
                                          |
+-----------------------------------------------------------------------------------+
|                      BROWSER PRESENTATION LAYER (LEAFLET)                         |
|  - Renders base map tiles (OpenStreetMap / Local Tile Cache)                      |
|  - Renders interactive GeoJSON polygon overlays with dynamic choropleth shading   |
|  - Tooltip hover shows: Commune Name (Khmer/EN), Total Pop, Density               |
|  - Click event zooms into commune sub-boundaries                                  |
+-----------------------------------------------------------------------------------+
```

---

## 2. Privacy-by-Design Spatial Constraints

1. **Aggregation-Only Visualization:** The GIS map exclusively displays polygon boundaries (Districts and Communes) with thematic color fills based on aggregate metrics.
2. **Point Data Prohibition:** Individual household dwelling pins, GPS coordinates, and personal street markers are strictly prohibited in the GIS data pipeline.
3. **Synthetic GeoJSON Boundaries:** For development and prototype evaluation, synthetic polygon coordinates representing the administrative boundaries of Kampong Speu are utilized, preventing reliance on unverified commercial GIS services.

---

## 3. Spatial Layers & Metric Visualizations

### 3.1 Layer Hierarchy
- **Layer 0 (Base Map):** Lightweight local tile cache or offline OpenStreetMap canvas.
- **Layer 1 (District Boundaries):** Thick polygon outlines representing the 8 districts of Kampong Speu.
- **Layer 2 (Commune Boundaries):** Thematic choropleth polygons color-coded according to the selected metric.

### 3.2 Dynamic Thematic Metrics
- **Metric 1: Total Population Density:** Number of residents per square kilometer.
- **Metric 2: Household Density:** Number of registered households per commune.
- **Metric 3: Dependency Ratio:** Ratio of children (<15) and elderly (>65) to working-age population (15-64).
- **Metric 4: Poverty Concentration:** Synthetic IDPoor household percentage by commune.

---

## 4. Leaflet Map Configuration & Responsive Controls

```javascript
// Example Client-Side Leaflet Setup
const map = L.map('ksp-gis-map').setView([11.4533, 104.5208], 9); // Kampong Speu Center

L.geoJSON(communeGeoData, {
    style: function(feature) {
        return {
            fillColor: getChoroplethColor(feature.properties.density),
            weight: 2,
            opacity: 1,
            color: '#ffffff',
            dashArray: '3',
            fillOpacity: 0.7
        };
    },
    onEachFeature: function(feature, layer) {
        layer.bindTooltip(`
            <strong>${feature.properties.name_km} (${feature.properties.name_en})</strong><br/>
            ប្រជាជនសរុប (Total Pop): ${feature.properties.total_population.toLocaleString()}<br/>
            ដង់ស៊ីតេ (Density): ${feature.properties.density}/km²
        `);
    }
}).addTo(map);
```
