feat: Add combined track functionality with repository and service layers

- Introduced CombinedTrackModel, CombinedTrackCreate, and CombinedTrackRepository for managing combined tracks.
- Implemented logic to create combined tracks based on existing tracks between two stations.
- Added methods to check for existing combined tracks and retrieve constituent track IDs.
- Enhanced TrackModel and TrackRepository to support OSM ID and track updates.
- Created migration scripts for adding combined tracks table and OSM ID to tracks.
- Updated services and API endpoints to handle combined track operations.
- Added tests for combined track creation, repository methods, and API interactions.

backend/Dockerfile

@@ -25,7 +25,7 @@ EXPOSE 8000
 
 # Initialize database with demo data if INIT_DEMO_DB is set
 CMD ["sh", "-c", "\
-    export PYTHONPATH=/app && \
+    export PYTHONPATH=/app/backend && \
     echo 'Waiting for database...' && \
     while ! pg_isready -h db -p 5432 -U railgame >/dev/null 2>&1; do sleep 1; done && \
     echo 'Database is ready!' && \

backend/alembic.ini

@@ -1,6 +1,6 @@
 [alembic]
 script_location = migrations
-sqlalchemy.url = postgresql+psycopg://railgame:railgame@localhost:5432/railgame
+sqlalchemy.url = postgresql+psycopg://railgame:railgame@localhost:5432/railgame_dev
 
 [loggers]
 keys = root,sqlalchemy,alembic

backend/app/api/__init__.py

@@ -4,9 +4,11 @@ from backend.app.api.auth import router as auth_router
 from backend.app.api.health import router as health_router
 from backend.app.api.network import router as network_router
 from backend.app.api.stations import router as stations_router
+from backend.app.api.tracks import router as tracks_router
 
 router = APIRouter()
 router.include_router(health_router, tags=["health"])
 router.include_router(auth_router)
 router.include_router(network_router)
 router.include_router(stations_router)
+router.include_router(tracks_router)

backend/app/api/tracks.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from backend.app.api.deps import get_current_user, get_db
+from backend.app.models import (
+    CombinedTrackModel,
+    TrackCreate,
+    TrackUpdate,
+    TrackModel,
+    UserPublic,
+)
+from backend.app.services.combined_tracks import (
+    create_combined_track,
+    get_combined_track,
+    list_combined_tracks,
+)
+from backend.app.services.tracks import (
+    create_track,
+    delete_track,
+    regenerate_combined_tracks,
+    update_track,
+    get_track,
+    list_tracks,
+)
+
+router = APIRouter(prefix="/tracks", tags=["tracks"])
+
+
+@router.get("", response_model=list[TrackModel])
+def read_combined_tracks(
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> list[TrackModel]:
+    """Return all base tracks."""
+    return list_tracks(db)
+
+
+@router.get("/combined", response_model=list[CombinedTrackModel])
+def read_combined_tracks_combined(
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> list[CombinedTrackModel]:
+    return list_combined_tracks(db)
+
+
+@router.get("/{track_id}", response_model=TrackModel)
+def read_track(
+    track_id: str,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> TrackModel:
+    track = get_track(db, track_id)
+    if track is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Track {track_id} not found",
+        )
+    return track
+
+
+@router.get("/combined/{combined_track_id}", response_model=CombinedTrackModel)
+def read_combined_track(
+    combined_track_id: str,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> CombinedTrackModel:
+    combined_track = get_combined_track(db, combined_track_id)
+    if combined_track is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Combined track {combined_track_id} not found",
+        )
+    return combined_track
+
+
+@router.post("", response_model=TrackModel, status_code=status.HTTP_201_CREATED)
+def create_track_endpoint(
+    payload: TrackCreate,
+    regenerate: bool = False,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> TrackModel:
+    try:
+        track = create_track(db, payload)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+
+    if regenerate:
+        regenerate_combined_tracks(
+            db, [track.start_station_id, track.end_station_id])
+
+    return track
+
+
+@router.post(
+    "/combined",
+    response_model=CombinedTrackModel,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a combined track between two stations using pathfinding",
+)
+def create_combined_track_endpoint(
+    start_station_id: str,
+    end_station_id: str,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> CombinedTrackModel:
+    combined_track = create_combined_track(
+        db, start_station_id, end_station_id)
+    if combined_track is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Could not create combined track: no path exists between stations or track already exists",
+        )
+    return combined_track
+
+
+@router.put("/{track_id}", response_model=TrackModel)
+def update_track_endpoint(
+    track_id: str,
+    payload: TrackUpdate,
+    regenerate: bool = False,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> TrackModel:
+    track = update_track(db, track_id, payload)
+    if track is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Track {track_id} not found",
+        )
+    if regenerate:
+        regenerate_combined_tracks(
+            db, [track.start_station_id, track.end_station_id])
+    return track
+
+
+@router.delete("/{track_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_track_endpoint(
+    track_id: str,
+    regenerate: bool = False,
+    _: UserPublic = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> None:
+    deleted = delete_track(db, track_id, regenerate=regenerate)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Track {track_id} not found",
+        )

backend/app/db/models.py

@@ -41,11 +41,14 @@ class User(Base, TimestampMixin):
     id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
     )
-    username: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
-    email: Mapped[str | None] = mapped_column(String(255), unique=True, nullable=True)
+    username: Mapped[str] = mapped_column(
+        String(64), unique=True, nullable=False)
+    email: Mapped[str | None] = mapped_column(
+        String(255), unique=True, nullable=True)
     full_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
     password_hash: Mapped[str] = mapped_column(String(256), nullable=False)
-    role: Mapped[str] = mapped_column(String(32), nullable=False, default="player")
+    role: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="player")
     preferences: Mapped[str | None] = mapped_column(Text, nullable=True)
 
 
@@ -62,12 +65,50 @@ class Station(Base, TimestampMixin):
         Geometry(geometry_type="POINT", srid=4326), nullable=False
     )
     elevation_m: Mapped[float | None] = mapped_column(Float, nullable=True)
-    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    is_active: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True)
 
 
 class Track(Base, TimestampMixin):
     __tablename__ = "tracks"
 
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    osm_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    start_station_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("stations.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    end_station_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("stations.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    length_meters: Mapped[float | None] = mapped_column(
+        Numeric(10, 2), nullable=True)
+    max_speed_kph: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    is_bidirectional: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True
+    )
+    status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="planned")
+    track_geometry: Mapped[str] = mapped_column(
+        Geometry(geometry_type="LINESTRING", srid=4326), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "start_station_id", "end_station_id", name="uq_tracks_station_pair"
+        ),
+    )
+
+
+class CombinedTrack(Base, TimestampMixin):
+    __tablename__ = "combined_tracks"
+
     id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
     )
