← Back to Articles
Swords Live

Swords Live V3 Release notes

Published on May 22, 2026

# SwordsLive Release Notes

**Version:** 3.0  
**Release Date:** April 15, 2026  
**Status:** Production Release

---

## Table of Contents

1. [Release Summary](#1-release-summary)
2. [Product Direction](#2-product-direction)
3. [Express Module](#3-express-module)
4. [Housing Module](#4-housing-module)
5. [Swoop Module](#5-swoop-module)
6. [Sionra and Weather](#6-sionra-and-weather)
7. [Live and Sord Chat](#7-live-and-sord-chat)
8. [Posts, Gallery and Home](#8-posts-gallery-and-home)
9. [Administration and Superuser Tools](#9-administration-and-superuser-tools)
10. [Infrastructure and Reliability](#10-infrastructure-and-reliability)

---

## 1. Release Summary

### Executive Summary

SwordsLive V3 turns the platform from a working hyperlocal prototype into a more coherent live awareness tool for Swords.

Version 2.5 proved that local transport, property, civic reporting and AI timetable search could live together in one experience. Version 3 deepens that idea: the product now helps people read what is happening around them in real time, with stronger live bus intelligence, richer map layers, better civic reporting, local planning context, stop-level weather, and operational tools for keeping the system trustworthy.

The core product promise is:

> Open SwordsLive and the town makes more sense.

V3 focuses on three kinds of local value:

- **Immediate value:** live buses, stop ETAs, direction, route overlays, location tracking and weather.
- **Civic value:** verified reports, tree POIs, planning applications and public maintenance visibility.
- **Place value:** housing movement, local stories, gallery images and the accumulated memory of Swords.

### Major Themes

- **Express becomes operationally intelligent:** bus state, direction, trip boundaries, stop visits, trip matching and ETAs now work as a connected enrichment pipeline rather than isolated features.
- **Housing becomes a local change map:** property data is joined by Fingal planning applications, grouped and displayed as a real map layer.
- **Swoop becomes a civic layer:** reports now include a verification gate, category pins, deep links and tree POIs.
- **Weather becomes local context:** Sionra provides stop-level forecasts and a daily AI weather bulletin for the Swords-Dublin corridor.
- **The backend becomes restart-resilient:** critical in-memory state can be snapshotted and restored across deploys.

---

## 2. Product Direction

SwordsLive is not a generic portal. It is a live local awareness tool for Swords.

The product is strongest when it helps a person answer:

- What is happening near me?
- What has changed?
- What should I do next?

V3 keeps the focus on Swords as a specific place. The product value comes from local precision: Swords Express behavior, bus stop weather, Fingal planning feeds, civic issues, tree records, property movement and local stories.

The release direction is practical and emotional at once:

- **Value:** reduce uncertainty for transport, weather, civic reporting and local change.
- **Fun:** make the map rewarding to explore.
- **Meaning:** make the town feel more visible and worth paying attention to.
- **Connection:** connect people to place, and through place to shared civic life.

The product filter is simple: a feature belongs when it makes Swords more readable, more immediate or more actionable.

---

## 3. Express Module

Express remains the daily-use core of SwordsLive.

### Live Bus Tracking

- Swords Express GPS polling writes current bus state to `bus_trip_live_state`.
- `/api/buses` returns current bus location, speed, heading, direction, route, trip match, stop list and last-seen data.
- `/api/journey/:busId` returns enriched journey details for a single bus.
- Bus and stop deep links open the correct map state and panel.

### Direction Observer V2

- DOv2 determines bus direction through corridor geometry rather than stop sequence assumptions.
- Corridors are loaded from the database and evaluated using ITM geometry.
- Per-corridor buffers smooth short-term GPS noise.
- Deadhaul corridors are treated as signals for deadhaul logic without overwriting passenger-service direction.
- A guarded fallback `trip_end` is emitted on direction flip only when a bus is still `in_service` and the normal boundary observer has been silent.

### Run Boundary Observer V1

- Trip start and trip end detection is now handled by geofenced run-boundary rules.
- Supported trip start rules include Abbeyvale, Eden Quay, Highfields, Millers Glen and River Valley.
- Supported trip end rules include Swords Manor and Eden Quay.
- State ownership is explicit:
  - `holding_for_departure` is owned by trip-start boundary rules.
  - `in_service` is owned by trip-start confirmation.
  - `layover` is owned by trip-end boundary rules.
  - `deadhaul` is owned by Deadhaul Observer V2.
- Trip boundary transitions dual-write to live state and signal history for auditability.
- Diagnostic `bo_state_change` events make boundary behavior inspectable.

### Holding-for-Departure Watchdog

- A watchdog recovers buses stuck in `holding_for_departure` when normal boundary transitions fail.
- It fires only after a grace period and only when movement, direction and state conditions indicate a real departure.
- Watchdog actions are logged to `bus_signal_log` for traceability.

### Trip Matcher V5

- Trip matching is now a staged scoring pipeline driven by trip-start and trip-end signals.
- Candidates are nominated at trip start using timetable origin stops.
- Stop visits continuously update candidate scores.
- Forward prediction checks whether the claimed trip remains plausible.
- Completion is triggered by `trip_end` signals, not by schedule expectation.
- Confidence is normalized from coverage, timing, runner-up margin and prediction accuracy.
- Completed trips are written to `bus_trip_daily_matrix` with hard or soft lockout depending on confidence.
- Live state is updated with trip ID, route, description, confidence and a merged scheduled/actual stop timeline.

### Stop Timelines and ETAs

- `BusInfoPanel` now exposes a full ordered stop timeline for matched trips.
- Visited stops show actual arrival time; upcoming stops show scheduled time.
- The Stop ETA Service predicts arrivals for upcoming stops using the Segment Pace Model.
- Bus stop panels can show Sord prediction cards for approaching buses.

### Segment Pace Model and Route Overlay

- The Segment Pace Model builds median stop-to-stop travel times from observed stop visits.
- Observations are grouped by direction and time-of-day band.
- Segments with insufficient data return no prediction rather than guessing.
- `/api/segment-pace-status` exposes a traffic snapshot for route overlays.
- The Express map can color route segments by current pace: free, moderate, heavy or no data.

### Location Experience

- Global location tracking is centralized in `LocationContext`.
- Tracking auto-resumes from `localStorage` when previously enabled.
- Last known position is stored and used to initialize the Express map at the user's location before the first live GPS fix arrives.
- Permission denial clears tracking intent and avoids reload retry loops.

---

## 4. Housing Module

Housing has grown from property visualization into a local change map.

### Property Tracking

- `/api/properties` returns property data within the Swords area.
- Data sources include PPR, Morton and Flanagan, and Flynn Associates.
- For-sale properties include online/offline state where available.
- `PropertySummaryPanel` gives aggregate statistics and links directly into individual property panels.
- `PropertyInfoPanel` supports zoom-to-property map behavior.

### Fingal Planning Overlay

- `/api/planning-applications` returns grouped planning applications for the map.
- Applications are fetched from Fingal County Council's ArcGIS FeatureServer.
- Geometry is fetched in EPSG:2157 and converted through shared geo helpers.
- Planning records are upserted by planning reference.
- Rows are never deleted; stale feed rows are marked as no longer current.
- Status is normalized into categories such as `pending`, `on_appeal`, `decided`, `withdrawn`, `archived` and `unknown`.

### Planning Grouping

- Related applications are grouped at response time, not persisted.
- Grouping is based on same applicant plus proximity.
- Applications without enough grouping data become singleton groups.
- This keeps the model flexible without requiring schema changes when grouping logic evolves.

### Planning Frontend

- The `/housing` map has a planning overlay toggle.
- When enabled, the frontend fetches planning applications by viewport bounding box.
- Planning markers use status-colored teardrop pins.
- Grouped applications show count badges.
- `PlanningInfoPanel` displays reference, status, description, address, applicant, dates, related applications and the Fingal portal link.
- `PropertySummaryPanel` now includes planning context, including recent applications.

---

## 5. Swoop Module

Swoop has grown into a civic map layer for Swords.

### Civic Reporting

- `/api/swoop/requests` supports public report retrieval and draft creation.
- Photo uploads support JPEG/PNG and EXIF GPS extraction.
- Reports can deep-link through `?id=`.
- Map markers are category-specific pins using the shared category source of truth.
- Reports remain hidden until content verification is completed.

### Content Verification Gate

- New reports are stored as hidden and unverified.
- Submitters with an email address receive a signed verification link.
- Verification links expire after 48 hours.
- A confirmed report becomes visible and triggers the FCC PDF email.
- Reports submitted without an email remain stored but require manual/admin intervention.
- The `/verify-content` page handles success, expired-token and invalid-token states.

### Category Pins

- Civic markers are SVG teardrop pins built from category color and icon.
- Supported categories include graffiti, leaks and drainage, litter, road/path defects, street lighting, tree and grass maintenance, and other.
- Category metadata is centralized in `frontend/shared/swoopCategories.ts`.

### Tree POIs

- Swoop now includes a separate POI layer for Irish deciduous trees in Swords.
- Tree records live in `swoop_poi` with `type = 'tree'`.
- Tree metadata includes species name, height and notes.
- Tree markers use a custom SVG icon and open a tree detail panel.

### Map Controls

- Civic reports and tree POIs can be toggled independently.
- Turning a layer off removes its markers immediately without a backend call.
- Marker lifecycle is managed through separate refs and effects for report markers and tree markers.

---

## 6. Sionra and Weather

Sionra gives SwordsLive local environmental context.

### Stop-Level Forecasts

- `/api/sion/forecast` returns 24-hour forecast data for bus stop grid points.
- Weather data is sourced from Met Eireann HARMONIE and stored in `sionra_meteireann_harmonie`.
- Forecast fields include temperature, wind, gusts, humidity, pressure, cloudiness, dew point, precipitation, precipitation probability, radiation and weather symbol.
- `/api/sion/grid` exposes grid specification for the frontend overlay.
- `/api/sion/icons` exposes the available weather icon set.

### Sion Map

- `/sion` displays bus stops with temperature and weather icons.
- `SionInfoPanel` presents detailed conditions in a metric grid.
- A 7-hour forecast slider updates metrics and symbols.
- OSI grid overlay logic is driven by config rather than hardcoded geometry.

### Weather Bulletin

- `/api/weather/swords-forecast` returns a daily Swords-Dublin corridor forecast.
- Forecasts are generated from Sionra data for Swords and Dublin reference stops.
- The bulletin is generated as plain text with morning, afternoon, evening and what-to-wear sections.
- A scheduler pre-generates the bulletin around 06:00 Europe/Dublin.
- Home and panel experiences share the same query key to avoid duplicate fetches.

---

## 7. Live and Sord Chat

Sord Chat remains the conversational access layer for timetable and local transport questions.

### RAG Pipeline

- `/api/chat-v2` accepts user messages with session context.
- Intent parsing identifies transport questions, origin, destination, route, time intent and favorites usage.
- Entity resolution uses local embeddings and pgvector search against bus stop data.
- Ambiguous stop matches can trigger clarification.
- Landmark resolution can infer a location and find nearby stops when a stop name is not directly provided.
- Session memory keeps recent origin/destination context for follow-up questions.
- Data fetching returns future departures and travel context.
- Response generation uses structured timetable data rather than free-form guessing.

### Monitoring

- Chat history is stored for diagnostics and transcript handling.
- Inactive sessions can be emailed through the monitoring service.

---

## 8. Posts, Gallery and Home

### Home

- Home remains the public entry point for local awareness.
- Weather bulletin, posts and gallery imagery support the sense that SwordsLive is about the place, not just transport.

### Posts

- `/api/posts` returns published posts.
- Admins can create and update posts with images.
- Post panels render full content and media.

### Gallery

- `/api/gallery` returns visible public images.
- Gallery pages support image panels and deep links.
- Admin gallery tools support upload, visibility, background selection and deletion.

---

## 9. Administration and Superuser Tools

### Admin Authentication

- Admin routes use JWT Bearer authentication.
- Login verifies against the configured password hash.
- Tokens are stored as `adminToken` and sent in the `Authorization` header.
- Express superuser mode verifies once and shares auth state through context.

### Express Superuser Diagnostics

- `/api/superuser/bus-trail` returns a merged chronological timeline for a bus.
- Historical GPS pings are jitter-corrected through an isolated replayer.
- Timelines merge pings, signal log rows and stop visits.
- Each timeline entry receives a sequence ID shared between map markers and terminal JSON.
- `/api/superuser/bus-state-dump/:busId` exposes in-memory service state for diagnostics.
- `/api/bus-live-state/:busId` supports live polling in the terminal console.

### Frontend Diagnostic Tools

- `BusTrailPanel` can fetch historical trail data or a live state dump.
- `TripTerminalConsole` shows live state, timeline JSON and state dump JSON.
- `useBusTrailOverlay` draws trail polylines and typed diagnostic markers on the map.
- Superuser tools are invisible unless authenticated.

---

## 10. Infrastructure and Reliability

### Technology Stack

- **Frontend:** Next.js 15, React 19, TypeScript, TanStack Query, Tailwind CSS, MapTalks, MapTiler, lucide-react, shadcn/ui
- **Backend:** Node.js, Express, TypeScript, Drizzle ORM
- **Database:** PostgreSQL with pgvector
- **AI and ML:** Transformers.js, xAI/Grok
- **Weather:** Met Eireann HARMONIE
- **Email:** Resend
- **Media:** Backblaze B2

### Feature Flags

Long-running services are gated through `backend/shared/config.ts`, including:

- Bus position polling
- Stop visit observer
- Direction Observer V2
- Deadhaul Observer V2
- Run Boundary Observer
- Trip Matcher V5
- Segment Pace Model
- Stop ETA Service
- Weather bulletin scheduler
- Planning scheduler
- Correction validator

### Restart-Resilient State Snapshots

- Critical in-memory service state is saved to `system_state_snapshots` on shutdown.
- State is restored on startup before service loops begin.
- Snapshot max age prevents stale operational state from being reused.
- Snapshot providers cover DOv2, BO rules, watchdog, stop visits, ETAs and segment pace state.

### Geometry Standard

- Internal spatial calculations use Irish Transverse Mercator, EPSG:2157.
- GPS coordinates are converted before distance, projection or corridor calculations.
- This remains a core correctness rule for transport, weather grid and planning geometry.

---

> SwordsLive V3 is about making one place more readable. The work is not to add everything; it is to reveal the right things at the right moment.

← Back to Articles