Birmingham 311 Map

Live app: https://admin.mcr.pub/311/

Flask + MapLibre GL map of Birmingham, Alabama 311 / SeeClickFix service requests: issue search, boundary layers, analytics, and PDF issue reports. This repository is the application source as run on Magic City Reader’s admin host (minus local databases, issue photo cache, and proprietary fonts).

License

Copyright © Magic City Reader / J.R. Williams

This work is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0). See LICENSE.

Third-party exceptions (not under CC BY-NC-SA):

• Leaflet assets: BSD 2-Clause
• MapLibre GL, Bootstrap, and other CDN libraries: their own licenses
• Helvetica Now webfonts are not included in this repository (proprietary). Production serves them from the host font tree; self-hosters should substitute another family or supply their own licensed files under fonts/

What’s included

• app.py — Flask API and HTML shell
• templates/ — Jinja map UI (index.html)
• js/, css/ — MapLibre adapter, layer control, styles
• reports/ — PDF issue-report builders (Python only)
• Boundary GeoJSON, data/layer_config_optimized.json, social preview images
• sync_seeclickfix.py — incremental SeeClickFix sync
• requirements.txt, gunicorn.conf.py, scripts/

What’s not included

• birmingham_311_enhanced.db (and WAL/SHM) — build or sync your own
• images/issue_images/ — on-disk photo/thumbnail cache
• fonts/ — Helvetica Now (see above)
• Gunicorn logs, generated PDF exports, photo compilations
• Optional static/models/ 3D mesh tiles

Run locally

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Optional: shapely (city-limits filtering in sync), gunicorn
export MCR_UMAMI_ENABLED=0
# Point at a SQLite DB if you have one:
# (default path in app.py is birmingham_311_enhanced.db next to app.py)
python3 -c "from app import app; app.run(host='127.0.0.1', port=5001, debug=True)"

Open http://127.0.0.1:5001/311/. Without a populated database and (optionally) issue images, map/API panels will be empty or error on data routes.

app.py inserts /root/umami on sys.path for shared Umami helpers on the production host. Set MCR_UMAMI_ENABLED=0 when that path is absent.

templates/site-header.html is a small vendored copy of the mcr.pub site chrome partial.

Production notes

On Magic City Reader’s server the unit is birmingham-311 (Gunicorn on 127.0.0.1:5001). Caddy serves https://admin.mcr.pub/311/ with path-prefix stripping. Python changes require systemctl restart birmingham-311; template/static edits usually do not.