turash/bugulma/backend/docs/PUBLIC_TRANSPORT.md

Public transport integration

This module provides read-only access to precomputed public transport data and optionally imports it into the database.

Data sources

• data/bugulma_public_transport.json or data/bugulma_public_transport_enriched.json (preferred): preprocessed JSON with stops and metadata
• data/bugulma_gtfs_export/* : GTFS export with stops.txt and routes.txt

Routes

• GET /api/v1/public-transport/metadata — returns dataset metadata
• GET /api/v1/public-transport/stops — returns common stops directory
• GET /api/v1/public-transport/stops/search?q=term — search stops by substring
• GET /api/v1/public-transport/stops/:id — get a single stop by key
• GET /api/v1/public-transport/gtfs/:filename — raw GTFS file (e.g., README.txt, stops.txt, routes.txt)

Database

• Two new tables are automatically migrated via GORM:
  • public_transport_stops
  • public_transport_routes

Seeding

• If data/bugulma_public_transport_enriched.json and/or data/bugulma_gtfs_export are present, the server will attempt to import stops and routes automatically at startup.

Repository

• Implementation: internal/repository/public_transport_repository.go
• Interface: domain.PublicTransportRepository

Service

• Read-only file loader: internal/service/public_transport_service.go
• Importer/seeder: internal/service/public_transport_importer.go