Skip to content

roadmap.md

Latest commit

 

History

History
1079 lines (819 loc) · 36.9 KB

roadmap.md

File metadata and controls

1079 lines (819 loc) · 36.9 KB
Raw

Open Hardware Manager (OHM) - Project Roadmap

Document Status: Living Document
Last Updated: April 6, 2026
Purpose: Strategic roadmap for OHM development as the project transitions from solo development to collaborative team development.

Executive Summary

This roadmap focuses on maturing OHM from a working prototype to a production-grade distributed system suitable for real-world deployment. The core features are functional and the architecture is solid, so the emphasis shifts to:

  1. Quality & Reliability: End-to-end testing with real-world workflows
  2. Output Excellence: Improving the quality and usability of generated results
  3. Human-Centered Design: Making OHM data legible and actionable for humans
  4. Architectural Separation: Extracting business logic into a dedicated service
  5. Federated Network: Enabling distributed, eventually-consistent design synchronization

Current Implementation Status (April 2026)

  • Phase 1: Complete (quality baseline and core e2e coverage established).
  • Phase 2: Complete for demo-readiness scope (prompt tuning, confidence metadata, matching enhancements, hardening, integration/regression pass).
  • Phase 3.1: In progress with major API/CLI slices implemented:
    • Multi-level human summaries (executive, technical, detailed) for match responses
    • API request/response controls for summary inclusion
    • Suggestion and suggestion-code response fields for actionable guidance
  • Phase 3.3: In progress (API formatting and CLI readability/disclosure improvements underway).
  • Phase 3.2: Not started (visualization work deferred until 3.1/3.3 closeout).
  • Phase 4+: Not started.

Strategic Priorities

Priority 1: Quality & Testing (Q1 2026)

Goal: Ensure OHM reliably handles real-world workflows with confidence

Priority 2: Output Quality Improvements (Q1-Q2 2026)

Goal: Make OHM outputs accurate, complete, and trustworthy

Priority 3: Human-Readable Data & Visualization (Q2 2026)

Goal: Transform technical data into actionable insights for human users

Priority 4: Business Logic Separation (Q2-Q3 2026)

Goal: Architect and implement Open Business Manager (OBM) as a separate service

Priority 5: Federated Design Synchronization (2027)

Goal: Transform OHM into a distributed network of nodes with lazy synchronization, trust management, and security

Phase 1: Quality & End-to-End Testing

Overview

Core features work but lack comprehensive real-world validation. This phase establishes confidence through systematic testing of complete workflows.

1.1 Real-World Test Scenarios

Objective: Create test suites based on actual use cases

Tasks:

  • Define canonical test workflows

    • Design-to-manufacturer matching (complete pipeline)
    • OKH manifest generation from repository URL
    • Multi-facility distributed manufacturing scenarios
    • Quality validation across different contexts (hobby, professional, medical)

  • Build test data sets

    • Real hardware designs (OKH manifests)
    • Diverse facility profiles (OKW manifests)
    • Edge cases and boundary conditions
    • Invalid/malformed input scenarios

  • Create end-to-end test framework

    • Automated test harness for complete workflows
    • Performance benchmarks and regression detection
    • Success criteria and acceptance thresholds
    • Test result visualization and reporting

Deliverables:

  • Test suite with 20+ real-world scenarios
  • Automated CI/CD test pipeline
  • Test coverage report and baseline metrics

GitHub Issues:

  • Define canonical test workflows for design-to-manufacturing
  • Create diverse OKH/OKW test dataset
  • Build end-to-end test framework with automation
  • Establish performance benchmarks and regression tests

1.2 Matching Service Quality Improvements

Objective: Enhance matching accuracy, reliability, and transparency

