Architecture

flighthelp is a four-layer system. Each layer has a clear contract with the layers above and below it. Each layer can be built, versioned, and tested independently. Each layer is useful on its own.

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 4 — REFERENCE SURFACES                                   │
│  flighthelp.net (consumer site) · contribute.flighthelp.net     │
│  These exist to demonstrate the layers below work in production │
└─────────────────────────────────────────────────────────────────┘
                                ▲
                                │ consumes
                                │
┌─────────────────────────────────────────────────────────────────┐
│  LAYER 3 — DATA + API                                           │
│  Continuously-updated verified dataset · REST + GraphQL API     │
│  Versioned bulk dumps · Webhooks · Self-service API keys        │
└─────────────────────────────────────────────────────────────────┘
                                ▲
                                │ structured by
                                │
┌─────────────────────────────────────────────────────────────────┐
│  LAYER 2 — RULES ENGINE                                         │
│  Standalone library implementing every relevant passenger-     │
│  rights regime (EC 261, UK 261, ANAC 400, Montreal, DOT, etc.)  │
│  Versioned, tested, with legal citations                        │
└─────────────────────────────────────────────────────────────────┘
                                ▲
                                │ built on
                                │
┌─────────────────────────────────────────────────────────────────┐
│  LAYER 1 — SCHEMAS                                              │
│  JSON Schema definitions, OpenAPI fragments, language-bound     │
│  types for every entity in the system                           │
└─────────────────────────────────────────────────────────────────┘

Layer 1 — Schemas

The foundation. A small, stable, public specification language for representing air-travel facts.

The schemas define every entity: Airline, Airport, BaggageRule, ContactMethod, Fee, Scenario, Regulation, Contributor, Edit, Source, Badge. Each entity is specified once, in JSON Schema, with documentation, and from that one specification the project generates language-bound types in TypeScript, Python, Go, PHP, Rust, Java, and Swift.

The schemas live in the flighthelp/schema repo, licensed MIT. They are versioned with strict semver: breaking changes get major bumps; new optional fields get minor bumps; documentation and clarification get patch bumps. Each schema version is released with a migration note for downstream consumers.

The schemas are designed to be adopted by anyone modeling this data — including projects that have no relationship with flighthelp. The whole point is that they become the de facto standard. To support that, the schemas are documented with full field-level rationale, every constraint is explained, and the versioning policy is public and predictable.

See SCHEMAS.md for the schema philosophy. See DATA-MODELS.md for the field-by-field specification of each entity.

Layer 2 — Rules engine

A standalone open-source library that takes a structured flight scenario and returns eligibility, legal basis, and expected compensation amount under every relevant regime.

The engine is published as packages on npm (@flighthelp/rules-engine), PyPI (flighthelp-rules-engine), and Composer (flighthelp/rules-engine). Each language has the same surface API. Each regime (eu-261, uk-261, brazil-400, montreal, us-dot-tarmac, canada-appr, india-dgca, and others added over time) is a separate sub-module that the engine composes.

The engine takes input that conforms to a Scenario schema (route, distance, delay reason, delay duration, fare class, passenger details, special circumstances) and returns output that conforms to a Determination schema (eligibility, legal basis, compensation amount and currency, time limits, required next steps, confidence flags, edge-case notes).

Every rule in the engine is tied to a specific article of the underlying regulation and, where relevant, to a court case or regulator opinion. The legal references are part of the engine's data, accessible programmatically. The engine is testable: each regime ships with hundreds of fixture cases (test-cases.json) that pin specific inputs to specific expected outputs, with each case citing its legal basis.

The engine lives in the flighthelp/rules-engine repo, licensed MIT. It is versioned independently of the schemas; downstream consumers can pin to a specific engine version for legal stability. When the underlying regulations change (an amendment is passed, a court ruling shifts interpretation), the engine is updated through a documented process and the version is bumped.

See RULES-ENGINE.md for the engine specification.

