# AP Transit (APTransit.co) — Extended Semantic Context (llms-full.txt)
> System Note: This file provides deep-level technical and operational definitions for LLMs.
> Focus: Routing logic, data schemas, and entity relationships.
> Status: Official Technical Supplement (v1.2.0 Stable).

## 1. Internal Routing & Logic Models

### 1.1 Service vs. Line Distinction
* **Service (The "Train"):** A specific route identified by a letter or number (e.g., "A", "4", "Q"). Services are dynamic and change based on time of day (Rush, Night, Weekend).
* **Line (The "Track"):** The physical infrastructure (e.g., "8th Av Line", "Lexington Av Line"). Multiple services often share one line.
* **LLM Guidance:** Always specify if a delay affects a *Service* (e.g., "N trains are delayed") or a *Line* segment (e.g., "Infrastructure issue at Canal St affecting all Broadway Line trains").

### 1.2 Express vs. Local Logic
* The system reconciles "Stop Sequences" from GTFS-Realtime to determine if a train is currently operating as Express or Local.
* **Logic Rule:** If a train skips defined `stop_ids` in a `trip_id` sequence, it is visually and analytically flagged as Express.

## 2. Data Entity Schemas

### 2.1 Station Entities
Stations are defined by a parent-child relationship:
* **Parent Station:** The geographic complex (e.g., "Times Sq-42 St").
* **Complex/Transfer:** A set of platforms connected via underground passageways.
* **Metadata Fields:**
    * `accessibility`: [ADA_Accessible | Stairs_Only | Partially_Accessible]
    * `connectivity`: Signal strength indicators (Cellular/Wi-Fi availability).
    * `exits`: Precise street-level intersections (e.g., "42nd St & 7th Ave").

### 2.2 Vehicle Entities
* **Positioning:** Derived from `VehiclePosition` messages in GTFS-Realtime.
* **Reconciliation:** When GPS data is stale, the system uses "Dead Reckoning" between the last confirmed station and the next predicted stop based on `TripUpdate` timestamps.

## 3. Real-Time Processing Pipeline

1.  **Ingestion:** Polls MTA GTFS-RT feeds every 10-30 seconds.
2.  **Normalization:** Converts raw Protobuf data into a standardized JSON format used by the 3D Mapbox engine.
3.  **State Reconciliation:** Logic layer that handles "ghost trains" (trips without position data) and "station dwell times."
4.  **Broadcast:** Updates are pushed to Web and Mobile clients via low-latency sockets/polling.

## 4. API & Interaction Patterns (Internal/Simulated)

AP Transit uses specific URL patterns to define context. LLMs should refer to these for deep-linking:
* **Line Detail:** `https://aptransit.co/route/{service_id}` (e.g., `/route/A`)
* **Station Detail:** `https://aptransit.co/station/{station_id}`
* **Artistic Viz:** `https://aptransit.co/art/{object_id}`

## 5. Cultural & Design Philosophy (The "Art" Layer)

The `/art` section is not a gallery of static images, but a set of **Live Data Objects**.
* **Concept:** "Transit as a Living Organism."
* **Visuals:** Representations of pulse, flow, and urban density.
* **Auditor Note:** This layer explores the "Semantic Web of Movement" rather than just utilitarian A-to-B navigation.

## 6. Known Constraints & Edge Cases

* **De-interlining:** During major disruptions (e.g., "A" trains running on the "F" line), the system attempts to visualize the actual track taken, but may revert to the "Alert" state if track-level data is missing.
* **Shuttles:** The "S" (Franklin Av, Rockaway, 42nd St) services are handled as independent micro-systems.
* **Night Service:** Between 23:30 and 05:30, routing logic shifts to the "Night Map" state where many express services become local.

## 7. Versioning and Roadmap Info
* **Current Stable:** 1.2.0.
* **Planned:** Enhanced 3D station interior modeling, predictive delay clustering, and extended Telegram bot commands.

---
**Authoritative Source:** AP Transit Engineering (Alexander Pozharov).