Matsubaa/FedDIY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf20d2a347072859fbc845ba6b829117ac301b2a
FedDIY/docs/OPEN_QUESTIONS.md
T

12 KiB
Raw Blame History

FeDIY Open Questions

A living document of unresolved design and product questions. When a question is resolved, record the decision as an ADR and remove or archive the entry here.

Each question is tagged with the phase it blocks or most affects: [P0], [P1], [P2], [P3], [P4].

Resolved Decisions

  • A "project" is a defined work process.
  • A project includes a list of materials/ingredients, a list of required tools, and step-by-step ordered instructions.
  • Steps may include embedded media hosted on-instance or linked from external sources.
  • Projects may include one or more external canonical links (for example homepage, repository, or source publication).
  • Explicit project versioning is preferred and should be supported.
  • A project is composable: FeDIY provides a minimal core model, and instances can tailor project detail via optional domain-specific extensions.
  • FeDIY should not require first-party implementation of every domain detail up front; expert communities can define richer schemas over time.

Upfront Clarification Plan (P0 -> Early P1)

The goal is to remove ambiguity before implementation while keeping scope realistic.

  1. Decision track A: Project revision model
  • Resolve Q1 first.
  • Output: one ADR defining draft/publish/supersede behavior and history visibility.
  • Success signal: API and UI contracts can assume a stable project lifecycle.
  1. Decision track B: Core-plus-extension contract
  • Resolve Q2, Q2a, Q2b, and Q2c as one coherent contract.
  • Output: one ADR for core project fields and one ADR for extension payload shape/namespacing/discovery.
  • Success signal: instances can add domain-specific detail (knitting, 3D print, electronics, etc.) without changing core semantics.
  1. Decision track C: Search/index policy for extensions
  • Resolve the extension-indexing part of Q2c with Q23.
  • Output: indexing policy doc or ADR that separates required indexed fields from opaque extension fields.
  • Success signal: predictable search behavior across instances with different extensions.
  1. Decision track D: API stability and evolution
  • Resolve Q10 and Q11 before broad client development.
  • Output: API versioning/deprecation policy with compatibility guarantees for third-party clients.
  • Success signal: extension evolution does not break existing clients unexpectedly.

Domain Model

Q1 [P1] What should the explicit versioning model look like?

  • Immutable numbered revisions, mutable drafts, or both?
  • Does each version snapshot materials, tools, steps, media references, and extension data?
  • What is the publish workflow for a new version (draft -> published -> superseded)?
  • How should old versions be exposed in API and UI (full history vs selected milestones)?

Q2 [P1] How are materials modelled?

  • Free-text only, or linked to a shared taxonomy/catalog?
  • Do quantities and units need to be structured (for search/filtering), or is prose sufficient for MVP?

Q2a [P1] How are required tools modelled?

  • Free-text tools list only, or a normalized/tool taxonomy strategy?
  • Should tools support optional metadata (skill level, safety notes, alternatives)?

Q2b [P1] How are canonical external links modelled and validated?

  • Single canonical link or multiple typed links (homepage, repository, video, reference)?
  • Are external links version-scoped or project-scoped?
  • What URL validation and safety checks are required?

Q2c [P1/P2] What is the extension model for domain-specific project data?

  • What extension shape is supported first: typed JSON blocks, namespaced key/value fields, or plugin-defined schemas?
  • How are extensions identified and namespaced to avoid collisions across instances?
  • How do API and UI clients discover which extensions are present on a project?
  • Which extension fields are indexed for search, and which remain opaque?
  • What validation guarantees does the server provide for extension payloads?

Q3 [P1] What is the tag and category strategy?

  • Folksonomy (free-form user tags), curated taxonomy, or both?
  • Is there a category hierarchy (craft type → technique → material)?
  • Who controls the taxonomy on a given instance?

Q4 [P1] What licences can a project carry?

  • Does the platform enforce a licence selection, or is it free-text?
  • Does the platform's own CC BY-SA 4.0 licence apply to user content by default, or is that a separate question?

Q5 [P3/P4] What are the rules for project forks and remixes?

  • Can a user fork another user's project (including from a remote instance)?
  • Does a fork maintain a reference/attribution link to the original?
  • What licence constraints apply to remixing?

Identity and Authentication

Q6 [P1] What is the authentication mechanism?

  • Local username/password (with secure hashing), passkeys, OAuth2/OIDC third-party providers, magic-link email, or a combination?
  • Is email verification required for account creation?

Q7 [P1] What account fields are required beyond the ActivityPub actor minimum?

  • Display name, bio, avatar, location — which are required, optional, or omitted entirely?
  • Are there craft-specific profile fields (preferred crafts, skill level)?

Q8 [P2] Can remote ActivityPub actors interact without a local account?

  • Can a remote actor follow a local user, like a project, or comment, without registering locally?
  • What local data is persisted for a remote actor who interacts?

Q9 [P1] What is the session and token strategy for the API?

  • Short-lived JWTs, opaque bearer tokens with a refresh flow, or server-side sessions?
  • How are tokens invalidated (logout, account suspension)?

API Design

Q10 [P1] What API style?

  • REST with JSON, or something else (GraphQL, JSON:API)?
  • Is there value in JSON:API's sparse fieldsets and relationship includes for a project-browsing use case?

Q11 [P1] What is the API versioning strategy?

  • URL path prefix (/api/v1/), Accept header versioning, or no versioning until a breaking change forces it?

