Matsubaa/FedDIY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance architecture documentation and add open questions; establish API-first architecture with bundled web UI as first-party client

Browse Source
This commit is contained in:
Kyle J. Turpin
2026-05-23 10:03:38 -05:00
parent 5794b593fa
commit c797a946c1
4 changed files with 304 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+37 -5
View File
@@ -6,7 +6,8 @@ This document captures current architectural intent. It is a planning artifact a
Primary system responsibilities:
- Host and render DIY project content.
- Expose a stable HTTP API as the primary interface for all clients.
- Host and render DIY project content through a bundled web UI that consumes the public API.
- Manage local accounts and authorization.
- Federate selected objects and activities using ActivityPub.
- Enforce local moderation policy for both local and remote content.
@@ -24,13 +25,42 @@ Out of scope for early phases:
- Moderation and trust policy.
- Search and discovery.
## Client and Front-End Strategy
The server exposes a stable, documented HTTP API as its primary interface. The bundled web UI is a first-party client of that same API — it receives no privileged server-side access that a third-party client could not also use.
Principles:
- **API-first**: every user-facing capability is reachable through the public API before the bundled UI uses it.
- **No server-side rendering shortcuts**: the bundled UI must not depend on server-internal state or bypass the API layer.
- **Third-party clients are first-class**: authentication, content negotiation, and capability negotiation must work the same way for any client origin.
- **Content negotiation**: the server responds to `Accept: application/activity+json` (or `application/ld+json`) for federation endpoints, and `Accept: application/json` for the API, allowing a single URL namespace to serve both.
- **CORS**: cross-origin API access is supported for read-only public resources, with authenticated endpoints requiring explicit opt-in by the instance operator.
- **Bundled UI is optional at deploy time**: an instance operator should be able to run the backend and serve their own front-end without modifying server code.
API surface areas:
- Public read API: browse projects, actors, and search without authentication.
- Authenticated user API: authoring, account management, preferences.
- Moderation API: moderation actions and audit review, scoped by role.
- Federation endpoints: ActivityPub inbox/outbox per the ActivityPub specification.
- Well-known endpoints: WebFinger, NodeInfo, and instance metadata.
Bundled web UI:
- Delivered as static assets served from the same origin.
- Communicates only through the public API.
- Treated as the reference client for API usability validation.
- Should degrade gracefully where JavaScript is unavailable where practical.
## Logical Components
- API and web delivery layer.
- Public HTTP API layer (routing, auth middleware, content negotiation, CORS).
- Domain service layer for project and account workflows.
- Federation layer (inbox/outbox, signing, verification, retries).
- Persistence layer for local and federated records.
- Moderation policy engine and audit log.
- Bundled web UI (static asset delivery).
- Background workers for delivery, indexing, and maintenance tasks.
## Data and Object Strategy
@@ -56,11 +86,13 @@ Out of scope for early phases:
## Non-Functional Requirements
- Reliability: resilient delivery and retry strategy for federated traffic.
- Security: signature verification, key management, least-privilege defaults.
- Security: signature verification, key management, least-privilege defaults, and safe CORS policy.
- Performance: predictable latency for local reads and bounded queues for remote events.
- Operability: metrics, logs, and runbooks for incident response.
- API stability: public API changes follow a deprecation policy; breaking changes require a version increment.
## Architecture Decision Practice
- Capture major decisions with lightweight ADRs in a future docs/adrs directory.
- Each ADR should include context, options considered, decision, and consequences.
- Decisions are captured as ADRs in [docs/adrs/](adrs/).
- Each ADR includes: context, options considered, decision, and consequences.
- See [ADR 0001: API-First with Bundled Web UI](adrs/0001-api-first-bundled-ui.md).