How nuhil/bangladesh-geocode works
Project Type and Purpose
• This is an open-source data distribution project that publishes Bangladesh administrative boundary and geo-coordinate data at four hierarchical levels (Division, District, Upazila, Union) in multiple file formats (CSV, JSON, PHP array, SQL, XML, GeoJSON).
• It leverages Jekyll (via _config.yml) to host a static website (likely on GitHub Pages) where developers and GIS applications can download or pull the data.
High-Level File-Structure Analysis
• Top level:
• FUNDING.yml, LICENSE, README.md – metadata about the project.
• _config.yml – Jekyll configuration for static site generation.
• img/img.txt – image assets or documentation placeholder.
• Data directories (divisions, districts, upazilas, unions): each contains the same dataset in five export formats (CSV, JSON, PHP array, SQL, XML).
• geojson/districts.geojson – prebuilt GeoJSON for district-level polygon boundaries.
Main Components
a. Source Data & Conversion Pipeline
• Raw source files (CSV as “master” format)
• Conversion scripts/services (not shown in repo but implied) that generate JSON, PHP arrays, SQL dumps, XML exports, and GeoJSON.
b. Repository & Build System
• GitHub (Git) repo storing all assets.
• Jekyll build engine (reads _config.yml) that stitches together a static website.
c. Hosting & Distribution
• GitHub Pages or equivalent static-site host serving HTML, data files, and GeoJSON.
d. Consumers & Integrations
• MySQL database importers (using .sql files)
• Data analysts or GIS applications (ingesting CSV/JSON/GeoJSON)
• Web or mobile apps that fetch JSON or PHP arrays via HTTP/HTTPS
• Contributors (via Git PRs) who update CSV or CSV-derived files
Relationships & Data Flows
• Data collection (external sources: bangladesh.gov.bd, Wikipedia, Google Maps) → CSV files in each directory.
• Conversion pipeline (scripts) reads CSV → outputs JSON, PHP array, XML, SQL, GeoJSON under each folder.
• Git commit → Jekyll build triggered → static website and all data assets are published.
• Consumers clone or fetch data files directly, or import SQL into MySQL follow-on queries.
Architectural Patterns & Design Principles
• Static-site generation (SSG) for stable, cacheable distribution; minimal server logic.
• File-based data distribution: each level is a self-contained module.
• Separation of concerns:
• Data source (CSV)
• Data transformation (format converters)
• Presentation layer (Jekyll static site)
• Consumption layer (external apps/DB imports)
Essential Details to Capture
• The hierarchy of administrative levels and their folder/module boundaries.
• The multi-format export strategy driven by a common source.
• The static site generation flow vs. the data-API/distribution flow.
• Points of extensibility: conversion scripts, addition of new columns (population, postal code), new export formats.