Gapwise Developer Documentation

Build on the deterministic platform behind Gapwise.

Official documentation for Gapwise: multi-university web architecture, public campus API, SDKs, data provenance, security, native clients, and permissioned AI/MCP integration.

_{Astro · Starlight · TypeScript · Vercel}

Gapwise · Android · iOS · API · AI · Data · Docs · Status

---

What this repository is

This repository is the canonical public developer-documentation surface for Gapwise, a free and open-source multi-university timetable and campus-intelligence platform created and engineered by Andrew Muratov.

Gapwise currently supports 14 universities across 16 campus models in Canada:

1. University of Toronto (gapwise.ca) — Mississauga, St. George, and Scarborough
2. Carleton University (carleton.gapwise.ca) — Ottawa campus
3. Toronto Metropolitan University (tmu.gapwise.ca) — Downtown Toronto campus
4. Queen's University (queens.gapwise.ca) — Kingston campus
5. Wilfrid Laurier University (laurier.gapwise.ca) — Waterloo campus
6. York University (york.gapwise.ca) — Keele campus
7. McMaster University (mcmaster.gapwise.ca) — Hamilton campus
8. Western University (western.gapwise.ca) — London campus
9. University of Guelph (guelph.gapwise.ca) — Guelph campus
10. University of Ottawa (uottawa.gapwise.ca) — Downtown Ottawa campus
11. Brock University (brock.gapwise.ca) — St. Catharines campus
12. University of British Columbia (ubc.gapwise.ca) — Vancouver / Point Grey campus
13. University of Waterloo (waterloo.gapwise.ca) — Main campus
14. McGill University (mcgill.gapwise.ca) — Downtown Montreal campus

The documentation describes the multi-university architecture, public campus API, SDKs, data layers, and permissioned AI/MCP integration without presenting Gapwise as a single-institution product.

The ecosystem includes the core web/PWA, native Android and iOS clients, deterministic public API and published SDKs, canonical campus-data/provenance layer, permissioned OAuth/MCP AI integration, these developer docs, and an independent operational status service.

The docs follow released first-party contracts rather than inventing parallel behavior:

• gapwise owns canonical product semantics, public API/OpenAPI, and SDK source;
• android owns the native Android implementation;
• ios owns the native iOS implementation;
• ai owns live MCP/OAuth delegation behavior;
• data owns canonical public campus facts and provenance for supported universities;
• cli discovers public campus data and scaffolds university integrations (guide);
• status owns operational state and incident communication.

---

Canonical developer surfaces

App       https://gapwise.ca
API       https://api.gapwise.ca/v1
OpenAPI   https://api.gapwise.ca/openapi.json
Docs      https://docs.gapwise.ca
Data      https://data.gapwise.ca
AI / MCP  https://ai.gapwise.ca/api/mcp
Status    https://status.gapwise.ca

Published SDKs:

npm install @gapwise/sdk@0.1.2
# JSR: @gapwise/sdk@0.1.2
python -m pip install gapwise==0.1.1

The JavaScript/TypeScript package is published on npm and JSR. The Python package is published on PyPI through Trusted Publishing. Registry and runtime claims remain evidence-based and must stay synchronized with actual releases.

---

Documentation map

Area	Covers
Start	Platform overview, architecture, and quickstart
SDKs	JavaScript/TypeScript and Python clients
API	Buildings, places, routing, gap planning, errors, envelopes, and defensive rate-limit handling
Guides	Integration recipes and common workflows
Data	Dataset identity, provenance, uncertainty, attribution, and Gapwise Data
AI & MCP	OAuth/delegation, tools, permissions, privacy, mutation boundaries, and compatibility
Security	Trust boundaries, threat model, privacy architecture, evidence, and validation limits
Platform	Ecosystem ownership, versioning, provenance, uncertainty, and changelog
Operations	Independent Gapwise Status and incident communication

The public API exposes campus intelligence only. It does not expose student timetables, accounts, friends, private sync state, credentials, AI delegation state, or precise live location. Private AI access exists behind a separate OAuth-protected, explicitly delegated boundary.

---

Source-of-truth rules

• gapwise + OpenAPI 3.1 are authoritative for public HTTP behavior and deterministic timetable/gap/routing/product semantics.
• android consumes those semantics for the native Android experience without creating a second product engine.
• ios consumes those semantics for the native iOS experience without creating a second product engine.
• ai is authoritative for the live MCP/OAuth tool, permission, delegation, and bounded-mutation behavior.
• data owns canonical public multi-university campus facts, geometry, provenance, evidence, schemas, and distribution.
• status owns current operational monitoring and incident-communication state.
• docs describes released behavior and preserves uncertainty rather than turning unknown facts into confident claims.
• University-wide timetable support must not be documented as equivalent university-wide campus-routing coverage.
• Named AI clients should not be described as verified until end-to-end production evidence exists.
• Public v1 must never imply private student-data access.

---

Gapwise ecosystem

Repository	Role	Primary surface
gapwise	Core web/PWA, canonical timetable/gap/routing semantics, public API, OpenAPI, and SDK source	gapwise.ca / api.gapwise.ca
android	Native Kotlin + Jetpack Compose Android client	Android app
ios	Native Swift + SwiftUI iOS client	iOS app
ai	OAuth/MCP layer for explicitly delegated student context and bounded actions	ai.gapwise.ca
data	Canonical public multi-university campus data, provenance, schemas, validation, and distribution	data.gapwise.ca
docs	Canonical public developer documentation	docs.gapwise.ca
status	Independent service-health monitoring and incident communication	status.gapwise.ca

These first-party product repositories form one ecosystem with deliberate separation of concerns, consistent links, trust boundaries, and source-of-truth ownership. Organization-wide GitHub defaults live separately in .github.

---

Local development

Requires Node.js 22 or newer.

git clone https://github.com/GapwiseHQ/docs.git
cd docs
npm ci
npm run check
npm run build
npm run dev

main is the production documentation branch and deploys to docs.gapwise.ca. The status service is deployed independently from status; documentation links to it rather than becoming a second status source.

---

Independent project

Gapwise is an independent student software project created by Andrew Muratov. It is not affiliated with, endorsed by, or an official service of the University of Toronto, Carleton University, Toronto Metropolitan University, Queen's University, Wilfrid Laurier University, York University, or McMaster University.

Original documentation and site code are available under the MIT License.

One ecosystem. Explicit owners. Documentation that follows the evidence.

Read the docs →

Updating the AI tool catalog

AI owns tool registration and the generated contracts/mcp-live-surface.json manifest. With ai and docs checked out as siblings:

# In ai, after editing registrations:
npm run contract:generate
npm run contract:check
# In docs:
npm run mcp-contract:sync
npm run verify:mcp-contract
npm run mcp-contract:check
npm run check
npm run build

Update the tool and permission guides when verification identifies drift. CI checks the vendored manifest against AI main; merge the AI producer PR before the Docs consumer PR. Docs builds use the checked-in manifest and do not fetch AI at runtime. For another checkout layout, pass -- --source=<path/to/mcp-live-surface.json> to the sync/check command.