@@ -82,19 +123,25 @@ class Track(Base, TimestampMixin):
         ForeignKey("stations.id", ondelete="RESTRICT"),
         nullable=False,
     )
-    length_meters: Mapped[float | None] = mapped_column(Numeric(10, 2), nullable=True)
+    length_meters: Mapped[float | None] = mapped_column(
+        Numeric(10, 2), nullable=True)
     max_speed_kph: Mapped[int | None] = mapped_column(Integer, nullable=True)
     is_bidirectional: Mapped[bool] = mapped_column(
         Boolean, nullable=False, default=True
     )
-    status: Mapped[str] = mapped_column(String(32), nullable=False, default="planned")
-    track_geometry: Mapped[str] = mapped_column(
+    status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="planned")
+    combined_geometry: Mapped[str] = mapped_column(
         Geometry(geometry_type="LINESTRING", srid=4326), nullable=False
     )
+    # JSON array of constituent track IDs
+    constituent_track_ids: Mapped[str] = mapped_column(
+        Text, nullable=False
+    )
 
     __table_args__ = (
         UniqueConstraint(
-            "start_station_id", "end_station_id", name="uq_tracks_station_pair"
+            "start_station_id", "end_station_id", name="uq_combined_tracks_station_pair"
         ),
     )
 
@@ -105,7 +152,8 @@ class Train(Base, TimestampMixin):
     id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
     )
-    designation: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
+    designation: Mapped[str] = mapped_column(
+        String(64), nullable=False, unique=True)
     operator_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL")
     )

backend/app/models/__init__.py

