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 28 universities across 74 campus models:

1. University of Toronto (uoft.gapwise.ca, also gapwise.ca) — Mississauga, St. George, and Scarborough
2. Carleton University (carleton.gapwise.ca) — Ottawa Campus, Dominion-Chalmers Centre
3. Toronto Metropolitan University (tmu.gapwise.ca) — Downtown Toronto Campus, Brampton Campus
4. Queen's University (queens.gapwise.ca) — Kingston Campus, West Campus
5. Wilfrid Laurier University (laurier.gapwise.ca) — Waterloo Campus, Brantford Campus, Milton Campus
6. York University (york.gapwise.ca) — Keele Campus, Glendon Campus, Markham Campus
7. McMaster University (mcmaster.gapwise.ca) — Hamilton Campus, Ron Joyce Centre
8. Western University (western.gapwise.ca) — London Campus, Huron University College, King's University College
9. University of Guelph (guelph.gapwise.ca) — Main Campus, Ridgetown Campus, Guelph-Humber Campus
10. University of Ottawa (uottawa.gapwise.ca) — Downtown Campus, Alta Vista Campus
11. Brock University (brock.gapwise.ca) — St. Catharines Campus, Marilyn I. Walker School
12. University of British Columbia (ubc.gapwise.ca) — Vancouver Point Grey, Okanagan Campus
13. University of Waterloo (waterloo.gapwise.ca) — Main Campus, Cambridge Campus, Kitchener Campus, Stratford School
14. McGill University (mcgill.gapwise.ca) — Downtown Campus, Macdonald Campus
15. Carnegie Mellon University (cmu.gapwise.ca) — Pittsburgh Campus, Silicon Valley Campus
16. University of California, Berkeley (ucberkeley.gapwise.ca) — Main Campus, Richmond Field Station
17. New York University (nyu.gapwise.ca) — Washington Square Campus, Brooklyn Campus
18. Massachusetts Institute of Technology (mit.gapwise.ca) — Cambridge Campus, Lincoln Laboratory Campus
19. Stanford University (stanford.gapwise.ca) — Main Campus, Redwood City Campus
20. University of Pennsylvania (upenn.gapwise.ca) — Philadelphia Campus, Pennovation Works, New Bolton Center
21. Cornell University (cornell.gapwise.ca) — Ithaca Campus, Cornell Tech Campus, Weill Cornell Medicine
22. Dartmouth College (dartmouth.gapwise.ca) — Hanover Campus, Dartmouth Health Lebanon
23. Brown University (brown.gapwise.ca) — College Hill Campus, Jewelry District Campus
24. Columbia University (columbia.gapwise.ca) — Morningside Campus, Manhattanville Campus, CUIMC Campus
25. Princeton University (princeton.gapwise.ca) — Main Campus, Forrestal Campus, Meadows Campus
26. Yale University (yale.gapwise.ca) — Central Campus, School of Medicine, West Campus
27. Harvard University (harvard.gapwise.ca) — Cambridge Campus, Allston Campus, Longwood Medical Area
28. Sorbonne Université (sorbonne.gapwise.ca) — Pierre et Marie Curie, Sorbonne, Pitié-Salpêtrière, Saint-Antoine, Cordeliers, Clignancourt, Malesherbes

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.