# Architecture and scope

Caribou is a white-labelled iOS platform. Each distributed application embeds a **metro ID** and bundled metro-specific JSON defaults. All applications consume one metro-scoped, read-only API. Mississauga is the proof of concept, not a special case in the contract.

## Contract-first design

- OpenAPI 3.1 defines the three initial GET endpoints and schemas.
- The bundled defaults have the same shape as API responses.
- `/bootstrap` is a lightweight manifest containing metro details, feature flags and versioned links to `areas` and `home`.
- `/areas` and `/home` are independent resources. No articles endpoint is specified yet; it is reserved for future design.
- Future API changes should be additive within `/v1`; breaking changes require a new version.
- The server does not determine a user's location. The application performs polygon containment locally and may find multiple overlapping areas.
- Metro IDs are stable technical identifiers. Area IDs are globally unique and survive renames and boundary revisions.
- There is no public write API or admin API in this project.

## Feature flags

Flags are metro-scoped Boolean values in `bootstrap.features`. Clients ignore unknown flags and treat absent flags as disabled. A flag cannot enable functionality absent from the installed app. TestFlight/beta overrides are app-local and outside the API scope.

## Error model

Use standard HTTP statuses, with RFC 9457 `application/problem+json` for errors. A 404 indicates an unknown or inactive metro; a 503 indicates a temporary outage. Clients should continue operating on local data. The placeholder API hostname in the spec is not a real endpoint.

## Security

The read-only API is not assumed to require a secret embedded in the app. Public deployment should use sensible abuse controls. API documentation access is independent from API authentication.

## Deferred work

Articles, administrative tools, photo upload, geographic editing, localization, authentication for end users, beta targeting, and historical boundaries are out of scope.