Layer 3 — Data and API

The verified dataset and the public API that serves it.

The dataset is the joint product of the contributor community, the automated scrapers, and the moderation system. It is continuously updated. Every fact in it carries provenance: a verification timestamp, a verifier count, a source URL, and a confidence score. Disputed facts are flagged. Stale facts are flagged. The dataset is downloadable in bulk under CC-BY 4.0, with daily and monthly snapshots committed to the flighthelp/data repo.

The API exposes the dataset through REST and GraphQL endpoints at api.flighthelp.net. Three free tiers (anonymous, registered, verified non-profit) cover the vast majority of consumers. A paid commercial tier funds operations and provides SLAs to high-volume integrators. Every response includes _meta with provenance fields so any downstream consumer can show users where the answer came from.

The API also exposes the rules engine through a POST /v1/compensation/evaluate endpoint, so consumers who do not want to install the library can still use the engine. The engine endpoint is stateless and fast.

Webhooks let registered consumers subscribe to entity-change events: "notify me when Delta's baggage rules change," "notify me when any EU carrier updates a contact number." This lets downstream products stay current without polling.

See API.md for the full API specification.

Layer 4 — Reference surfaces

The two human-facing applications that consume the layers below and exist to prove they work.

The consumer site at flighthelp.net is the public-facing reference for travelers. It is a Next.js app that consumes the API and presents the data in a fast, mobile-first, ad-free interface. The site has roughly nine page types: airline pages, airport pages, scenario pages, comparison pages, knowledge pages, tool pages, community pages, and meta pages. It exists to help travelers directly and to demonstrate that the API and data are usable in production.

The contributor PWA at contribute.flighthelp.net is the application community contributors use to verify data, take sizer photos, report disputes, and earn reputation. It is a separate Next.js app so the consumer site never has to ship contributor code. The PWA is installable, offline-first, and designed around airport workflows.

Both reference surfaces are built on the same shared packages: the schema types, the rules-engine library, the API client, and the design system. Both are subject to the design system in DESIGN-SYSTEM.md.

See WEBSITE.md for the consumer site specification. See CONTRIBUTOR-APP.md for the PWA specification.

How the layers interact

The dependency direction is strict: each layer depends only on the layers below it.

  • The schemas have no dependencies. They are the foundation.
  • The rules engine depends on the schemas (for input/output types) and nothing else.
  • The dataset is structured by the schemas. The API serves the dataset and exposes the rules engine.
  • The reference surfaces consume the API and the engine. They do not contain business logic that should live in the engine or data that should live in the dataset.

This dependency hygiene matters because it allows each layer to be useful on its own. A developer who wants only the schemas can use them. A developer who wants only the engine can install the library. A developer who wants the data can hit the API or download the dump. The reference site is one application of many possible applications.

Layers as repositories

The four layers map onto five GitHub repositories under the flighthelp org:

  • flighthelp/schema (MIT) — Layer 1
  • flighthelp/rules-engine (MIT) — Layer 2
  • flighthelp/data (CC-BY 4.0) — Layer 3 data
  • flighthelp/web (AGPL-3.0) — Layer 4 reference surfaces (web + contribute apps as a monorepo)
  • flighthelp/scrapers (MIT) — supports Layer 3 (the automated ingestion system)

See REPOSITORIES.md for the full repo specification.

What is not in the architecture

Two notable absences:

No "service layer" separate from the API. The API is the service layer. There is no internal microservice mesh, no service-to-service mTLS, no event bus. The system is intentionally simple: scrapers and contributors write to Postgres through moderation, the API reads from Postgres with aggressive Cloudflare caching in front. Complexity is added only when load demands it, not preemptively.

No proprietary "AI layer." flighthelp does not train models, does not host LLMs, and does not maintain its own AI offering. AI labs are downstream consumers of the API; what they build on top is their business. The project's job is to provide grounded, current, citable facts — not to compete with the labs whose customers use those facts.