@@ -8,11 +8,14 @@ from .auth import (
     UserPublic,
 )
 from .base import (
+    CombinedTrackCreate,
+    CombinedTrackModel,
     StationCreate,
     StationModel,
     StationUpdate,
     TrackCreate,
     TrackModel,
+    TrackUpdate,
     TrainCreate,
     TrainModel,
     TrainScheduleCreate,
@@ -33,9 +36,12 @@ __all__ = [
     "StationUpdate",
     "TrackCreate",
     "TrackModel",
+    "TrackUpdate",
     "TrainScheduleCreate",
     "TrainCreate",
     "TrainModel",
     "UserCreate",
     "to_camel",
+    "CombinedTrackCreate",
+    "CombinedTrackModel",
 ]

backend/app/models/base.py

@@ -51,13 +51,24 @@ class StationModel(IdentifiedModel[str]):
 class TrackModel(IdentifiedModel[str]):
     start_station_id: str
     end_station_id: str
-    length_meters: float
-    max_speed_kph: float
+    length_meters: float | None = None
+    max_speed_kph: float | None = None
     status: str | None = None
     is_bidirectional: bool = True
     coordinates: list[tuple[float, float]] = Field(default_factory=list)
 
 
+class CombinedTrackModel(IdentifiedModel[str]):
+    start_station_id: str
+    end_station_id: str
+    length_meters: float | None = None
+    max_speed_kph: int | None = None
+    status: str | None = None
+    is_bidirectional: bool = True
+    coordinates: list[tuple[float, float]] = Field(default_factory=list)
+    constituent_track_ids: list[str] = Field(default_factory=list)
+
+
 class TrainModel(IdentifiedModel[str]):
     designation: str
     capacity: int
@@ -89,6 +100,31 @@ class TrackCreate(CamelModel):
     start_station_id: str
     end_station_id: str
     coordinates: Sequence[tuple[float, float]]
+    osm_id: str | None = None
+    name: str | None = None
+    length_meters: float | None = None
+    max_speed_kph: int | None = None
+    is_bidirectional: bool = True
+    status: str = "planned"
+
+
+class TrackUpdate(CamelModel):
+    start_station_id: str | None = None
+    end_station_id: str | None = None
+    coordinates: Sequence[tuple[float, float]] | None = None
+    osm_id: str | None = None
+    name: str | None = None
+    length_meters: float | None = None
+    max_speed_kph: int | None = None
+    is_bidirectional: bool | None = None
+    status: str | None = None
+
+
+class CombinedTrackCreate(CamelModel):
+    start_station_id: str
+    end_station_id: str
+    coordinates: Sequence[tuple[float, float]]
+    constituent_track_ids: list[str]
     name: str | None = None
     length_meters: float | None = None
     max_speed_kph: int | None = None

backend/app/repositories/__init__.py

@@ -2,6 +2,7 @@
 
 from backend.app.repositories.stations import StationRepository
 from backend.app.repositories.tracks import TrackRepository
+from backend.app.repositories.combined_tracks import CombinedTrackRepository
 from backend.app.repositories.train_schedules import TrainScheduleRepository
 from backend.app.repositories.trains import TrainRepository
 from backend.app.repositories.users import UserRepository
@@ -10,6 +11,7 @@ __all__ = [
     "StationRepository",
     "TrainScheduleRepository",
     "TrackRepository",
+    "CombinedTrackRepository",
     "TrainRepository",
     "UserRepository",
 ]

backend/app/repositories/combined_tracks.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import json
+from uuid import UUID
+
+import sqlalchemy as sa
+from geoalchemy2.elements import WKTElement
+from sqlalchemy.orm import Session
+
+from backend.app.db.models import CombinedTrack
+from backend.app.models import CombinedTrackCreate
+from backend.app.repositories.base import BaseRepository
+
+
+class CombinedTrackRepository(BaseRepository[CombinedTrack]):
+    model = CombinedTrack
+
+    def __init__(self, session: Session) -> None:
+        super().__init__(session)
+
+    def list_all(self) -> list[CombinedTrack]:
+        statement = sa.select(self.model)
+        return list(self.session.scalars(statement))
+
+    def exists_between_stations(self, start_station_id: str, end_station_id: str) -> bool:
+        """Check if a combined track already exists between two stations."""
+        statement = sa.select(sa.exists().where(
+            sa.and_(
+                self.model.start_station_id == start_station_id,
+                self.model.end_station_id == end_station_id
+            )
+        ))
+        return bool(self.session.scalar(statement))
+
+    def get_constituent_track_ids(self, combined_track: CombinedTrack) -> list[str]:
+        """Extract constituent track IDs from a combined track."""
+        try:
+            return json.loads(combined_track.constituent_track_ids)
+        except (json.JSONDecodeError, TypeError):
+            return []
+
+    @staticmethod
+    def _ensure_uuid(value: UUID | str) -> UUID:
+        if isinstance(value, UUID):
+            return value
+        return UUID(str(value))
+
+    @staticmethod
+    def _line_string(coordinates: list[tuple[float, float]]) -> WKTElement:
+        if len(coordinates) < 2:
+            raise ValueError(
+                "Combined track geometry requires at least two coordinate pairs")
+        parts = [f"{lon} {lat}" for lat, lon in coordinates]
+        return WKTElement(f"LINESTRING({', '.join(parts)})", srid=4326)
+
+    def create(self, data: CombinedTrackCreate) -> CombinedTrack:
+        coordinates = list(data.coordinates)
+        geometry = self._line_string(coordinates)
+        constituent_track_ids_json = json.dumps(data.constituent_track_ids)
+        
+        combined_track = CombinedTrack(
+            name=data.name,
+            start_station_id=self._ensure_uuid(data.start_station_id),
+            end_station_id=self._ensure_uuid(data.end_station_id),
+            length_meters=data.length_meters,
+            max_speed_kph=data.max_speed_kph,
+            is_bidirectional=data.is_bidirectional,
+            status=data.status,
+            combined_geometry=geometry,
+            constituent_track_ids=constituent_track_ids_json,
+        )
+        self.session.add(combined_track)
+        return combined_track

backend/app/repositories/tracks.py

@@ -7,7 +7,7 @@ from geoalchemy2.elements import WKTElement
 from sqlalchemy.orm import Session
 
 from backend.app.db.models import Track
-from backend.app.models import TrackCreate
+from backend.app.models import TrackCreate, TrackUpdate
 from backend.app.repositories.base import BaseRepository
 
 
@@ -21,6 +21,102 @@ class TrackRepository(BaseRepository[Track]):
         statement = sa.select(self.model)
         return list(self.session.scalars(statement))
 
+    def exists_by_osm_id(self, osm_id: str) -> bool:
+        statement = sa.select(sa.exists().where(self.model.osm_id == osm_id))
+        return bool(self.session.scalar(statement))
+
+    def find_path_between_stations(self, start_station_id: str, end_station_id: str) -> list[Track] | None:
+        """Find the shortest path between two stations using existing tracks.
+
+        Returns a list of tracks that form the path, or None if no path exists.
+        """
+        # Build adjacency list: station -> list of (neighbor_station, track)
+        adjacency = self._build_track_graph()
+
+        if start_station_id not in adjacency or end_station_id not in adjacency:
+            return None
+
+        # BFS to find shortest path
+        from collections import deque
+
+        # (current_station, path_so_far)
+        queue = deque([(start_station_id, [])])
+        visited = set([start_station_id])
+
+        while queue:
+            current_station, path = queue.popleft()
+
+            if current_station == end_station_id:
+                return path
+
+            for neighbor, track in adjacency[current_station]:
+                if neighbor not in visited:
+                    visited.add(neighbor)
+                    queue.append((neighbor, path + [track]))
+
+        return None  # No path found
+
+    def _build_track_graph(self) -> dict[str, list[tuple[str, Track]]]:
+        """Build a graph representation of tracks: station -> [(neighbor_station, track), ...]"""
+        tracks = self.list_all()
+        graph = {}
+
+        for track in tracks:
+            start_id = str(track.start_station_id)
+            end_id = str(track.end_station_id)
+
+            # Add bidirectional edges (assuming tracks are bidirectional)
+            if start_id not in graph:
+                graph[start_id] = []
+            if end_id not in graph:
+                graph[end_id] = []
+
+            graph[start_id].append((end_id, track))
+            graph[end_id].append((start_id, track))
+
+        return graph
+
+    def combine_track_geometries(self, tracks: list[Track]) -> list[tuple[float, float]]:
+        """Combine the geometries of multiple tracks into a single coordinate sequence.
+
+        Assumes tracks are in order and form a continuous path.
+        """
+        if not tracks:
+            return []
+
+        combined_coords = []
+
+        for i, track in enumerate(tracks):
+            # Extract coordinates from track geometry
+            coords = self._extract_coordinates_from_track(track)
+
+            if i == 0:
+                # First track: add all coordinates
+                combined_coords.extend(coords)
+            else:
+                # Subsequent tracks: skip the first coordinate (shared with previous track)
+                combined_coords.extend(coords[1:])
+
+        return combined_coords
+
+    def _extract_coordinates_from_track(self, track: Track) -> list[tuple[float, float]]:
+        """Extract coordinate list from a track's geometry."""
+        # Convert WKT string to WKTElement, then to shapely geometry
+        from geoalchemy2.elements import WKTElement
+        from geoalchemy2.shape import to_shape
+
+        try:
+            wkt_element = WKTElement(track.track_geometry)
+            geom = to_shape(wkt_element)
+            if hasattr(geom, 'coords'):
+                # For LineString, coords returns [(x, y), ...] where x=lon, y=lat
+                # Convert to (lat, lon)
+                return [(coord[1], coord[0]) for coord in geom.coords]
+        except Exception:
+            pass
+
+        return []
+
     @staticmethod
     def _ensure_uuid(value: UUID | str) -> UUID:
         if isinstance(value, UUID):
@@ -30,7 +126,8 @@ class TrackRepository(BaseRepository[Track]):
     @staticmethod
     def _line_string(coordinates: list[tuple[float, float]]) -> WKTElement:
         if len(coordinates) < 2:
-            raise ValueError("Track geometry requires at least two coordinate pairs")
+            raise ValueError(
+                "Track geometry requires at least two coordinate pairs")
         parts = [f"{lon} {lat}" for lat, lon in coordinates]
         return WKTElement(f"LINESTRING({', '.join(parts)})", srid=4326)
 
@@ -38,6 +135,7 @@ class TrackRepository(BaseRepository[Track]):
         coordinates = list(data.coordinates)
         geometry = self._line_string(coordinates)
         track = Track(
+            osm_id=data.osm_id,
             name=data.name,
             start_station_id=self._ensure_uuid(data.start_station_id),
             end_station_id=self._ensure_uuid(data.end_station_id),
@@ -49,3 +147,26 @@ class TrackRepository(BaseRepository[Track]):
         )
         self.session.add(track)
         return track
+
+    def update(self, track: Track, payload: TrackUpdate) -> Track:
+        if payload.start_station_id is not None:
+            track.start_station_id = self._ensure_uuid(
+                payload.start_station_id)
+        if payload.end_station_id is not None:
+            track.end_station_id = self._ensure_uuid(payload.end_station_id)
+        if payload.coordinates is not None:
+            track.track_geometry = self._line_string(
+                list(payload.coordinates))  # type: ignore[assignment]
+        if payload.osm_id is not None:
+            track.osm_id = payload.osm_id
+        if payload.name is not None:
+            track.name = payload.name
+        if payload.length_meters is not None:
+            track.length_meters = payload.length_meters
+        if payload.max_speed_kph is not None:
+            track.max_speed_kph = payload.max_speed_kph
+        if payload.is_bidirectional is not None:
+            track.is_bidirectional = payload.is_bidirectional
+        if payload.status is not None:
+            track.status = payload.status
+        return track

backend/app/services/combined_tracks.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+"""Application services for combined track operations."""
+
+from sqlalchemy.orm import Session
+
+from backend.app.models import CombinedTrackCreate, CombinedTrackModel
+from backend.app.repositories import CombinedTrackRepository, TrackRepository
+
+
+def create_combined_track(
+    session: Session, start_station_id: str, end_station_id: str
+) -> CombinedTrackModel | None:
+    """Create a combined track between two stations using pathfinding.
+
+    Returns the created combined track, or None if no path exists or
+    a combined track already exists between these stations.
+    """
+    combined_track_repo = CombinedTrackRepository(session)
+    track_repo = TrackRepository(session)
+
+    # Check if combined track already exists
+    if combined_track_repo.exists_between_stations(start_station_id, end_station_id):
+        return None
+
+    # Find path between stations
+    path_tracks = track_repo.find_path_between_stations(
+        start_station_id, end_station_id)
+    if not path_tracks:
+        return None
+
+    # Combine geometries
+    combined_coords = track_repo.combine_track_geometries(path_tracks)
+    if len(combined_coords) < 2:
+        return None
+
+    # Calculate total length
+    total_length = sum(track.length_meters or 0 for track in path_tracks)
+
+    # Get max speed (use the minimum speed of all tracks)
+    max_speeds = [
+        track.max_speed_kph for track in path_tracks if track.max_speed_kph]
+    max_speed = min(max_speeds) if max_speeds else None
+
+    # Get constituent track IDs
+    constituent_track_ids = [str(track.id) for track in path_tracks]
+
+    # Create combined track
+    create_data = CombinedTrackCreate(
+        start_station_id=start_station_id,
+        end_station_id=end_station_id,
+        coordinates=combined_coords,
+        constituent_track_ids=constituent_track_ids,
+        length_meters=total_length if total_length > 0 else None,
+        max_speed_kph=max_speed,
+        status="operational",
+    )
+
+    combined_track = combined_track_repo.create(create_data)
+    session.commit()
+
+    return CombinedTrackModel.model_validate(combined_track)
+
+
+def get_combined_track(session: Session, combined_track_id: str) -> CombinedTrackModel | None:
+    """Get a combined track by ID."""
+    try:
+        combined_track_repo = CombinedTrackRepository(session)
+        combined_track = combined_track_repo.get(combined_track_id)
+        return CombinedTrackModel.model_validate(combined_track)
+    except LookupError:
+        return None
+
+
+def list_combined_tracks(session: Session) -> list[CombinedTrackModel]:
+    """List all combined tracks."""
+    combined_track_repo = CombinedTrackRepository(session)
+    combined_tracks = combined_track_repo.list_all()
+    return [CombinedTrackModel.model_validate(ct) for ct in combined_tracks]

backend/app/services/tracks.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+"""Service layer for primary track management operations."""
+
+from typing import Iterable
+
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from backend.app.models import CombinedTrackModel, TrackCreate, TrackModel, TrackUpdate
+from backend.app.repositories import CombinedTrackRepository, TrackRepository
+
+
+def list_tracks(session: Session) -> list[TrackModel]:
+    repo = TrackRepository(session)
+    tracks = repo.list_all()
+    return [TrackModel.model_validate(track) for track in tracks]
+
+
+def get_track(session: Session, track_id: str) -> TrackModel | None:
+    repo = TrackRepository(session)
+    track = repo.get(track_id)
+    if track is None:
+        return None
+    return TrackModel.model_validate(track)
+
+
+def create_track(session: Session, payload: TrackCreate) -> TrackModel:
+    repo = TrackRepository(session)
+    try:
+        track = repo.create(payload)
+        session.commit()
+    except IntegrityError as exc:
+        session.rollback()
+        raise ValueError(
+            "Track with the same station pair already exists") from exc
+
+    return TrackModel.model_validate(track)
+
+
+def update_track(session: Session, track_id: str, payload: TrackUpdate) -> TrackModel | None:
+    repo = TrackRepository(session)
+    track = repo.get(track_id)
+    if track is None:
+        return None
+
+    repo.update(track, payload)
+    session.commit()
+
+    return TrackModel.model_validate(track)
+
+
+def delete_track(session: Session, track_id: str, regenerate: bool = False) -> bool:
+    repo = TrackRepository(session)
+    track = repo.get(track_id)
+    if track is None:
+        return False
+
+    start_station_id = str(track.start_station_id)
+    end_station_id = str(track.end_station_id)
+
+    session.delete(track)
+    session.commit()
+
+    if regenerate:
+        regenerate_combined_tracks(session, [start_station_id, end_station_id])
+
+    return True
+
+
+def regenerate_combined_tracks(session: Session, station_ids: Iterable[str]) -> list[CombinedTrackModel]:
+    combined_repo = CombinedTrackRepository(session)
+
+    station_id_set = set(station_ids)
+    if not station_id_set:
+        return []
+
+    # Remove combined tracks touching these stations
+    for combined in combined_repo.list_all():
+        if {str(combined.start_station_id), str(combined.end_station_id)} & station_id_set:
+            session.delete(combined)
+
+    session.commit()
+
+    # Rebuild combined tracks between affected station pairs
+    from backend.app.services.combined_tracks import create_combined_track
+
+    regenerated: list[CombinedTrackModel] = []
+    station_list = list(station_id_set)
+    for i in range(len(station_list)):
+        for j in range(i + 1, len(station_list)):
+            result = create_combined_track(
+                session, station_list[i], station_list[j])
+            if result is not None:
+                regenerated.append(result)
+    return regenerated
+
+
+__all__ = [
+    "list_tracks",
+    "get_track",
+    "create_track",
+    "update_track",
+    "delete_track",
+    "regenerate_combined_tracks",
+]

backend/migrations/versions/63d02d67b39e_add_osm_id_to_tracks.py

@@ -0,0 +1,19 @@
+"""Template for new Alembic migration scripts."""
+
+from __future__ import annotations
+import sqlalchemy as sa
+from alembic import op
+
+revision = '63d02d67b39e'
+down_revision = '20251011_01'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column('tracks', sa.Column(
+        'osm_id', sa.String(length=32), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column('tracks', 'osm_id')

backend/migrations/versions/e7d4bb03da04_add_combined_tracks_table.py

@@ -0,0 +1,75 @@
+"""Template for new Alembic migration scripts."""
+
+from __future__ import annotations
+from sqlalchemy.dialects import postgresql
+from geoalchemy2.types import Geometry
+import sqlalchemy as sa
+from alembic import op
+
+revision = 'e7d4bb03da04'
+down_revision = '63d02d67b39e'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "combined_tracks",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column("name", sa.String(length=128), nullable=True),
+        sa.Column("start_station_id", postgresql.UUID(
+            as_uuid=True), nullable=False),
+        sa.Column("end_station_id", postgresql.UUID(
+            as_uuid=True), nullable=False),
+        sa.Column("length_meters", sa.Numeric(10, 2), nullable=True),
+        sa.Column("max_speed_kph", sa.Integer(), nullable=True),
+        sa.Column(
+            "is_bidirectional",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("true"),
+        ),
+        sa.Column(
+            "status", sa.String(length=32), nullable=False, server_default="planned"
+        ),
+        sa.Column(
+            "combined_geometry",
+            Geometry(geometry_type="LINESTRING", srid=4326),
+            nullable=False,
+        ),
+        sa.Column("constituent_track_ids", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("timezone('utc', now())"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("timezone('utc', now())"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["start_station_id"], ["stations.id"], ondelete="RESTRICT"
+        ),
+        sa.ForeignKeyConstraint(
+            ["end_station_id"], ["stations.id"], ondelete="RESTRICT"
+        ),
+        sa.UniqueConstraint(
+            "start_station_id", "end_station_id", name="uq_combined_tracks_station_pair"
+        ),
+    )
+    op.create_index(
+        "ix_combined_tracks_geometry", "combined_tracks", ["combined_geometry"], postgresql_using="gist"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_combined_tracks_geometry", table_name="combined_tracks")
+    op.drop_table("combined_tracks")

backend/scripts/tracks_load.py

@@ -22,6 +22,7 @@ from backend.app.repositories import StationRepository, TrackRepository
 @dataclass(slots=True)
 class ParsedTrack:
     coordinates: list[tuple[float, float]]
+    osm_id: str | None = None
     name: str | None = None
     length_meters: float | None = None
     max_speed_kph: float | None = None
@@ -97,7 +98,8 @@ def _parse_track_entries(entries: Iterable[Mapping[str, Any]]) -> list[ParsedTra
         processed_coordinates: list[tuple[float, float]] = []
         for pair in coordinates:
             if not isinstance(pair, Sequence) or len(pair) != 2:
-                raise ValueError(f"Invalid coordinate pair {pair!r} in track entry")
+                raise ValueError(
+                    f"Invalid coordinate pair {pair!r} in track entry")
             lat, lon = pair
             processed_coordinates.append((float(lat), float(lon)))
 
@@ -106,10 +108,12 @@ def _parse_track_entries(entries: Iterable[Mapping[str, Any]]) -> list[ParsedTra
         max_speed = _safe_float(entry.get("maxSpeedKph"))
         status = entry.get("status", "operational")
         is_bidirectional = entry.get("isBidirectional", True)
+        osm_id = entry.get("osmId")
 
         parsed.append(
             ParsedTrack(
                 coordinates=processed_coordinates,
+                osm_id=str(osm_id) if osm_id else None,
                 name=str(name) if name else None,
                 length_meters=length,
                 max_speed_kph=max_speed,
@@ -133,6 +137,12 @@ def load_tracks(tracks: Iterable[ParsedTrack], commit: bool = True) -> int:
         }
 
         for track_data in tracks:
+            # Skip if track with this OSM ID already exists
+            if track_data.osm_id and track_repo.exists_by_osm_id(track_data.osm_id):
+                print(
+                    f"Skipping track {track_data.osm_id} - already exists by OSM ID")
+                continue
+
             start_station = _nearest_station(
                 track_data.coordinates[0],
                 station_index,
@@ -145,13 +155,19 @@ def load_tracks(tracks: Iterable[ParsedTrack], commit: bool = True) -> int:
             )
 
             if not start_station or not end_station:
+                print(
+                    f"Skipping track {track_data.osm_id} - no start/end stations found")
                 continue
 
             if start_station.id == end_station.id:
+                print(
+                    f"Skipping track {track_data.osm_id} - start and end stations are the same")
                 continue
 
             pair = (start_station.id, end_station.id)
             if pair in existing_pairs:
+                print(
+                    f"Skipping track {track_data.osm_id} - station pair {pair} already exists")
                 continue
 
             length = track_data.length_meters or _polyline_length(
@@ -163,6 +179,7 @@ def load_tracks(tracks: Iterable[ParsedTrack], commit: bool = True) -> int:
                 else None
             )
             create_schema = TrackCreate(
+                osm_id=track_data.osm_id,
                 name=track_data.name,
                 start_station_id=start_station.id,
                 end_station_id=end_station.id,
@@ -193,7 +210,8 @@ def _nearest_station(
     best_station: StationRef | None = None
     best_distance = math.inf
     for station in stations:
-        distance = _haversine(coordinate, (station.latitude, station.longitude))
+        distance = _haversine(
+            coordinate, (station.latitude, station.longitude))
         if distance < best_distance:
             best_station = station
             best_distance = distance

backend/tests/test_combined_tracks.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, List
+from uuid import uuid4
+
+import pytest
+
+from backend.app.models import CombinedTrackModel
+from backend.app.repositories.combined_tracks import CombinedTrackRepository
+from backend.app.repositories.tracks import TrackRepository
+from backend.app.services.combined_tracks import create_combined_track
+
+
+@dataclass
+class DummySession:
+    added: List[Any] = field(default_factory=list)
+    scalars_result: List[Any] = field(default_factory=list)
+    scalar_result: Any = None
+    statements: List[Any] = field(default_factory=list)
+    committed: bool = False
+    rolled_back: bool = False
+    closed: bool = False
+
+    def add(self, instance: Any) -> None:
+        self.added.append(instance)
+
+    def add_all(self, instances: list[Any]) -> None:
+        self.added.extend(instances)
+
+    def scalars(self, statement: Any) -> list[Any]:
+        self.statements.append(statement)
+        return list(self.scalars_result)
+
+    def scalar(self, statement: Any) -> Any:
+        self.statements.append(statement)
+        return self.scalar_result
+
+    def flush(
+        self, _objects: list[Any] | None = None
+    ) -> None:  # pragma: no cover - optional
+        return None
+
+    def commit(self) -> None:  # pragma: no cover - optional
+        self.committed = True
+
+    def rollback(self) -> None:  # pragma: no cover - optional
+        self.rolled_back = True
+
+    def close(self) -> None:  # pragma: no cover - optional
+        self.closed = True
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def test_combined_track_model_round_trip() -> None:
+    timestamp = _now()
+    combined_track = CombinedTrackModel(
+        id="combined-track-1",
+        start_station_id="station-1",
+        end_station_id="station-2",
+        length_meters=3000.0,
+        max_speed_kph=100,
+        status="operational",
+        is_bidirectional=True,
+        coordinates=[(52.52, 13.405), (52.6, 13.5), (52.7, 13.6)],
+        constituent_track_ids=["track-1", "track-2"],
+        created_at=timestamp,
+        updated_at=timestamp,
+    )
+    assert combined_track.length_meters == 3000.0
+    assert combined_track.start_station_id != combined_track.end_station_id
+    assert len(combined_track.coordinates) == 3
+    assert len(combined_track.constituent_track_ids) == 2
+
+
+def test_combined_track_repository_create() -> None:
+    """Test creating a combined track through the repository."""
+    session = DummySession()
+    repo = CombinedTrackRepository(session)  # type: ignore[arg-type]
+
+    # Create test data
+    from backend.app.models import CombinedTrackCreate
+
+    create_data = CombinedTrackCreate(
+        start_station_id="550e8400-e29b-41d4-a716-446655440000",
+        end_station_id="550e8400-e29b-41d4-a716-446655440001",
+        coordinates=[(52.52, 13.405), (52.6, 13.5)],
+        constituent_track_ids=["track-1"],
+        length_meters=1500.0,
+        max_speed_kph=120,
+        status="operational",
+    )
+
+    combined_track = repo.create(create_data)
+
+    assert combined_track.start_station_id is not None
+    assert combined_track.end_station_id is not None
+    assert combined_track.length_meters == 1500.0
+    assert combined_track.max_speed_kph == 120
+    assert combined_track.status == "operational"
+    assert session.added and session.added[0] is combined_track
+
+
+def test_combined_track_repository_exists_between_stations() -> None:
+    """Test checking if combined track exists between stations."""
+    session = DummySession()
+    repo = CombinedTrackRepository(session)  # type: ignore[arg-type]
+
+    # Initially should not exist (scalar_result is None by default)
+    assert not repo.exists_between_stations(
+        "550e8400-e29b-41d4-a716-446655440000",
+        "550e8400-e29b-41d4-a716-446655440001"
+    )
+
+    # Simulate existing combined track
+    session.scalar_result = True
+    assert repo.exists_between_stations(
+        "550e8400-e29b-41d4-a716-446655440000",
+        "550e8400-e29b-41d4-a716-446655440001"
+    )
+
+
+def test_combined_track_service_create_no_path() -> None:
+    """Test creating combined track when no path exists."""
+    # Mock session and repositories
+    session = DummySession()
+
+    # Mock TrackRepository to return no path
+    class MockTrackRepository:
+        def __init__(self, session):
+            pass
+
+        def find_path_between_stations(self, start_id, end_id):
+            return None
+
+    # Mock CombinedTrackRepository
+    class MockCombinedTrackRepository:
+        def __init__(self, session):
+            pass
+
+        def exists_between_stations(self, start_id, end_id):
+            return False
+
+    # Patch the service to use mock repositories
+    import backend.app.services.combined_tracks as service_module
+    original_track_repo = service_module.TrackRepository
+    original_combined_repo = service_module.CombinedTrackRepository
+
+    service_module.TrackRepository = MockTrackRepository
+    service_module.CombinedTrackRepository = MockCombinedTrackRepository
+
+    try:
+        result = create_combined_track(
+            session,  # type: ignore[arg-type]
+            "550e8400-e29b-41d4-a716-446655440000",
+            "550e8400-e29b-41d4-a716-446655440001"
+        )
+        assert result is None
+    finally:
+        # Restore original classes
+        service_module.TrackRepository = original_track_repo
+        service_module.CombinedTrackRepository = original_combined_repo

backend/tests/test_tracks_api.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from backend.app.api import tracks as tracks_api
+from backend.app.main import app
+from backend.app.models import CombinedTrackModel, TrackModel
+
+client = TestClient(app)
+
+
+def _track_model(track_id: str = "track-1") -> TrackModel:
+    now = datetime.now(timezone.utc)
+    return TrackModel(
+        id=track_id,
+        start_station_id="station-a",
+        end_station_id="station-b",
+        length_meters=None,
+        max_speed_kph=None,
+        status="planned",
+        coordinates=[(52.5, 13.4), (52.6, 13.5)],
+        is_bidirectional=True,
+        created_at=now,
+        updated_at=now,
+    )
+
+
+def _combined_model(track_id: str = "combined-1") -> CombinedTrackModel:
+    now = datetime.now(timezone.utc)
+    return CombinedTrackModel(
+        id=track_id,
+        start_station_id="station-a",
+        end_station_id="station-b",
+        length_meters=1000,
+        max_speed_kph=120,
+        status="operational",
+        coordinates=[(52.5, 13.4), (52.6, 13.5)],
+        constituent_track_ids=["track-1", "track-2"],
+        is_bidirectional=True,
+        created_at=now,
+        updated_at=now,
+    )
+
+
+def _authenticate() -> str:
+    response = client.post(
+        "/api/auth/login",
+        json={"username": "demo", "password": "railgame123"},
+    )
+    assert response.status_code == 200
+    return response.json()["accessToken"]
+
+
+def test_list_tracks(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    monkeypatch.setattr(tracks_api, "list_tracks", lambda db: [_track_model()])
+
+    response = client.get(
+        "/api/tracks",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert response.status_code == 200
+    payload = response.json()
+    assert isinstance(payload, list)
+    assert payload[0]["id"] == "track-1"
+
+
+def test_get_track_returns_404(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    monkeypatch.setattr(tracks_api, "get_track", lambda db, track_id: None)
+
+    response = client.get(
+        "/api/tracks/not-found",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert response.status_code == 404
+
+
+def test_create_track_calls_service(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    captured: dict[str, Any] = {}
+    payload = {
+        "startStationId": "station-a",
+        "endStationId": "station-b",
+        "coordinates": [[52.5, 13.4], [52.6, 13.5]],
+    }
+
+    def fake_create(db: Any, data: Any) -> TrackModel:
+        assert data.start_station_id == "station-a"
+        captured["payload"] = data
+        return _track_model("track-new")
+
+    monkeypatch.setattr(tracks_api, "create_track", fake_create)
+
+    response = client.post(
+        "/api/tracks",
+        json=payload,
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert response.status_code == 201
+    body = response.json()
+    assert body["id"] == "track-new"
+    assert captured["payload"].end_station_id == "station-b"
+
+
+def test_delete_track_returns_404(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    monkeypatch.setattr(
+        tracks_api, "delete_track", lambda db, tid, regenerate=False: False
+    )
+
+    response = client.delete(
+        "/api/tracks/missing",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert response.status_code == 404
+
+
+def test_delete_track_success(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    seen: dict[str, Any] = {}
+
+    def fake_delete(db: Any, track_id: str, regenerate: bool = False) -> bool:
+        seen["track_id"] = track_id
+        seen["regenerate"] = regenerate
+        return True
+
+    monkeypatch.setattr(tracks_api, "delete_track", fake_delete)
+
+    response = client.delete(
+        "/api/tracks/track-99",
+        params={"regenerate": "true"},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+
+    assert response.status_code == 204
+    assert seen["track_id"] == "track-99"
+    assert seen["regenerate"] is True
+
+
+def test_list_combined_tracks(monkeypatch: pytest.MonkeyPatch) -> None:
+    token = _authenticate()
+    monkeypatch.setattr(
+        tracks_api, "list_combined_tracks", lambda db: [_combined_model()]
+    )
+
+    response = client.get(
+        "/api/tracks/combined",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert response.status_code == 200
+    payload = response.json()
+    assert len(payload) == 1
+    assert payload[0]["id"] == "combined-1"