# 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?