Q12 [P1] What is the pagination strategy?

  • Cursor-based (stable under concurrent inserts), offset-based, or keyset pagination?
  • What is the default and maximum page size?

Q13 [P1] What rate-limiting and abuse-prevention strategy applies to the API?

  • Per-IP, per-authenticated-user, or both?
  • Does this apply equally to federation endpoints?

Front-End / Bundled UI

Q14 [P1] What technology powers the bundled web UI?

  • Vanilla JS / progressive enhancement (HTMX or similar), a Rust WASM front-end framework, or a JS framework (e.g. Svelte, Vue)?
  • Does the choice live in the same Cargo workspace or a separate directory with its own build tooling?

Q15 [P1] What is the no-JavaScript fallback scope?

  • Read-only browsing (project pages, search results) without JS is desirable.
  • Authoring without JS is probably out of scope — is that an explicit decision?

Q16 [P1] What is the accessibility baseline?

  • WCAG 2.1 AA as a minimum?
  • Are there specific craft-community accessibility concerns (screen reader support for step-by-step instructions, colour contrast for pattern images)?

Federation and ActivityPub

Q17 [P2] How do FeDIY project objects map to ActivityPub types?

  • Use Note or Article for broad compatibility, or define a custom FeDIYProject type?
  • If custom, what fallback representation do we provide for clients that don't understand it?

Q18 [P2] What ActivityPub activity types does FeDIY support in phase 2?

  • Minimum set: Create, Update, Delete, Follow, Accept, Reject, Undo.
  • Phase 2 or later: Like, Announce (boost), Flag (report)?

Q19 [P2] What is the media federation strategy?

  • Do media attachments (images, files) federate as links to the canonical origin, or are they replicated locally?
  • How are broken/unavailable remote media handled in the UI?

Q20 [P2] What is the HTTP Signatures key lifecycle?

  • Per-actor keypairs (standard), or instance-level signing with keyId delegation?
  • Key rotation: when and how are keys rotated, and how are remote instances notified?

Q21 [P2] Which well-known endpoints are in scope for phase 2?

  • WebFinger (required for actor discovery).
  • NodeInfo (instance metadata for compatibility and listing services).
  • /.well-known/oauth-authorization-server if OIDC is supported.

Q22 [P2] How is WebFinger structured for FeDIY entities?

  • Actors are users: acct:user@instance — standard.
  • Do projects also have addressable AP identities, or do they belong to the author actor?

Search and Discovery

Q23 [P1] What is the full-text search implementation?

  • PostgreSQL full-text search (zero extra infra), an embedded engine (Tantivy via Rust), or an external service (Meilisearch, Elasticsearch)?
  • What fields are indexed: title, description, steps, tags, materials?

Q24 [P2] Does search span federated content?

  • Phase 1: local content only.
  • Phase 2+: do we query remote instances, or build a local index of federated objects we've received?

Media Storage

Q25 [P1] How are user-uploaded media assets stored?

  • Local filesystem, S3-compatible object storage, or both with a configurable backend?
  • What is the maximum file size and permitted formats for MVP?

Q26 [P1] Is image processing (resize, thumbnail, format conversion) in-process or delegated?

  • In-process with a Rust image library, or delegated to an external service/worker?

Persistence

Q27 [P0/P1] What is the database?

  • PostgreSQL is the obvious choice given full-text search, JSONB for flexible AP object storage, and broad hosting support — is this confirmed?
  • Is SQLite a supported option for lightweight self-hosting, or is that complexity not worth it?

Q28 [P1] What is the database migration strategy?

  • A Rust migration library (sqlx migrate, refinery), or a standalone tool (Flyway, Liquibase)?

Moderation

Q29 [P1] How are moderator roles assigned and scoped?

  • Instance admin assigns moderators manually; no self-service promotion.
  • Are there multiple moderation tiers (e.g. content moderator vs instance admin)?

Q30 [P3] Do we participate in shared blocklists (e.g. FIRES, Oliphant tiers)?

  • Subscribe to external block lists automatically, or manual import only?
  • Is this a phase 3 concern or deferred entirely?

Q31 [P3] What is the user-facing report and appeals workflow?

  • Can a user see the status of their own report?
  • Is there a formal appeals process, or at moderator discretion?

Deployment and Operations

Q32 [P0/P1] What is the primary deployment target?

  • Single static binary + external PostgreSQL (simplest self-hosting).
  • OCI/Docker container image.
  • NixOS module.
  • All three, or a prioritised subset?

Q33 [P1] What are the minimum self-hosting requirements?

  • RAM, CPU, disk, and network minimums for a small instance.
  • Is there a single-binary mode with embedded SQLite for hobbyist hosting (see Q27)?

Q34 [P1] What is the configuration strategy?

  • Environment variables only, a config file (TOML), or both?
  • What must be configurable per-instance (instance name, federation policy, storage backend, SMTP, etc.)?

Q35 [P4] What observability stack is expected?

  • Structured logging to stdout (12-factor), Prometheus metrics endpoint, OpenTelemetry traces?
  • Are these required at launch or added progressively?

Content and Community Policy

Q36 [P0] Does the platform define baseline content guidelines beyond what moderation tooling enforces?

  • What categories of content are prohibited regardless of instance policy?
  • CSAM must be prohibited and reported — is there a mechanism planned?

Q37 [P4] Are collaborative/co-authorship workflows in scope?

  • Can multiple accounts be listed as co-authors of a project?
  • Is there a contribution workflow (pull-request style) or trust-based co-author invite?
Reference in New Issue View Git Blame Copy Permalink