From bf20d2a347072859fbc845ba6b829117ac301b2a Mon Sep 17 00:00:00 2001 From: Kyle J Turpin Date: Sat, 23 May 2026 10:16:51 -0500 Subject: [PATCH] Enhance documentation structure and clarify project domain; add new directories for architecture, contracts, and extensions; update roadmap and open questions with resolved decisions and clarification plans. --- README.md | 12 +++++++ docs/ARCHITECTURE.md | 14 ++++++++ docs/OPEN_QUESTIONS.md | 66 ++++++++++++++++++++++++++++++++--- docs/ROADMAP.md | 8 ++++- docs/contracts/.gitkeep | 0 docs/extensions/.gitkeep | 0 schemas/extensions/.gitkeep | 0 schemas/project-core/.gitkeep | 0 8 files changed, 95 insertions(+), 5 deletions(-) create mode 100644 docs/contracts/.gitkeep create mode 100644 docs/extensions/.gitkeep create mode 100644 schemas/extensions/.gitkeep create mode 100644 schemas/project-core/.gitkeep diff --git a/README.md b/README.md index be2daa1..cdf0e99 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,19 @@ make flatpak-build ``` Cargo.toml Cargo.lock +docs/ + adrs/ # Architecture decision records + contracts/ # API and behavior contracts (planning artifacts) + extensions/ # Extension model planning and examples + OPEN_QUESTIONS.md + ROADMAP.md + ARCHITECTURE.md +schemas/ + project-core/ # Core project schema artifacts + extensions/ # Domain-specific extension schema artifacts src/ └── main.rs (or lib.rs) +tests/ Makefile .envrc flake.nix @@ -126,6 +137,7 @@ See project.toml for example metadata. - [Roadmap](docs/ROADMAP.md) - [Architecture baseline](docs/ARCHITECTURE.md) - [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md) +- [Open questions and clarification plan](docs/OPEN_QUESTIONS.md) ## Helper Tools diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 69f2e4f..962739f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -25,6 +25,19 @@ Out of scope for early phases: - 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. @@ -68,6 +81,7 @@ Bundled web UI: - 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 diff --git a/docs/OPEN_QUESTIONS.md b/docs/OPEN_QUESTIONS.md index d81ae9c..4a1ec40 100644 --- a/docs/OPEN_QUESTIONS.md +++ b/docs/OPEN_QUESTIONS.md @@ -4,21 +4,79 @@ A living document of unresolved design and product questions. When a question is 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 is the canonical structure of a "project"? +**Q1 [P1]** What should the explicit versioning model look like? -- Is it steps + materials + media, or does it also include file attachments (patterns, templates, cut files)? -- Are steps ordered (sequential instructions) or unordered (reference material)? -- Do projects have explicit versioning/revision history, or only an updated timestamp? +- 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? diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 6bf8a4c..4b7be41 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -13,27 +13,33 @@ Goals: - Stabilize development environment and reproducible tooling. - Define domain language and baseline architecture docs. - Establish quality process (TDD/BDD + GitHub Flow). +- Clarify the core-plus-extension project contract before implementation. Exit criteria: - Agreed glossary and architecture baseline. - Documented contribution and branch workflow. - CI skeleton in place for formatting, linting, and tests. +- ADR for project revision lifecycle (draft/publish/supersede). +- ADR for composable extension mechanism (shape, namespacing, discovery). +- Initial repository layout includes dedicated locations for API contracts and extension schemas. ## Phase 1: Single-Node MVP (No Federation Yet) Goals: - User identity and basic authentication model. -- Core DIY project entities (project, materials, steps, media, tags). +- Core DIY project entities (project, materials, tools, steps, media, canonical links, tags). - Basic publishing lifecycle (draft, published, updated). - Search and browse within one instance. +- Support extension payloads in project data model without requiring domain-specific first-party implementations. Exit criteria: - A user can publish and update a complete project end-to-end. - Project pages are discoverable and readable on one node. - Test coverage exists for core behavior paths. +- At least one extension payload can be stored, validated, and rendered as non-breaking optional data. ## Phase 2: ActivityPub Foundation diff --git a/docs/contracts/.gitkeep b/docs/contracts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/extensions/.gitkeep b/docs/extensions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/schemas/extensions/.gitkeep b/schemas/extensions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/schemas/project-core/.gitkeep b/schemas/project-core/.gitkeep new file mode 100644 index 0000000..e69de29