29 lines
1.8 KiB
Markdown
29 lines
1.8 KiB
Markdown
# ADR 0001: API-First Architecture with Bundled Web UI
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
FeDIY needs to serve both a usable web interface for end users and the ActivityPub federation protocol for other instances. It must also not create barriers to third-party clients or alternative front-ends. Without an explicit policy, it is easy to accumulate shortcuts where the bundled UI is given privileged access to server internals, making it progressively harder for external clients to reach parity.
|
|
|
|
## Options Considered
|
|
|
|
1. **Server-side rendering only** — simpler initial delivery but couples the front-end tightly to server internals, making third-party clients second-class.
|
|
2. **Separate front-end service** — clean decoupling but adds operational complexity and a cross-origin story from day one.
|
|
3. **API-first with bundled UI as first-party client** — the server exposes a stable public API; the bundled UI is a client of that API, co-deployed as static assets from the same origin.
|
|
|
|
## Decision
|
|
|
|
Option 3. The server exposes a stable HTTP API as its primary interface. The bundled web UI is a first-party client of that API and receives no privileged access unavailable to third-party clients. The UI is delivered as static assets from the same origin and is optional at deploy time.
|
|
|
|
## Consequences
|
|
|
|
- Every capability must be reachable through the public API before the bundled UI uses it. This creates a useful constraint that keeps the API complete.
|
|
- Content negotiation (ActivityPub vs JSON API) is required at the same URL namespace.
|
|
- CORS policy must be explicit and safe by default.
|
|
- Third-party clients and alternative front-ends are supported without server changes.
|
|
- The bundled UI serves as the reference implementation for API usability validation.
|
|
- The API surface must be versioned and changes must follow a deprecation policy.
|