Rijad Zuzo
58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# ADR 0002: Backend Protocol = HTTPS REST + JSON (OpenAPI-First)
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-02-14
|
|
|
|
## Context
|
|
|
|
`relationship_saver` is offline-first for MVP. Local DB remains the source of truth for core usage. Backend responsibilities are incremental:
|
|
|
|
1. account/session management
|
|
2. sync transport for local mutations and remote updates
|
|
3. recommendation/signals feed
|
|
4. future upload/download URL broker
|
|
|
|
We need a transport that is cross-platform, testable in Flutter, easy to stub for local development, and contract-driven across mobile/backend teams.
|
|
|
|
## Decision
|
|
|
|
Use HTTPS REST + JSON with an OpenAPI-first contract.
|
|
|
|
- Client HTTP stack: `dio`
|
|
- Typed models: `freezed` + `json_serializable`
|
|
- Gateway boundary: `BackendGateway` (transport-agnostic interface)
|
|
- Runtime implementation: `BackendGatewayRest`
|
|
- Local development implementation: `BackendGatewayFake`
|
|
- Auth/session support: access + refresh token with secure storage
|
|
- Retry policy: only transient failures; non-idempotent retries require idempotency key
|
|
- Error surface: typed `BackendException` taxonomy
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Strong, versioned contract artifact in `docs/api/openapi.yaml`
|
|
- Fast local iteration with fake gateway, no backend dependency for core UX
|
|
- Explicit behavior for refresh/retry/failure classes
|
|
- Good compatibility across Android/iOS/macOS/Windows/Linux/Web
|
|
|
|
### Tradeoffs
|
|
|
|
- REST polling for feed/sync may be less real-time than socket-based push
|
|
- Some envelope sizes may require tuning and pagination strategy
|
|
- Requires careful idempotency handling for mutation endpoints
|
|
|
|
## Evolution Plan
|
|
|
|
Realtime is deferred for now but planned:
|
|
|
|
1. Keep REST as source of truth for command/query semantics.
|
|
2. Add optional SSE or WebSocket channel for push notifications/signals invalidation.
|
|
3. Continue using same DTO schema envelopes from OpenAPI where possible.
|
|
4. Add explicit capability negotiation (`/v1/capabilities`) when realtime ships.
|
|
|
|
## Rejected Alternatives
|
|
|
|
- gRPC-only for MVP: stronger streaming story, but higher setup and broader tooling burden for immediate scope.
|
|
- GraphQL-first: flexible querying, but sync/mutation idempotency patterns are clearer with explicit REST resources now.
|