113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
# FeDIY Architecture (Planning Baseline)
|
|
|
|
This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature.
|
|
|
|
## System Boundaries
|
|
|
|
Primary system responsibilities:
|
|
|
|
- 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.
|
|
|
|
Out of scope for early phases:
|
|
|
|
- Rich social graph features beyond project-oriented interactions.
|
|
- Highly customized recommendation systems.
|
|
|
|
## Core Domains
|
|
|
|
- Identity and actors.
|
|
- Project authoring and publishing.
|
|
- Federation transport and protocol translation.
|
|
- Moderation and trust policy.
|
|
- Search and discovery.
|
|
|
|
## Project Domain Baseline
|
|
|
|
Current product definition:
|
|
|
|
- A project is a defined work process.
|
|
- Core project structure includes materials/ingredients, required tools, and ordered step-by-step instructions.
|
|
- Steps may include embedded media hosted on this instance or linked from external sources.
|
|
- Projects may include external canonical links (for example homepage, repository, or source publication).
|
|
- Explicit project versioning is preferred and will be part of the domain model.
|
|
- The project model is composable: a minimal core plus optional domain-specific extensions.
|
|
- Domain-specific detail (for example knitting patterns/yarns, 3D print profiles/STLs, electronics BoM data) should be representable without being mandatory for all instances.
|
|
- First-party FeDIY focuses on a stable extension mechanism rather than implementing every niche schema directly.
|
|
|
|
## 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
|
|
|
|
- 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
|
|
|
|
- Separate local canonical records from imported federated records.
|
|
- Preserve source metadata for remote content and actor provenance.
|
|
- Track object lifecycle states to support idempotent federation processing.
|
|
- Persist project data as core fields plus extension payloads so instances can tailor domain detail without fragmenting the base model.
|
|
|
|
## Federation Strategy
|
|
|
|
- Start with a narrow, explicit ActivityPub profile.
|
|
- Prefer strict validation and clear rejection reasons over permissive parsing.
|
|
- Use replay-safe request validation and deterministic retry behavior.
|
|
- Maintain an interop test matrix for protocol behaviors.
|
|
|
|
## Moderation and Safety Strategy
|
|
|
|
- Local policy is authoritative for what is visible on this instance.
|
|
- Policy controls exist at three levels: object, actor, and instance.
|
|
- Moderation actions produce auditable events.
|
|
- Appeals and reversal policy should be documented before broad federation rollout.
|
|
|
|
## Non-Functional Requirements
|
|
|
|
- Reliability: resilient delivery and retry strategy for federated traffic.
|
|
- 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
|
|
|
|
- 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).
|