Decisions

Early mutations like and rejected bookings whose dates fell outside the destination's date range. This felt safe but was wrong — real trip planning is messy. You book a...

Testing feature branches means either deploying to production (risky) or testing locally (doesn't catch infra issues). Preview environments give each feature branch its own...

The git-like modification tree (ADR-0046) requires ordered appending — each new modification must point to the current HEAD, and HEAD must advance atomically. With multiple...

The MV + Environment Services architecture (ADR-0003) means views trigger fetches on and observe service properties. This is correct for the running app but breaks Xcode...

ADR-0033 established that trips are derived state, generated by replaying modifications (event sourcing). The modification history already supports going back in time — you...

The codebase uses UUIDs as identifiers for many domain entities: trips, users, snapshots, modifications, invitations, accommodations, reservations, documents, journey legs,...

Apollo iOS generates strongly-typed Swift structs from GraphQL fragments and operations. Early in the project, we maintained a parallel layer of domain model types (, , ,...

Without a consistent validation approach, validation logic scatters throughout the codebase: Functions repeatedly validate the same inputs Validation failures occur deep in...

With real-time subscriptions (ADR-0041), a mutation on Device A publishes a signal via Redis pub/sub. All subscribers to that trip receive the signal — including Device A...

Issue #111 introduces GraphQL subscriptions for real-time trip updates across a user's devices. The fundamental design question is how much data the subscription carries....

Production traces go to Grafana Cloud via Alloy (ADR-0053). But iterating on tracing instrumentation against production has a slow feedback loop and costs money per trace....

The backend and iOS app export OpenTelemetry traces and metrics to Grafana Cloud and Langfuse. The recommended OpenTelemetry approach is to export to a local collector rather...

The application runs on a public-facing Hetzner cluster with SSH and Traefik exposed to the internet. Any public endpoint receives constant automated scanning from bots...

The application uses PostgreSQL as its primary data store with pgBackRest for backup and point-in-time recovery (PITR) to Cloudflare R2. The initial configuration used daily...

The backend needs structured error codes for GraphQL (ADR-0006), error source chains for debugging, and automatic tracing on error creation. Standard Rust error crates don't...

Developers and CI runners need to reach cluster services — deploying via Colmena, running database migrations, accessing preview environments (ADR-0055). This was done over...

Users need to understand destination neighborhoods before booking accommodations. When planning a trip to Lisbon, you want to know that Bairro Alto is nightlife, Alfama is...

The app captures accommodation bookings as part of destinations. The initial approach considered storing full location data (coordinates, address, name) for each hotel. This...

Locations need to be more than strings — coordinates, timezone, country code, and locality enable map visualizations, timezone-aware scheduling, and distance calculations....

The app needs user authentication. Passwords are the default but they're a known-weak pattern — reuse, phishing, credential stuffing. Passkeys (WebAuthn/FIDO2) provide...

The trip planning system uses GPT-5 with CFG constraints to generate effects (ADR-0032). The original approach used a custom Lark grammar that output a domain-specific...

Traditional trip planning follows a direct manipulation model: start with an empty itinerary, add each element through forms, the trip IS the data you entered. This doesn't...

The original architecture planned three layers: natural language → intents (via Apple Foundation Models) → effects (via rule interpreter) → trip modifications. This failed...

A common anti-pattern is treating GraphQL queries like REST endpoints — creating "reusable" queries that fetch all possible fields to serve multiple components. This negates...

The application runs on a multi-node Hetzner cluster. Initial deployments used a custom script, but coordinating deploys across the cluster — ordering, error handling,...

Resolvers need access to services (database pools, external API clients, domain services). Options: a DI framework, a global singleton, or async-graphql's built-in container.

The app needs an API layer between the iOS client and Rust backend. REST is the default, but Apollo iOS provides a normalized cache that acts as a source of truth for the UI...

The backend already has OpenTelemetry tracing exported to Grafana Cloud Tempo via an Alloy collector. But mobile requests appear as orphaned traces — the backend shows a 67ms...

The authentication stack used PASETO tokens as transport for session IDs, with server-side sessions in Redis via tower-sessions and axum-login. ADR-0020 attempted to run...

Key rotation (ADR-0026) means tokens can end up signed by deprecated keys. Mobile clients need updated tokens without explicit refresh requests or authentication interruptions.

The application runs as a long-lived Rust/Axum server on a 3-node cluster. PASETO key rotation needs to happen automatically — generate new keys, deprecate old ones, revoke...

Users who book trips months in advance (booking a June trip in January) should remain logged in without re-authentication. Mobile devices are personal devices with a...

After choosing PASETO v4.local for session transport (ADR-0019), we needed a Rust crate that could handle the full lifecycle: token creation, validation, key generation, and...

During key rotation, the server needs to know which key was used to create a given token without exposing key material.

The application runs on a 3-node cluster. PASETO key rotation needs to happen on exactly one node at a time.

After adopting PASETO tokens for transport (ADR-0019), we had token generation working but no token validation middleware. The existing auth stack (tower-sessions,...

The app started with HTTP session cookies via tower-sessions and axum-login. This worked on web but caused persistent lost-session bugs on iOS — cookies in native apps...

The iOS app makes authenticated GraphQL requests via Apollo Client. Authentication needs to be transparent to views — they shouldn't manage tokens, handle 401s, or know about...

SwiftUI apps accumulate hardcoded colors, spacing values, and font sizes across components. Without a system, design changes mean hunting through multiple files, dark mode...

The iOS app needed visual regression testing — something like Chromatic or Storybook but for SwiftUI. The ecosystem in 2024 doesn't have a good middle ground: open source...

SwiftUI historically used with properties for state observation. The problem is it triggers view redraws for any property change, even if the view doesn't use that...

The LLM introduced Result types into the iOS authentication service. While Result types force explicit success/failure handling, async throws is the idiomatic Swift pattern...

The backend will have complex business logic spanning users, trips, accommodations, reservations, journeys, memberships, and more. The traditional alternative is layered...

Unlike web applications where frontend and backend deploy together and every client immediately gets the new bundle, native iOS apps update on the device's schedule. Users...

Rust provides two ways to handle conditional compilation based on build configuration: Compile-time conditionals (): Code is included/excluded at compile time Runtime checks...

We need to decide how to handle error messages across the GraphQL API and iOS client. The backend can either return user-facing error messages in English, or return...

We want short feedback loops when building features. If an idea takes days of backend and frontend work before you can see it running, that's too long to find out it doesn't...

We want good coverage so we can move fast, but not tests that overlap and create maintenance work. LLMs make generating tests trivial now, so the problem isn't writing enough...

Having used React Query for server state management, the goal was to find a similar pattern for SwiftUI — something where views declare data needs and a cache layer handles...

We need to record the architectural decisions made on this project. Traditional documentation claims to always be current, creating maintenance burdens and unrealistic...