Tasks:

  • Matching accuracy assessment

    • Baseline accuracy metrics for each matching layer (Direct, Heuristic, NLP, LLM)
    • False positive/negative analysis
    • Confidence score calibration
    • Layer performance comparison

  • Matching algorithm refinement

    • Optimize heuristic rules based on test results
    • Improve NLP semantic similarity thresholds
    • Fine-tune LLM prompts for better reasoning
    • Enhance scoring and ranking algorithms

  • Matching transparency

    • Detailed match explanations (why facilities matched/didn't match)
    • Confidence score breakdowns by layer
    • Alternative match suggestions
    • Match quality indicators

Deliverables:

  • Matching accuracy report with improvement targets
  • Refined matching algorithms with documented changes
  • Transparency features in match results

GitHub Issues:

  • Establish matching accuracy baseline metrics
  • Analyze and reduce false positives/negatives
  • Refine heuristic rules based on test data
  • Add match explanation and transparency features

1.3 OKH Generation Service Quality

Objective: Improve quality and reliability of OKH manifest generation from repository URLs

Tasks:

  • Generation accuracy assessment

    • Test against diverse repository types (GitHub, GitLab, various project structures)
    • Completeness analysis (required fields, optional fields, metadata)
    • Correctness validation (extracted data matches reality)
    • Edge case handling (mono-repos, minimal documentation, multi-language projects)

  • LLM prompt optimization

    • Refine prompts for better extraction accuracy
    • Add explicit validation instructions
    • Improve handling of ambiguous or missing information
    • Test across different LLM providers for consistency

  • Generation result validation

    • Automated quality checks on generated manifests
    • Confidence indicators for extracted fields
    • Suggestion system for incomplete data
    • User feedback loop for improvements

Deliverables:

  • OKH generation quality report
  • Optimized LLM prompts with version control
  • Automated validation and quality scoring

GitHub Issues:

  • Test OKH generation across diverse repository types
  • Optimize LLM prompts for extraction accuracy
  • Implement automated quality checks for generated manifests
  • Add confidence indicators and suggestions for incomplete data

Phase 2: Output Quality & Demo Readiness

Overview

Status (April 2026): Completed for summit demo scope; post-demo maintenance only.

Phase 2 is scoped around the May 23, 2026 Open Hardware Summit talk (Building Supply Chain Mesh Networks). The talk demonstrates how OKH/OKW standards, automated matching, and supply tree generation enable resilient supply chain mesh networks — directly addressing the coordination failures exposed by the COVID-19 crisis.

The demo flow: take a real COVID-era open hardware repo → generate a complete OKH manifest → match against available facilities → display the supply tree. The audience is the OSHWA community: hardware-literate makers, open-source advocates, and disaster-response practitioners who will evaluate whether this is credible, real infrastructure.

Feature freeze: May 8, 2026. Only stability fixes after that date.

Detail: See notes/phase2-plan.md for timeline, target demo repositories, and per-item acceptance criteria.

2.1 LLM Prompt Tuning (carried from 1.3.2)

Objective: Manifests generated live on stage must be complete and credible to a hardware-literate audience.

Tasks:

  • Tune extraction prompts for hardware-specific fields: bom, manufacturing-files, license, documentation-language, standards-used
  • Improve handling of sparse or minimally-documented repos (common in crisis hardware projects)
  • Verify consistent output across providers (Anthropic, OpenAI, local Ollama)
  • Batch evaluation against canary corpus; gate on no regression vs. Phase 1 baseline

Deliverables:

  • Tuned prompt templates with version history
  • Evaluation report showing field-level completeness vs. baseline

2.2 Confidence Indicators on Generated Fields (carried from 1.3.4)

Objective: A technical audience trusts a system more when it honestly signals uncertainty.

Tasks:

  • Surface per-field confidence scores in manifest JSON output
  • Add top-level generation_confidence summary and low_confidence_fields list
  • CLI: display confidence alongside field values in --verbose mode
  • API: include confidence metadata in the manifest response envelope

Deliverables:

  • Confidence visible in JSON output, CLI, and API response
  • No regression in generation accuracy

2.3 Matching Result Enhancement

Objective: The match output is one of the two core things being demonstrated — it must be readable, complete, and credible.

Tasks:

  • Ensure all relevant facility details are included in match results (capabilities, location, certifications)
  • Improve result ranking: sort by confidence + capability coverage
  • Add a human-readable match summary per result (what matched, what was missing, overall fit)
  • API: add match_summary and coverage_gaps fields to match result schema
  • CLI: make --explain output the default in verbose mode

Deliverables:

  • Enhanced match result schema with ranking and summaries
  • Updated CLI verbose output

2.4 End-to-End Pipeline Reliability

Objective: The full repo URL to manifest to match to supply tree flow must work without errors on stage.

Tasks:

  • Run the full pipeline on 5 COVID-era hardware repos; document and fix any failures
  • Ensure graceful error handling at each stage (no uncaught exceptions, clear fallback messaging)
  • Verify pipeline works with both Anthropic and local Ollama model
  • Time the end-to-end flow; target under 90 seconds for live generation

Deliverables:

  • Zero crashes on 5 target repos
  • Graceful degradation when fields cannot be extracted

2.5 System Mode: Minimal / Standard / Strict

Objective: Maps directly to the disaster-response narrative. "In a crisis, you run Minimal mode — coverage and dependency checks only — because a partial supply tree in 10 seconds beats a perfect one in 10 minutes."

Tasks:

  • Define centralized SystemMode config with preset modes: minimal, standard, strict
  • minimal: coverage + dependency checks only; relaxed thresholds; designed for low-data, off-grid, crisis contexts
  • standard: adds quality and completeness checks (current default behavior)
  • strict: all validations and thresholds enforced
  • CLI: --mode minimal|standard|strict flag
  • Apply mode to supply tree validation, matching thresholds, and manifest quality checks
  • Documentation with humanitarian use-case framing

Deliverables:

  • System Mode schema and config integration
  • Preset modes with CLI flag
  • Validation framework updated to honor System Mode

2.6 CI Regression Hooks (carried from 1.3.1 Phase C)

Objective: Prevent regressions in the weeks before the talk.

Tasks:

  • Parametrized e2e tests for generation pipeline (ground-truth repos)
  • Regression flag if required-field completeness drops below Phase 1 baseline
  • CI gate on the chunked canary evaluation script

Deliverables:

  • CI runs clean on main branch
  • Automated regression detection for generation quality

Deferred to Phase 3

The following items from the original Phase 2 roadmap are deferred. They have lower demo impact relative to effort, or require more than 6 weeks to execute well.

Item Notes
1.3.1 Phase B2 — ground truth expansion Internal quality tooling; not visible in demo
1.3.3 — Automated quality checks on manifests Internal; low demo value
OKH manifest quality scoring and suggestions Useful but not critical for demo narrative
Supply tree quality optimization Complex; current supply tree sufficient for demo
Phase 3 — Visualization High demo value but needs more than 6 weeks

Phase 3: Human-Readable Data & Visualization

Overview

OHM generates highly technical data that is difficult for humans to parse and understand. This phase focuses on making data accessible, interpretable, and actionable.

Status (April 2026): Active. 3.1 and 3.3 are closed out; 3.2 visualization implementation is in progress.

3.1 Data Abstraction & Summarization

Objective: Transform technical data into human-understandable summaries

Status (April 2026): Complete for current scope. Deterministic key insights, role-oriented summary profiles, and API/CLI summary disclosure are implemented and validated.

Tasks:

  • LLM-powered summarization (future enhancement)

    • Natural language explanations of matching results
    • Executive summaries of supply trees
    • Plain language facility descriptions
    • Requirement/capability comparison narratives

  • Key insight extraction

    • Identify critical information automatically
    • Highlight risks and opportunities
    • Surface actionable recommendations
    • Provide decision-support summaries

  • Multi-level abstraction

    • Executive overview (non-technical)
    • Technical summary (for practitioners)
    • Detailed data (for deep analysis)
    • Customizable detail levels per user role

Deliverables:

  • LLM summarization service
  • Multi-level abstraction framework
  • User role-based view system

GitHub Issues:

  • Implement LLM-powered data summarization
  • Create key insight extraction algorithms
  • Design multi-level abstraction system
  • Build role-based view customization

3.2 Data Visualization

Objective: Create visual representations of OHM data

Status (April 2026): In progress. API/CLI-first visualization artifacts and contracts are now being implemented.

Tasks:

  • [~] Matching visualization

    • Facility map with match quality indicators
    • Capability coverage heat maps
    • Match confidence visualizations
    • Timeline and capacity charts

  • [~] Supply tree visualization

    • Interactive tree diagrams
    • Process flow charts
    • Dependency graphs
    • Resource allocation views

  • [~] Network visualization

    • Geographic facility distribution
    • Capability network graphs
    • Production capacity maps
    • Route optimization displays

  • [~] Dashboard & reporting

    • Project overview dashboards
    • KPI tracking and metrics
    • Trend analysis and forecasting
    • Exportable reports (PDF, HTML)

Deliverables:

  • Visualization library and components
  • Interactive dashboard framework
  • Export and reporting system

GitHub Issues:

  • Create matching result visualization components
  • Build interactive supply tree diagrams
  • Implement network and geographic visualizations
  • Design project dashboard and reporting system

3.3 User Interface Improvements

Objective: Make OHM more accessible through improved interfaces

Status (April 2026): Complete for current scope. API and CLI formatting/disclosure improvements are complete; web UI remains optional/future.

Tasks:

  • API response formatting

    • Human-readable response structure
    • Consistent formatting across endpoints
    • Helpful error messages and suggestions
    • Progressive disclosure of detail

  • CLI output improvements

    • Improved table formatting
    • Color-coded indicators
    • Progress bars and status updates
    • Interactive prompts and wizards

  • Web UI exploration (Optional/Future)

    • Consider web-based interface for non-technical users
    • Visual query builder
    • Interactive result exploration
    • Collaborative project management

Deliverables:

  • Enhanced API response schemas
  • Improved CLI formatting utilities
  • Web UI prototype (if pursued)

GitHub Issues:

  • Enhance API response formatting for readability
  • Improve CLI output with better formatting and color
  • Add progress indicators and status updates
  • Design web UI prototype and gather user feedback

Phase Transition Note (April 2026)

Phase 3 is complete for current scope (3.1, 3.2, 3.3). Execution focus has shifted to Phase 4, starting with a lightweight demo frontend that remains API-first and presentation-oriented.

Active execution checklist:

  • notes/phase4-demo-frontend-execution-checklist.md

Phase 4: Business Logic Separation - Open Business Manager (OBM)

Overview

OHM currently contains or plans to contain business logic (RFQ generation, pricing, contracts) that should be separated into a dedicated service. This phase architects and implements Open Business Manager (OBM).

4.1 OBM Requirements & Architecture

Objective: Define what OBM does and how it integrates with OHM

Tasks:

  • Scope definition

    • Identify all business logic features (current and planned)
    • Define OBM boundaries and responsibilities
    • Clarify OHM/OBM separation of concerns
    • Identify shared data and interfaces

  • Containerization and deployment compatibility

    • Define containerization standards for OHM and OBM
    • Support co-located deployment (same network)
    • Support distributed deployment (separate networks)
    • Support fully independent operation
    • Align with industry best practices (12-factor, health checks, readiness probes)

  • Feature inventory

    • Request for Quote (RFQ) generation
    • Pricing and cost estimation
    • Contract management
    • Order tracking and fulfillment
    • Invoice and payment processing
    • Supplier relationship management
    • Business analytics and reporting

  • Architecture design

    • Service communication protocol (REST API, gRPC, message queue)
    • Data models and schemas
    • Authentication and authorization
    • Deployment and scaling strategy
    • Dependency management

Deliverables:

  • OBM scope document
  • Feature specification
  • Architecture decision records (ADRs)

GitHub Issues:

  • Define OBM scope and responsibilities
  • Create feature inventory for business logic
  • Design OBM/OHM integration architecture
  • Document service communication patterns

4.2 OBM Core Features

Objective: Implement essential business logic features in OBM

Tasks:

  • RFQ generation

    • Automatic RFQ creation from match results
    • Customizable RFQ templates
    • Multi-facility RFQ distribution
    • RFQ tracking and status

  • Cost estimation

    • Facility pricing integration
    • Material cost calculation
    • Lead time and scheduling
    • Multi-scenario cost comparison

  • Contract & order management

    • Contract generation and tracking
    • Order placement and confirmation
    • Status updates and notifications
    • Fulfillment tracking

  • Financial operations

    • Invoice generation
    • Payment tracking
    • Currency handling
    • Tax and compliance

Deliverables:

  • OBM service implementation
  • API endpoints for business operations
  • Integration points with OHM

GitHub Issues:

  • Implement RFQ generation service
  • Build cost estimation module
  • Create contract and order management system
  • Add financial operations features

4.3 OBM/OHM Integration

Objective: Seamless integration between technical matching (OHM) and business operations (OBM)

Tasks:

  • Data exchange

    • Define data contracts between services
    • Implement data transformation layers
    • Handle versioning and compatibility
    • Error handling and retry logic

  • Workflow orchestration

    • End-to-end workflows spanning both services
    • Transaction coordination
    • Event-driven updates
    • State management

  • User experience

    • Unified API gateway (optional)
    • Consistent authentication
    • Coordinated error handling
    • Integrated documentation

Deliverables:

  • Integration layer
  • Workflow orchestration system
  • Combined API documentation

GitHub Issues:

  • Define data contracts between OHM and OBM
  • Implement data transformation and exchange layer
  • Create end-to-end workflow orchestration
  • Build unified API gateway (optional)

Phase 5: Federated Design Synchronization

Overview

Transform OHM from a centralized architecture to a federated network of nodes. This enables regional OHM deployments to lazily synchronize OKH designs across a distributed network, forming an eventually consistent global pool of open hardware designs while maintaining regional autonomy.

5.1 Network Architecture & Protocol Design

Objective: Design and implement the foundational distributed network architecture

Tasks:

  • Network topology design

    • Define node types (full nodes, lightweight nodes, archive nodes)
    • Design peer discovery mechanisms
    • Define network roles and responsibilities
    • Document federation architecture patterns

  • Gossip protocol implementation

    • Implement efficient gossip propagation algorithm
    • Design message prioritization and routing
    • Add network partition tolerance
    • Optimize bandwidth usage

  • Merkle tree synchronization

    • Design OKH manifest content addressing
    • Implement Merkle tree structure for design collections
    • Create efficient diff and sync algorithms
    • Add incremental update mechanisms

  • Node discovery and bootstrap

    • Implement bootstrap node system
    • Design peer discovery protocols (DHT, DNS, manual)
    • Add dynamic peer management
    • Create node health monitoring

Deliverables:

  • Federated network architecture document
  • Gossip protocol implementation
  • Merkle tree sync library
  • Node discovery service

GitHub Issues:

  • Design federated network topology and node types
  • Implement gossip protocol for design propagation
  • Build Merkle tree synchronization system
  • Create node discovery and bootstrap mechanism

5.2 Trust and Security Framework

Objective: Establish trust relationships and security measures for federated network

Tasks:

  • Identity and authentication

    • Implement node identity system (public key infrastructure)
    • Design node authentication protocols
    • Create identity verification mechanisms
    • Add key rotation and revocation

  • Trust relationship management

    • Design trust scoring system for nodes
    • Implement reputation tracking
    • Create trust policy configuration
    • Add trust relationship visualization

  • Content verification

    • Implement cryptographic signing of OKH manifests
    • Design content integrity verification
    • Add provenance tracking (design lineage)
    • Create signature validation system

  • Access control and permissions

    • Design node-level access control
    • Implement content filtering policies
    • Add permission delegation mechanisms
    • Create audit logging system

Deliverables:

  • Node identity and authentication system
  • Trust management framework
  • Content signing and verification system
  • Access control policies

GitHub Issues:

  • Implement PKI-based node identity system
  • Build trust scoring and reputation tracking
  • Create cryptographic signing for OKH manifests
  • Design and implement access control framework

5.3 Security and Malware Defense

Objective: Protect the federated network against malicious actors and malware distribution

Tasks:

  • Malware detection

    • Design OKH manifest static analysis
    • Implement suspicious pattern detection
    • Add automated security scanning
    • Create malware signature database

  • Sandboxing and isolation

    • Implement safe manifest parsing
    • Design isolated validation environments
    • Add resource limits and quotas
    • Create execution sandboxes for untrusted content

  • Rate limiting and abuse prevention

    • Implement node-level rate limiting
    • Design anti-spam mechanisms
    • Add DDoS protection
    • Create resource exhaustion prevention

  • Adversarial behavior detection

    • Design anomaly detection algorithms
    • Implement behavioral analysis
    • Add automated threat response
    • Create incident reporting system

  • Network security

    • Implement encrypted node communication (TLS)
    • Design secure key exchange
    • Add network traffic monitoring
    • Create intrusion detection system

Deliverables:

  • Malware detection service
  • Sandboxing infrastructure
  • Rate limiting and abuse prevention system
  • Security monitoring dashboard

GitHub Issues:

  • Build OKH manifest static analysis and malware detection
  • Implement sandboxing for untrusted content
  • Create rate limiting and anti-abuse mechanisms
  • Design anomaly detection and threat response system

5.4 Synchronization and Consistency

Objective: Ensure efficient and reliable data synchronization across the federated network

Tasks:

  • Sync protocols

    • Implement lazy synchronization algorithms
    • Design conflict resolution strategies
    • Add version vector management
    • Create sync scheduling and prioritization

  • Eventual consistency guarantees

    • Define consistency models
    • Implement convergence verification
    • Add consistency monitoring
    • Create consistency repair mechanisms

  • Bandwidth optimization

    • Implement delta synchronization
    • Design compression for network transfers
    • Add deduplication mechanisms
    • Create adaptive sync strategies based on network conditions

  • Partial replication

    • Design selective sync policies (regional, topical)
    • Implement interest-based filtering
    • Add storage quota management
    • Create pruning and garbage collection

Deliverables:

  • Lazy sync protocol implementation
  • Conflict resolution system
  • Bandwidth optimization suite
  • Partial replication framework

GitHub Issues:

  • Implement lazy synchronization algorithms
  • Build conflict resolution and version management
  • Create bandwidth optimization and compression
  • Design partial replication and filtering system

5.5 Federation Management and Monitoring

Objective: Provide tools for managing and monitoring federated nodes

Tasks:

  • Node management

    • Design node configuration system
    • Implement node lifecycle management
    • Add federation policy management
    • Create node upgrade mechanisms

  • Monitoring and observability

    • Implement network health monitoring
    • Design sync status dashboards
    • Add performance metrics collection
    • Create alerting for network issues

  • Network analytics

    • Track design propagation patterns
    • Analyze network topology
    • Monitor trust relationships
    • Create network health reports

  • Administration tools

    • Build CLI for federation management
    • Design API for programmatic control
    • Add troubleshooting utilities
    • Create federation documentation

Deliverables:

  • Node management system
  • Monitoring dashboard
  • Network analytics platform
  • Administration tooling

GitHub Issues:

  • Build node management and configuration system
  • Create network monitoring and observability tools
  • Implement network analytics and reporting
  • Design CLI and API for federation administration

5.6 Migration and Compatibility

Objective: Enable smooth transition from centralized to federated architecture

Tasks:

  • Backward compatibility

    • Maintain existing API compatibility
    • Design hybrid mode (centralized + federated)
    • Add graceful degradation
    • Create migration documentation

  • Data migration tools

    • Build tools to export from centralized storage
    • Design import to federated nodes
    • Add migration validation
    • Create rollback mechanisms

  • Gradual rollout

    • Design phased deployment strategy
    • Implement feature flags for federation
    • Add A/B testing capabilities
    • Create rollback procedures

  • Testing and validation

    • Build federation test environment
    • Design chaos engineering tests
    • Add network partition simulation
    • Create performance benchmarks

Deliverables:

  • Backward compatibility layer
  • Migration toolkit
  • Deployment strategy documentation
  • Federation test suite

GitHub Issues:

  • Ensure backward compatibility with centralized mode
  • Build data migration tools and validation
  • Design phased deployment and rollout strategy
  • Create federation testing and simulation environment

Phase 6: Design Version Management

Overview

Design versioning ensures end users can discover, validate, and pull specific vetted versions of a full design package (manifest + linked files). This builds on existing package and storage systems while adding version metadata, certification states, and version-aware retrieval.

6.1 Versioned Design Packages

Objective: Enable version-aware discovery, validation, and retrieval of complete design packages

Tasks:

  • Define design version model and metadata

    • Version identifiers (semantic or content-addressed)
    • Status states (draft, tested, certified, deprecated)
    • Link version metadata to OKH manifests and file bundles

  • Extend package and storage systems for versioned designs

    • Store versioned bundles (manifest + all referenced files)
    • Enable retrieval by version, latest, and certified
    • Add integrity checks (checksums for all files)

  • Version discovery and validation

    • Search and filter by version status and certification
    • Surface test/certification metadata in results
    • Validate completeness of versioned bundles

  • API/CLI integration and documentation

    • Add CLI commands to list and pull versions
    • Add API endpoints for versioned retrieval
    • Document versioning workflows and certification signals

Deliverables:

  • Design version metadata schema and status model
  • Versioned bundle storage and retrieval layer
  • Version-aware discovery and validation endpoints
  • CLI commands and documentation for version management

GitHub Issues:

  • Define design version model and OKH metadata extensions
  • Implement versioned bundle storage and retrieval
  • Add version discovery and certification filtering
  • Build version validation and integrity checks

Cross-Cutting Concerns

Documentation

Ongoing throughout all phases

Tasks:

  • Maintain comprehensive API documentation
  • Create user guides for each feature
  • Document architectural decisions
  • Provide runnable examples and tutorials
  • Keep roadmap document updated
  • Automate publishing canonical OKH schema to external repositories

Testing

Ongoing throughout all phases

Tasks:

  • Unit tests for all new features
  • Integration tests for service interactions
  • End-to-end tests for complete workflows
  • Performance and load testing
  • Security testing and validation

DevOps & Infrastructure

Ongoing throughout all phases

Tasks:

  • CI/CD pipeline maintenance
  • Container and deployment optimization
  • Monitoring and alerting
  • Backup and disaster recovery
  • Cost optimization

Success Metrics

Quality Metrics

  • Match accuracy: >90% for direct and heuristic layers
  • OKH generation completeness: >85% for well-documented repos
  • Supply tree validation pass rate: >95%
  • User-reported error rate: <5%

Usability Metrics

  • Time to first successful match: <5 minutes (new users)
  • API response clarity score: >4/5 (user surveys)
  • CLI usability score: >4/5 (user surveys)
  • Documentation completeness: 100% of features documented

Performance Metrics

  • API response time: p95 <2s for matching operations
  • OKH generation: <30s for typical repository
  • Uptime: >99.5%
  • Test coverage: >80%

Federation Metrics (Phase 5)

  • Sync latency: p95 <5 minutes for design propagation across network
  • Network availability: >99% node uptime
  • Trust score accuracy: <2% false positives for malicious content
  • Bandwidth efficiency: <10MB/hour average per node
  • Conflict resolution success rate: >98%
  • Network partition recovery: <1 hour to full consistency

Timeline & Phases

Q1 2026 (Jan-Mar) — Phase 1 (Complete)

  • Focus: Quality & Testing
  • Milestones:
    • Real-world test suite complete
    • Matching service quality baseline established (F1 0.807 to 0.992)
    • LLM chunking architecture implemented; all canary quality gates passing

Q2 2026 (Apr-Jun) — Phase 2 (Completed) / Phase 3 (Started)

  • Focus: Demo closeout and transition into human-readable API/CLI output
  • Hard deadline: May 23, 2026 — Open Hardware Summit talk
  • Feature freeze: May 8, 2026
  • Milestones:
    • LLM prompt tuning complete; generation quality improved
    • Confidence indicators visible in manifest output
    • Matching result enhancement with ranking and summaries
    • End-to-end pipeline reliability validated on target COVID-era repos
    • Phase 3.1/3.3 implementation started (API/CLI summary and formatting slices)

Q3 2026 (Jul-Sep)

  • Focus: OBM Implementation, OHM/OBM Integration
  • Milestones:
    • OBM core features implemented
    • OHM/OBM integration complete
    • End-to-end business workflows functional

Q4 2026 (Oct-Dec)

  • Focus: Refinement, Documentation, Production Hardening
  • Milestones:
    • All features production-ready
    • Comprehensive documentation complete
    • Performance and reliability targets met

Q1-Q2 2027 (Jan-Jun)

  • Focus: Federated Network Architecture (Phase 5)
  • Milestones:
    • Gossip protocol and Merkle sync implemented
    • Trust and security framework deployed
    • Malware defense system operational

Q3-Q4 2027 (Jul-Dec)

  • Focus: Federation Rollout and Stabilization
  • Milestones:
    • Multi-node testing complete
    • Production federation network launched
    • Network monitoring and management tools deployed

Contributing

This roadmap is a living document. As development progresses and priorities shift, it will be updated to reflect the current strategic direction.

How to Use This Roadmap

  1. For Contributors: Choose tasks aligned with your interests and skills
  2. For Planning: Break down tasks into GitHub issues with appropriate labels
  3. For Prioritization: Use phase ordering and dependencies to sequence work
  4. For Tracking: Update task completion status and add notes/learnings

GitHub Issue Labels

When decomposing this roadmap into issues, use these labels:

Priority Labels

  • priority-1: Critical for next release
  • priority-2: Important but not urgent
  • priority-3: Nice to have

Phase Labels

  • phase-1: Quality & Testing
  • phase-2: Output Quality
  • phase-3: Human-Readable Data
  • phase-4: OBM Separation
  • phase-5: Federated Network

Component Labels

  • component-matching: Matching service
  • component-okh: OKH generation/management
  • component-visualization: Data visualization
  • component-obm: Business logic
  • component-federation: Federated network features
  • component-security: Security and trust framework
  • component-sync: Synchronization and consistency

Type Labels

  • testing: Test-related tasks
  • documentation: Documentation tasks
  • security: Security-related tasks
  • infrastructure: Infrastructure and networking
  • good-first-issue: Suitable for new contributors

Questions & Discussions

Open Questions

General

  1. OBM Deployment: Should OBM be containerized separately or as part of a multi-service deployment?
  2. Visualization Technology: What library/framework for data visualization? (D3.js, Plotly, custom?)
  3. Web UI: Is a web UI a priority, or should we focus on API/CLI improvements?
  4. LLM Usage: How do we balance LLM power vs. cost for summarization features?
  5. Multi-tenancy: Do we need to support multiple organizations/users with data isolation?

Federation-Specific

  1. Gossip Protocol: Which gossip protocol variant? (Epidemic, anti-entropy, rumor-mongering?)
  2. Identity System: PKI-based or alternative identity system (DIDs, blockchain-based)?
  3. Content Addressing: IPFS-style content addressing or custom Merkle DAG?
  4. Bootstrap Nodes: Who operates bootstrap nodes? Centralized trust or distributed?
  5. Malware Detection: Static analysis only, or sandboxed execution for validation?
  6. Network Incentives: Should there be incentives for running nodes? Token-based or reputation-only?
  7. Storage Limits: How much storage should a node be expected to maintain?
  8. Backwards Compatibility: How long should we maintain hybrid centralized/federated mode?

Discussion Topics

General

  1. OBM Scope: What business features are essential vs. nice-to-have?
  2. Data Privacy: How do we handle sensitive business data (pricing, contracts)?
  3. Integration Patterns: Event-driven vs. request-response for OHM/OBM communication?
  4. Extensibility: Plugin architecture for custom business logic?

Federation-Specific

  1. Federation Governance: How are network-wide decisions made? Consensus mechanisms?
  2. Trust Models: Web of trust, certificate authorities, or hybrid approach?
  3. Conflict Resolution: CRDT-based, last-write-wins, or manual resolution?
  4. Network Topology: Fully decentralized, super-nodes/hub architecture, or regional hierarchies?
  5. Legal Compliance: How do we handle regulatory requirements across jurisdictions?
  6. Malicious Node Response: Automatic blacklisting, manual review, or community voting?
  7. Design Licensing: How do we ensure license compliance in federated sync?
  8. Version Conflicts: How do nodes handle incompatible OHM versions?