guideCity

Android walking city-guide app. Detects the user's location, finds nearby landmarks, and narrates historical/architectural information about them by voice while showing a swipeable card stack. Starting city: Moscow.

Architecture

                 ┌────────────────────┐
                 │   Android app      │  Kotlin + Jetpack Compose
                 │  (android/)        │  2GIS map, on-device TTS,
                 └─────────┬──────────┘  location, Room favorites
                           │ HTTPS / REST (JSON)
                 ┌─────────▼──────────┐
                 │   FastAPI backend   │  Python, SQLAlchemy, Alembic
                 │   (backend/)        │  Dockerized
                 └─────────┬──────────┘
                           │ SQL
                 ┌─────────▼──────────┐
                 │ PostgreSQL+PostGIS  │  cities / places / place_content
                 └────────────────────┘

• backend/ — FastAPI service exposing city/place/nearby-search endpoints, backed by PostgreSQL+PostGIS. See backend/ for details.
• android/ — Kotlin/Compose app skeleton (MVVM, Hilt, Retrofit, Room, DataStore, 2GIS MapKit, on-device TextToSpeech).

Backend quickstart

cp .env.example .env
docker compose up -d db
docker compose exec api alembic upgrade head   # (once api image is built: docker compose up -d --build api adminer first)
docker compose exec api python -m seed.seed_loader --file seed/moscow_gorky_park.yaml
docker compose exec api python -m seed.seed_loader --file seed/moscow_red_square.yaml
docker compose exec api python -m seed.seed_loader --file seed/moscow_city.yaml
curl http://localhost:8000/api/v1/health
curl "http://localhost:8000/api/v1/nearby?lat=55.7525&lon=37.6231"

Swagger UI: http://localhost:8000/docs Adminer (DB inspection): http://localhost:8080

The api service binds 0.0.0.0:8000 (see docker-compose.yml), so it's also reachable from other devices on the same LAN at http://<this-machine's-LAN-IP>:8000/ — no extra config needed, just make sure nothing (firewall, VPN) blocks port 8000 on that interface.

It's also reverse-proxied behind nginx at https://guidetest.vrubel.xyz/, which works from anywhere (not just the local network) and is the preferred API_BASE_URL for the Android app during this test phase.

Android quickstart

cp android/local.properties.example android/local.properties
# fill in sdk.dir and DGIS_API_KEY (test key: b4df01a8-61db-4cb9-8286-7e069495987d)
cd android && ./gradlew :app:assembleDebug

Point the app's API base URL (API_BASE_URL in local.properties) at https://guidetest.vrubel.xyz/ (works from anywhere), http://10.0.2.2:8000/ for the emulator, or your machine's LAN IP for a physical device on the same Wi-Fi/LAN.

Run unit tests before building — ./gradlew testDebugUnitTest, then ./gradlew :app:assembleDebug.

Notes / current scope

This is iteration 1: Moscow only (Gorky Park, Red Square area, Moscow-City), no user accounts (favorites are local/Room-only), no speed/heading-aware auto content-length selection yet (reserved API params exist, unused).

The 2GIS API key above is used directly via local.properties/BuildConfig for development convenience — don't ship it as-is in a public repo.