BusTime

• Mission: Make daily commuting predictable. BusTime uses AI to predict bus arrival times and optimal transfers so people can move with confidence.
• Scope: Start with the routing context (routes, stops, topology), then add prediction (ETA probability) and ingestion (public feeds → DB).

Tech Stack

• Kotlin 2.x, Spring Boot 3.5.x, Java 21, Gradle (Kotlin DSL)
• MariaDB, Flyway
• DDD + Hexagonal (Ports & Adapters)

Architecture

• Layers: api → application → domain ← infrastructure
• Domain: pure Kotlin, framework-agnostic
• Ports: inbound use cases, outbound repositories/clients
• Adapters: hide technical details (JPA/HTTP/messaging) behind ports

Key classes (routing context):

• Domain: Route, RouteId, GetRouteUseCase, RouteRepository
• Application: GetRouteService (transaction boundaries)
• API: RouteController, RouteResponse
• Infrastructure (JPA): RouteJpaEntity, RouteJpaRepository, RouteRepositoryAdapter, RoutePersistenceMapper

Repository layout (backend/):

• domain/ — aggregates, value objects, ports
• application/ — services/use cases
• interfaces/ — controllers and API DTOs
• infrastructure/ — adapters (JPA), mappers
• resources/db/migration/ — Flyway SQL (V1__init_route.sql)

Configuration & Profiles

• local: application-local.yml (Flyway enabled). Use .env.local:

  DB_URL=jdbc:mariadb://localhost:3306/bustime
  DB_USERNAME=root
  DB_PASSWORD=your_password
  PORT=8080
  

• test: application-test.yml disables DataSource, JPA repositories, and Flyway for fast context load tests
• prod: environment-driven, Flyway enabled

Database & Migrations

• Migrations live in backend/src/main/resources/db/migration/
• Initial schema: V1__init_route.sql creates table route
• Flyway runs automatically on startup (after DataSource, before JPA)

Run Locally

1. Start MariaDB and create database bustime
2. Create backend/.env.local as above
3. Start the app:

   ./gradlew -p backend bootRun --args='--spring.profiles.active=local'
   

4. Sample request:

   curl -i http://localhost:8080/api/v1/routes/100
   

Testing

• Unit tests: JUnit 5, MockK
• Run:

  ./gradlew -p backend test
  

• Future: add a Testcontainers profile for JPA integration tests (with Flyway)

Roadmap

• Ingestion: public transit feeds → normalized schema
• Prediction: ETA probabilistic models with confidence bands
• API: route search, stop arrivals, multi-leg connection suggestions
• Observability: tracing and metrics (p95 latency, error rate)
• Security: Spring Security, problem+json error responses

Contribution & Conventions

• Code in English. Functions are short and single-purpose; prefer early return.
• Naming: *Controller, *Service, *Repository, *Mapper, *Client; *Command, *Query, *Event.

References

• Spring Boot + Flyway: https://docs.spring.io/spring-boot/reference/data/sql.html#data.sql.migration.flyway
• Flyway Docs: https://documentation.flywaydb.org/
• Externalized Config: https://docs.spring.io/spring-boot/reference/features/external-config.html
• Spring Data JPA: https://docs.spring.io/spring-data/jpa/reference/