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
3 changes: 3 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Copy to .env (never commit .env). Used by scripts/, not by the app.
# Create a key at https://aistudio.google.com/apikey and pick the project g311-communication-needs-map.
GEMINI_API_KEY=
2 changes: 2 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# The team's advisors are asked to review every pull request.
* @kquakk @skarthikb-tech
25 changes: 25 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: CI

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: astral-sh/setup-uv@v10.3.0
- run: uv sync --locked
- run: uv run ruff check
- run: uv run ruff format --check
- run: uv run pytest
# Streamlit Community Cloud installs from requirements.txt; keep it in step with uv.lock.
- name: requirements.txt matches uv.lock
run: |
uv export --no-dev --no-hashes --no-emit-project -o requirements.txt
git diff --exit-code requirements.txt
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.venv/
.env
__pycache__/
.pytest_cache/
.ruff_cache/
.streamlit/secrets.toml
1 change: 1 addition & 0 deletions .python-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
3.12
3 changes: 3 additions & 0 deletions .streamlit/config.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[theme]
base = "light"
primaryColor = "#1a73e8"
44 changes: 43 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,46 @@ Georgia 311 Challenge 2026 · DevDogs (GDG on Campus UGA)
- Advisor: Kyle Quach and Shakthi Karthik
- Sprint: Oct 16–30, 2026. Demo Day: Fri Oct 30 at DevFest Atlanta.

Starter code is added once the team confirms its stack at the Oct 19 kickoff.
## What's here

