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/.
Each ADR includes: context, options considered, decision, and consequences.
See ADR 0001: API-First with Bundled Web UI.

5.6 KiB Raw Blame History