Documentation navigation

Wayfarer

Developers and contributors

This is the starting point for working on the Wayfarer web application. It covers source development, repository orientation and the shortest path from a change to useful validation. Supported installation and production operation are separate concerns; use the self-hosting guide for those.

Maintained development baseline

WayfarerMobile is a separate repository. Changes to the server do not implicitly change the mobile application.

Restore and run

Clone into a native filesystem for the environment you are using. On WSL2, prefer a path such as ~/src/Wayfarer rather than /mnt/c/....

Restore the .NET tools, application dependencies and locked frontend dependencies:

dotnet tool restore
dotnet restore
nvm install
nvm use
npm ci

Create or select a local PostgreSQL database, enable postgis and citext, and configure ConnectionStrings:DefaultConnection. The checked-in Development JSON contains only a placeholder password; do not commit credentials. An environment-variable override is unambiguous:

export ConnectionStrings__DefaultConnection='Host=localhost;Port=5432;Database=wayfarer;Username=postgres;Password=your-local-password'

Start the ASP.NET Core application in Development:

dotnet run

dotnet watch run is the normal hot-reload alternative. Non-Production startup applies pending EF migrations, aligns the Quartz schema and seeds required development data. Production startup deliberately does not perform those mutations; see Database and the self-hosting documentation.

Native Windows uses the same .NET commands from PowerShell or Command Prompt, with a native checkout and a local development/test PostgreSQL 18 + PostGIS connection. Keep disposable smoke storage and Data Protection keys separate from existing user data; do not bypass startup/readiness checks. The current native Windows build/controller evidence and remaining actual-startup prerequisite are recorded in helper validation.

Frontend development

Wayfarer has two frontend paths that share the same ASP.NET Core application:

For Razor/MvcFrontendKit production bundles, use the repository-local tool:

dotnet frontend build

For the Trip Editor, run Vite beside the ASP.NET application when editing the Vue client:

npm run dev

Build the Trip Editor assets with:

npm run typecheck
npm run build

Generated wwwroot/dist/ and wwwroot/vite/ outputs are build products, not source ownership boundaries.

Repository orientation

Start from responsibilities rather than individual files:

Read Architecture before changing an unfamiliar subsystem. Use Extending Wayfarer for task-oriented recipes.

Development and production are different paths

dotnet run is a source-development path. It is not the supported way to install or operate a production Wayfarer instance. Production/self-hosting uses the documented release, Compose and wayfarerctl flow under Self-hosting. Keep operator credentials, backup/update procedures and lifecycle qualification out of source-development instructions.

Contribution path

Before editing, read the repository-root AGENTS.md. It owns contribution, review, branch, merge and evidence policy; this guide does not duplicate those rules.

A practical development loop is:

  1. Locate the owning HTTP, service, persistence and client boundary.
  2. Make the smallest coherent change in that owner.
  3. Prove behavior at the lowest reliable test seam.
  4. Add relational or browser evidence only when the requirement depends on those layers.
  5. Run the relevant frontend checks, Code Guard and repository CI described in Testing.
  6. Update the canonical documentation when the public developer contract changes.

Continue with Architecture, Configuration, Database, API, Security, Extending Wayfarer and Testing.

Proposed contracts awaiting implementation include the Option C Activity reconciliation design, covering catalog identity, safe import retry, authenticated reads and existing-client Activity ID compatibility.

Back to top