A blank [Streamlit](https://streamlit.io) app, plus the council district boundaries. Nothing is built yet; that's up to you.

| File | What it's for |
| --- | --- |
| `app.py` | The app. Start here. It should read only files in `data/`, so it runs anywhere with no keys. |
| `data/` | Committed data the app reads. The six council districts and the city limits are already here (see `data/README.md` for the source). |
| `scripts/` | Code you run on your own machine to fetch and prepare data, writing the results to `data/`. [geopandas](https://geopandas.org) is installed for joining Census areas to districts. |
| `scripts/gemini.py` | `client()` returns a Gemini client for writing summaries ahead of time. It reads `GEMINI_API_KEY` from `.env` (copy `.env.example`). |
| `tests/` | [pytest](https://docs.pytest.org) tests. `test_app.py` checks the app starts without errors. |

If Gemini replies "This model is currently experiencing high demand", change the model in `scripts/gemini.py` to an older Flash model such as `gemini-3.5-flash`. The newest model is the busiest on the free tier.

The Census data source comes in a separate pull request: the BigQuery sandbox or the Census API. Merge one.

## Run it locally

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:

```sh
uv sync
uv run streamlit run app.py # http://localhost:8501, reloads as you edit
uv run python scripts/<script>.py # run a data script
```

Before you push:

```sh
uv run ruff format # formats
uv run ruff check # lint (CI runs this)
uv run pytest # tests (CI runs this)
```

Add packages with `uv add <package>` (the app needs it) or `uv add --group dev <package>` (only scripts or tests need it). After `uv add`, refresh `requirements.txt`, which Streamlit Community Cloud installs from:

```sh
uv export --no-dev --no-hashes --no-emit-project -o requirements.txt
```

## Deploy

[Streamlit Community Cloud](https://streamlit.io/cloud) is free and runs straight from this repo: sign in with GitHub, choose **Create app**, pick this repo, branch `main` and file `app.py`. It redeploys on every push to `main`. Apps sleep after 12 hours without visitors and wake on the next visit.
11 changes: 11 additions & 0 deletions app.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
"""The Streamlit app. Run with `uv run streamlit run app.py`.

It reads only files committed in data/, so it needs no keys or secrets to run.
Fetching and preparing data happens in scripts/, ahead of time.
"""

import streamlit as st

st.set_page_config(page_title="Communication-needs Map", layout="wide")
st.title("Communication-needs Map")
st.write("Edit `app.py` and save; the page reloads by itself.")
8 changes: 8 additions & 0 deletions data/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Data

Files here are committed and read by `app.py`.

- `mableton-council-districts.geojson`: the six council districts. Properties: `district` (1–6) and `population` (2020 Census).
- `mableton-city-limits.geojson`: the city boundary.

Both come from the public layer the city's [Find My District](https://www.mableton.gov/1247/Find-My-District) lookup uses: <https://services5.arcgis.com/Mm1BAVEiAXrYE9vn/arcgis/rest/services/CouncilDistricts_CityLimits/FeatureServer> (layers 2 and 3), converted to WGS 84 (EPSG:4326).
1 change: 1 addition & 0 deletions data/mableton-city-limits.geojson

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions data/mableton-council-districts.geojson

Large diffs are not rendered by default.

22 changes: 22 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
[project]
name = "communication-needs-map"
version = "0.1.0"
description = "Communication needs by Mableton council district"
requires-python = ">=3.12"
dependencies = [
"pandas>=3.0.6",
"plotly>=7.1.0",
"streamlit>=1.66.0",
]

[dependency-groups]
dev = [
"geopandas>=1.2.0",
"google-genai>=2.31.0",
"pytest>=9.1.1",
"python-dotenv>=1.2.4",
"ruff>=0.17.1",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
103 changes: 103 additions & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# This file was autogenerated by uv via the following command:
# uv export --no-dev --no-hashes --no-emit-project -o requirements.txt
altair==6.3.0
# via streamlit
anyio==4.15.1
# via
# starlette
# streamlit
attrs==26.1.0
# via
# jsonschema
# referencing
certifi==2026.10.18
# via requests
charset-normalizer==3.5.2
# via requests
click==8.5.0
# via
# streamlit
# uvicorn
h11==0.16.0
# via uvicorn
idna==3.20
# via
# anyio
# requests
itsdangerous==2.2.0
# via streamlit
jinja2==3.1.6
# via
# altair
# pydeck
jsonschema==4.26.0
# via altair
jsonschema-specifications==2025.9.1
# via jsonschema
markupsafe==3.0.4
# via jinja2
narwhals==2.27.1
# via
# altair
# plotly
numpy==2.5.4
# via
# pandas
# pydeck
# streamlit
packaging==26.3
# via
# altair
# plotly
# streamlit
pandas==3.0.6
# via
# communication-needs-map
# streamlit
pillow==12.3.0
# via streamlit
plotly==7.1.0
# via communication-needs-map
protobuf==7.36.2
# via streamlit
pyarrow==26.0.0
# via streamlit
pydeck==0.9.3
# via streamlit
python-dateutil==2.9.0.post0
# via pandas
python-multipart==0.0.32
# via streamlit
referencing==0.37.0
# via
# jsonschema
# jsonschema-specifications
requests==2.34.2
# via streamlit
rpds-py==2026.9.1
# via
# jsonschema
# referencing
six==1.17.0
# via python-dateutil
starlette==1.9.0
# via streamlit
streamlit==1.66.0
# via communication-needs-map
typing-extensions==4.16.0
# via
# altair
# anyio
# referencing
# starlette
# streamlit
tzdata==2026.5 ; sys_platform == 'emscripten' or sys_platform == 'win32'
# via pandas
urllib3==2.8.0
# via requests
uvicorn==0.54.0
# via streamlit
watchdog==6.0.0 ; sys_platform != 'darwin'
# via streamlit
websockets==16.1.1
# via streamlit
12 changes: 12 additions & 0 deletions scripts/gemini.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
"""Gemini for scripts. The key comes from GEMINI_API_KEY in .env (see .env.example)."""

from dotenv import load_dotenv
from google import genai

# Model list: https://ai.google.dev/gemini-api/docs/models
MODEL = "gemini-3.8-flash"


def client() -> genai.Client:
load_dotenv()
return genai.Client() # reads GEMINI_API_KEY from the environment
10 changes: 10 additions & 0 deletions tests/test_app.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
from pathlib import Path

from streamlit.testing.v1 import AppTest

APP = str(Path(__file__).parent.parent / "app.py")


def test_app_runs():
app = AppTest.from_file(APP).run()
assert not app.exception
Loading
Loading