{"id":36753794,"url":"https://github.com/openshift-hyperfleet/architecture","last_synced_at":"2026-01-12T12:47:39.876Z","repository":{"id":320042112,"uuid":"1080566275","full_name":"openshift-hyperfleet/architecture","owner":"openshift-hyperfleet","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-31T01:09:36.000Z","size":792,"stargazers_count":2,"open_issues_count":6,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-01T11:10:02.933Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openshift-hyperfleet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T14:47:14.000Z","updated_at":"2025-12-31T01:09:40.000Z","dependencies_parsed_at":"2025-10-21T17:22:25.647Z","dependency_job_id":"568a5445-c51e-49fb-b651-ba675c440335","html_url":"https://github.com/openshift-hyperfleet/architecture","commit_stats":null,"previous_names":["openshift-hyperfleet/architecture"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/openshift-hyperfleet/architecture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Farchitecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Farchitecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Farchitecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Farchitecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openshift-hyperfleet","download_url":"https://codeload.github.com/openshift-hyperfleet/architecture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Farchitecture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T12:47:39.807Z","updated_at":"2026-01-12T12:47:39.868Z","avatar_url":"https://github.com/openshift-hyperfleet.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperFleet Architecture Repository\n\n**Status**: Active  \n**Owner**: Architecture Team  \n**Last Updated**: 2025-10-22  \n\n---\n\n## Purpose\n\nThis repository serves as the **single source of truth** for all architectural documentation related to HyperFleet. All documents are **living documents** that evolve as the design and implementation progress.\n\n**Key Principle**: All significant architectural decisions must be documented here with their trade-offs to track technical debt and enable informed future decisions.\n\n---\n\n## Repository Access \u0026 MVP Process\n\n**Current Phase**: MVP Development\n\n**Access \u0026 Permissions**:\n- All developers in the HyperFleet team are granted **write access** to this repository\n- To support quick iteration during MVP, developers have **approve and merge access** if there are no objections from peers\n- This temporary process enables rapid documentation of decisions and scope changes\n\n**Repository Usage**:\n- This repository primarily records:\n  - Architectural decisions and their rationale\n  - Trade-offs we're accepting during MVP\n  - Changes to MVP scope and priorities\n  - Technical debt we're consciously incurring\n\n**Post-MVP**:\n- Once MVP is complete, we will establish official processes for:\n  - Repository access management\n  - PR review requirements\n  - Approval workflows\n  - Documentation governance\n\n**During MVP, prioritize speed over process while maintaining clear documentation of decisions.**\n\n---\n\n## Repository Structure\n\n```\narchitecture/\n├── README.md                      # This file - repository guide\n├── hyperfleet/                    # HyperFleet-specific architecture\n│   ├── architecture/              # 30,000 feet view (system-level)\n│   │   ├── architecture-summary.md\n│   │   ├── component-diagram.md\n│   │   ├── data-flow-diagram.md\n│   │   └── deployment-architecture.md\n│   ├── components/                # Component-level design decisions\n│   │   ├── api.md\n│   │   ├── sentinel.md\n│   │   ├── message-broker.md\n│   │   ├── adapters.md\n│   │   └── database.md\n│   └── docs/                      # Implementation guides and features\n│       ├── status-guide.md\n│       ├── adapter-development-guide.md\n│       ├── deployment-guide.md\n│       └── monitoring-guide.md\n```\n\n---\n\n## Document Types\n\n### 1. Architecture Documents (`architecture/`)\n\n**Purpose**: High-level system architecture (30,000 feet view)\n\n**Contents**:\n- System overview and goals\n- Component relationships and interactions\n- Data flows and communication patterns\n- Deployment topology\n- Cross-cutting concerns (security, scalability, observability)\n\n**When to create**: Major system redesigns, new architecture proposals\n\n**Living Document**: Update as system architecture evolves\n\n---\n\n### 2. Component Design Documents (`components/`)\n\n**Purpose**: Detailed design for individual components\n\n**Required Sections**:\n- **What**: Component purpose and responsibilities\n- **Why**: Problem it solves and context\n- **How**: Technical implementation approach\n- **Trade-offs**: What we gain vs what we lose (REQUIRED)\n- **Dependencies**: What this component relies on\n- **Interfaces**: APIs, events, data contracts\n- **Configuration**: How to configure the component\n- **Alternatives Considered**: What we didn't choose and why\n\n**When to create**: New component introduction, major component redesign\n\n**Living Document**: Update as component design evolves during implementation\n\n---\n\n### 3. Implementation Guides (`docs/`)\n\n**Purpose**: Practical guides for developers and operators\n\n**Contents**:\n- Step-by-step instructions\n- Code examples and patterns\n- Configuration examples\n- Troubleshooting tips\n- Best practices\n\n**When to create**: New feature implementation, operational procedures\n\n**Living Document**: Keep examples current as APIs and configurations change\n\n---\n\n## Tracking Trade-offs and Technical Debt\n\n**Critical Requirement**: Every component design document MUST include both:\n1. **\"Trade-offs\" section** - What we gain and lose with the chosen approach\n2. **\"Alternatives Considered\" section** - What other options existed and why we didn't choose them\n\nThese sections work together to provide full context for architectural decisions.\n\n### Trade-offs Template\n\n```markdown\n## Trade-offs\n\n### What We Gain\n- ✅ Benefit 1 with measurable impact\n- ✅ Benefit 2 with context\n- ✅ Benefit 3\n\n### What We Lose / What Gets Harder\n- ❌ Cost 1 - Technical debt we're accepting\n- ❌ Cost 2 - Capability we're giving up\n- ⚠️ Risk 1 - What could go wrong\n\n### Technical Debt Incurred\n- **Debt Item 1**: Description of shortcut taken, impact, remediation plan\n- **Debt Item 2**: What we should fix in the future\n\n### Acceptable Because\n- Reason 1 why the trade-off makes sense\n- Reason 2 (e.g., time constraints, simplicity, MVP scope)\n```\n\n### Example: Sentinel Direct Broker Publishing\n\n```markdown\n## Trade-offs\n\n### What We Gain\n- ✅ Simpler architecture (5 components vs 6)\n- ✅ Lower latency (no outbox polling)\n- ✅ Easier to understand and maintain\n\n### What We Lose / What Gets Harder\n- ❌ Eventual consistency (not guaranteed delivery like outbox pattern)\n- ❌ No transactional event creation with database writes\n- ⚠️ Risk of events lost if broker is down and Sentinel crashes\n\n### Technical Debt Incurred\n- **No event delivery guarantees**: If Sentinel publishes to broker and crashes before updating internal state, we may duplicate events\n  - **Impact**: Low (adapters are idempotent)\n  - **Remediation**: Post-MVP, add event deduplication in adapters or message broker\n\n### Acceptable Because\n- MVP scope prioritizes simplicity over perfect consistency\n- Cluster provisioning use case tolerates eventual consistency\n- Adapters are designed to be idempotent\n```\n\n---\n\n## Living Documents\n\nAll documents in this repository are **living documents**:\n\n- **Update freely** as design evolves\n- **Mark status** to indicate maturity (Draft, Active, Deprecated)\n- **Track changes** via git commit history\n- **Pay down debt** by updating \"Technical Debt Incurred\" sections\n\n### Document Status\n\n- **Draft**: Initial design, still being refined\n- **Active**: Current implementation\n- **Deprecated**: No longer used (link to replacement)\n\n### Updating Documents\n\n**When to update \"Last Updated\" date:**\n\nUpdate the date for **meaningful changes only**:\n- ✅ Component design changes\n- ✅ New sections added\n- ✅ Trade-offs modified\n- ✅ Status changes (Draft → Active, Active → Deprecated)\n- ✅ Technical debt paid down or added\n- ❌ NOT for typos, formatting, or minor clarifications\n\n**Note**: Git commit history tracks all changes. The \"Last Updated\" date is a quick visual indicator of the last **significant** revision.\n\n**Steps for meaningful updates:**\n1. Update the relevant sections\n2. Update \"Last Updated\" date at the top of the document\n3. If paying down technical debt, ~~strikethrough~~ the debt item and link to PR\n\nExample of paying down technical debt:\n```markdown\n### Technical Debt Incurred\n- ~~**No retry logic**: Adapters don't retry failed operations~~\n  - **Status**: Resolved in #123\n  - **Resolution**: Added exponential backoff retry logic\n```\n\n### Review and Merge Process\n\n**MVP Process (Current)**:\n\nAll HyperFleet team developers have approve and merge access. **Goal**: Move fast while keeping the team informed.\n\n**How to submit and merge changes:**\n\n1. **Create a PR** with your documentation updates\n2. **Add a clear description** of what changed and why\n3. **Post the PR link** in Slack: #hcm-hyperfleet-team for team visibility\n4. **Wait 24 hours** for peer review and objections (accounts for time zone differences between regions)\n   - For urgent changes, use judgment but ensure the change is well-documented with clear rationale\n   - For major architectural changes, strongly consider waiting for at least one or two Technical Leader reviews\n5. **Merge when ready**: Once you have approval from peers and no objections after the 24-hour window, you may merge\n\n**Post-MVP Process** (to be established):\n- Formal approval requirements based on change type\n- Required reviewers for different document categories\n- Defined merge timelines and escalation paths\n\n---\n\n## Navigation Guide\n\n### I want to...\n\n**Understand HyperFleet architecture**\n→ Start with `hyperfleet/architecture/architecture-summary.md`\n\n**Design a new component**\n→ Add document to `hyperfleet/components/` with required sections (see \"Component Design Documents\")\n\n**Write an implementation guide**\n→ Add guide to `hyperfleet/docs/` with step-by-step instructions\n\n**Find trade-offs for a component**\n→ Read component document in `hyperfleet/components/`, look for \"Trade-offs\" section\n\n**Track technical debt**\n→ Search all component docs for \"Technical Debt Incurred\"\n\n---\n\n## Writing Guidelines\n\n### Trade-offs and Alternatives Are Required\n\nEvery component document MUST document both trade-offs AND alternatives considered. These go hand-in-hand:\n- **Trade-offs** explain what you gain and lose with your chosen approach\n- **Alternatives** explain what other options you considered and why you rejected them\n\nWithout alternatives, trade-offs lack context. Why did you accept this trade-off? What were you comparing against?\n\n### Be Specific\n\n❌ Bad: \"This makes things faster\"\n✅ Good: \"This reduces API latency from 200ms to 50ms\"\n\n### Quantify Impact\n\n❌ Bad: \"This improves performance\"\n✅ Good: \"This reduces memory usage by 40%\"\n\n### Document Trade-offs Honestly\n\n❌ Bad: \"This is better in every way\"\n✅ Good: \"This simplifies code but increases latency by 10ms\"\n\n### Include Diagrams\n\nAll architecture and component documents should include Mermaid diagrams.\n\n---\n\n## Diagram Guidelines\n\n### Use Mermaid for Diagrams\n\nAll diagrams should use Mermaid syntax for:\n- Maintainability (text-based, version control friendly)\n- GitHub rendering (renders in markdown)\n- Consistency\n\n---\n\n## Quality Standards\n\n### Component Design Documents Must Have\n\n- [ ] Clear \"What\" section (component purpose)\n- [ ] \"Why\" section (problem context)\n- [ ] \"How\" section (implementation approach)\n- [ ] **\"Trade-offs\" section** (what we gain vs lose) - REQUIRED\n- [ ] **\"Alternatives Considered\" section** - REQUIRED (trade-offs only exist because you chose one approach over alternatives)\n- [ ] Dependencies clearly listed\n- [ ] Interfaces documented (APIs, events)\n- [ ] Configuration examples\n- [ ] At least one diagram\n\n**Note**: Trade-offs and Alternatives go hand-in-hand. If you document trade-offs, you MUST document what alternatives you considered and why you didn't choose them.\n\n### Guides Must Have\n\n- [ ] Clear target audience\n- [ ] Step-by-step instructions\n- [ ] Code/configuration examples\n- [ ] Troubleshooting section\n- [ ] Links to related documents\n\n---\n\n## Searching for Technical Debt\n\nUse these commands to find technical debt across documents:\n\n```bash\n# Find all technical debt items\ngrep -r \"Technical Debt\" hyperfleet/components/\n\n# Find all trade-offs\ngrep -r \"## Trade-offs\" hyperfleet/\n\n# Find all \"What We Lose\" sections\ngrep -r \"What We Lose\" hyperfleet/\n\n# Find deprecated documents\ngrep -r \"Status: Deprecated\" hyperfleet/\n```\n\n---\n\n## Examples\n\n### Good Component Document\n\nSee: `hyperfleet/components/sentinel.md`\n- Clear purpose and responsibilities\n- Detailed trade-offs section\n- Alternatives considered\n- Technical debt identified\n- Diagrams included\n\n### Good Guide\n\nSee: `hyperfleet/docs/status-guide.md`\n- Step-by-step instructions\n- Code examples\n- Clear troubleshooting\n\n---\n\n## FAQ\n\n**Q: Do I need to document every implementation detail?**\nA: No. Focus on architectural decisions and component design. Implementation details belong in code comments and inline documentation.\n\n**Q: What if I don't know the trade-offs yet?**\nA: Document what you know and mark unknowns:\n- \"⚠️ Unknown: Performance impact needs measurement\"\n- \"⚠️ To investigate: Scalability limits\"\n\nUpdate the document as you learn more.\n\n**Q: How detailed should component docs be?**\nA: Detailed enough that someone unfamiliar with the component can:\n- Understand its purpose\n- Understand the trade-offs\n- Start implementing or operating it\n\nAvoid implementation minutiae (that's for code comments).\n\n**Q: Can I update someone else's document?**\nA: Yes! These are living documents. Update freely as design evolves. Use git history to track changes.\n\n**Q: When should I create a new document vs update existing?**\nA: Update existing documents when:\n- Refining the existing design\n- Adding implementation details\n- Paying down technical debt\n- Fixing errors or clarifications\n\nCreate new documents when:\n- Adding a completely new component\n- Major redesign that deprecates old approach\n- New feature guide or operational procedure\n\n---\n\n## Related Resources\n\n- [C4 Model](https://c4model.com/) - Architecture diagram inspiration\n- [Mermaid Documentation](https://mermaid.js.org/) - Diagram syntax\n- [Technical Debt Metaphor](https://www.martinfowler.com/bliki/TechnicalDebt.html) - Understanding technical debt\n\n---\n\n## Contact\n\n**Questions or suggestions?**\n- Slack: //todo\n- Architecture Team: //todo\n- Pull requests welcome for documentation updates\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Farchitecture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenshift-hyperfleet%2Farchitecture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Farchitecture/lists"}