Status: Active
Owner: Architecture Team
Last Updated: 2025-10-22
This 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.
Key Principle: All significant architectural decisions must be documented here with their trade-offs to track technical debt and enable informed future decisions.
Current Phase: MVP Development
Access & Permissions:
- All developers in the HyperFleet team are granted write access to this repository
- To support quick iteration during MVP, developers have approve and merge access if there are no objections from peers
- This temporary process enables rapid documentation of decisions and scope changes
Repository Usage:
- This repository primarily records:
- Architectural decisions and their rationale
- Trade-offs we're accepting during MVP
- Changes to MVP scope and priorities
- Technical debt we're consciously incurring
Post-MVP:
- Once MVP is complete, we will establish official processes for:
- Repository access management
- PR review requirements
- Approval workflows
- Documentation governance
During MVP, prioritize speed over process while maintaining clear documentation of decisions.
architecture/
├── README.md # This file - repository guide
├── hyperfleet/ # HyperFleet-specific architecture
│ ├── architecture/ # 30,000 feet view (system-level)
│ │ ├── architecture-summary.md
│ │ ├── component-diagram.md
│ │ ├── data-flow-diagram.md
│ │ └── deployment-architecture.md
│ ├── components/ # Component-level design decisions
│ │ ├── api.md
│ │ ├── sentinel.md
│ │ ├── message-broker.md
│ │ ├── adapters.md
│ │ └── database.md
│ └── docs/ # Implementation guides and features
│ ├── status-guide.md
│ ├── adapter-development-guide.md
│ ├── deployment-guide.md
│ └── monitoring-guide.md
Purpose: High-level system architecture (30,000 feet view)
Contents:
- System overview and goals
- Component relationships and interactions
- Data flows and communication patterns
- Deployment topology
- Cross-cutting concerns (security, scalability, observability)
When to create: Major system redesigns, new architecture proposals
Living Document: Update as system architecture evolves
Purpose: Detailed design for individual components
Required Sections:
- What: Component purpose and responsibilities
- Why: Problem it solves and context
- How: Technical implementation approach
- Trade-offs: What we gain vs what we lose (REQUIRED)
- Dependencies: What this component relies on
- Interfaces: APIs, events, data contracts
- Configuration: How to configure the component
- Alternatives Considered: What we didn't choose and why
When to create: New component introduction, major component redesign
Living Document: Update as component design evolves during implementation
Purpose: Practical guides for developers and operators
Contents:
- Step-by-step instructions
- Code examples and patterns
- Configuration examples
- Troubleshooting tips
- Best practices
When to create: New feature implementation, operational procedures
Living Document: Keep examples current as APIs and configurations change
Critical Requirement: Every component design document MUST include both:
- "Trade-offs" section - What we gain and lose with the chosen approach
- "Alternatives Considered" section - What other options existed and why we didn't choose them
These sections work together to provide full context for architectural decisions.
## Trade-offs
### What We Gain
- ✅ Benefit 1 with measurable impact
- ✅ Benefit 2 with context
- ✅ Benefit 3
### What We Lose / What Gets Harder
- ❌ Cost 1 - Technical debt we're accepting
- ❌ Cost 2 - Capability we're giving up
- ⚠️ Risk 1 - What could go wrong
### Technical Debt Incurred
- **Debt Item 1**: Description of shortcut taken, impact, remediation plan
- **Debt Item 2**: What we should fix in the future
### Acceptable Because
- Reason 1 why the trade-off makes sense
- Reason 2 (e.g., time constraints, simplicity, MVP scope)## Trade-offs
### What We Gain
- ✅ Simpler architecture (5 components vs 6)
- ✅ Lower latency (no outbox polling)
- ✅ Easier to understand and maintain
### What We Lose / What Gets Harder
- ❌ Eventual consistency (not guaranteed delivery like outbox pattern)
- ❌ No transactional event creation with database writes
- ⚠️ Risk of events lost if broker is down and Sentinel crashes
### Technical Debt Incurred
- **No event delivery guarantees**: If Sentinel publishes to broker and crashes before updating internal state, we may duplicate events
- **Impact**: Low (adapters are idempotent)
- **Remediation**: Post-MVP, add event deduplication in adapters or message broker
### Acceptable Because
- MVP scope prioritizes simplicity over perfect consistency
- Cluster provisioning use case tolerates eventual consistency
- Adapters are designed to be idempotentAll documents in this repository are living documents:
- Update freely as design evolves
- Mark status to indicate maturity (Draft, Active, Deprecated)
- Track changes via git commit history
- Pay down debt by updating "Technical Debt Incurred" sections
- Draft: Initial design, still being refined
- Active: Current implementation
- Deprecated: No longer used (link to replacement)
When to update "Last Updated" date:
Update the date for meaningful changes only:
- ✅ Component design changes
- ✅ New sections added
- ✅ Trade-offs modified
- ✅ Status changes (Draft → Active, Active → Deprecated)
- ✅ Technical debt paid down or added
- ❌ NOT for typos, formatting, or minor clarifications
Note: Git commit history tracks all changes. The "Last Updated" date is a quick visual indicator of the last significant revision.
Steps for meaningful updates:
- Update the relevant sections
- Update "Last Updated" date at the top of the document
- If paying down technical debt,
strikethroughthe debt item and link to PR
Example of paying down technical debt:
### Technical Debt Incurred
- ~~**No retry logic**: Adapters don't retry failed operations~~
- **Status**: Resolved in #123
- **Resolution**: Added exponential backoff retry logicMVP Process (Current):
All HyperFleet team developers have approve and merge access. Goal: Move fast while keeping the team informed.
How to submit and merge changes:
- Create a PR with your documentation updates
- Add a clear description of what changed and why
- Post the PR link in Slack: #hcm-hyperfleet-team for team visibility
- Wait 24 hours for peer review and objections (accounts for time zone differences between regions)
- For urgent changes, use judgment but ensure the change is well-documented with clear rationale
- For major architectural changes, strongly consider waiting for at least one or two Technical Leader reviews
- Merge when ready: Once you have approval from peers and no objections after the 24-hour window, you may merge
Post-MVP Process (to be established):
- Formal approval requirements based on change type
- Required reviewers for different document categories
- Defined merge timelines and escalation paths
Understand HyperFleet architecture
→ Start with hyperfleet/architecture/architecture-summary.md
Design a new component
→ Add document to hyperfleet/components/ with required sections (see "Component Design Documents")
Write an implementation guide
→ Add guide to hyperfleet/docs/ with step-by-step instructions
Find trade-offs for a component
→ Read component document in hyperfleet/components/, look for "Trade-offs" section
Track technical debt → Search all component docs for "Technical Debt Incurred"
Every component document MUST document both trade-offs AND alternatives considered. These go hand-in-hand:
- Trade-offs explain what you gain and lose with your chosen approach
- Alternatives explain what other options you considered and why you rejected them
Without alternatives, trade-offs lack context. Why did you accept this trade-off? What were you comparing against?
❌ Bad: "This makes things faster" ✅ Good: "This reduces API latency from 200ms to 50ms"
❌ Bad: "This improves performance" ✅ Good: "This reduces memory usage by 40%"
❌ Bad: "This is better in every way" ✅ Good: "This simplifies code but increases latency by 10ms"
All architecture and component documents should include Mermaid diagrams.
All diagrams should use Mermaid syntax for:
- Maintainability (text-based, version control friendly)
- GitHub rendering (renders in markdown)
- Consistency
- Clear "What" section (component purpose)
- "Why" section (problem context)
- "How" section (implementation approach)
- "Trade-offs" section (what we gain vs lose) - REQUIRED
- "Alternatives Considered" section - REQUIRED (trade-offs only exist because you chose one approach over alternatives)
- Dependencies clearly listed
- Interfaces documented (APIs, events)
- Configuration examples
- At least one diagram
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.
- Clear target audience
- Step-by-step instructions
- Code/configuration examples
- Troubleshooting section
- Links to related documents
Use these commands to find technical debt across documents:
# Find all technical debt items
grep -r "Technical Debt" hyperfleet/components/
# Find all trade-offs
grep -r "## Trade-offs" hyperfleet/
# Find all "What We Lose" sections
grep -r "What We Lose" hyperfleet/
# Find deprecated documents
grep -r "Status: Deprecated" hyperfleet/See: hyperfleet/components/sentinel.md
- Clear purpose and responsibilities
- Detailed trade-offs section
- Alternatives considered
- Technical debt identified
- Diagrams included
See: hyperfleet/docs/status-guide.md
- Step-by-step instructions
- Code examples
- Clear troubleshooting
Q: Do I need to document every implementation detail? A: No. Focus on architectural decisions and component design. Implementation details belong in code comments and inline documentation.
Q: What if I don't know the trade-offs yet? A: Document what you know and mark unknowns:
- "
⚠️ Unknown: Performance impact needs measurement" - "
⚠️ To investigate: Scalability limits"
Update the document as you learn more.
Q: How detailed should component docs be? A: Detailed enough that someone unfamiliar with the component can:
- Understand its purpose
- Understand the trade-offs
- Start implementing or operating it
Avoid implementation minutiae (that's for code comments).
Q: Can I update someone else's document? A: Yes! These are living documents. Update freely as design evolves. Use git history to track changes.
Q: When should I create a new document vs update existing? A: Update existing documents when:
- Refining the existing design
- Adding implementation details
- Paying down technical debt
- Fixing errors or clarifications
Create new documents when:
- Adding a completely new component
- Major redesign that deprecates old approach
- New feature guide or operational procedure
- C4 Model - Architecture diagram inspiration
- Mermaid Documentation - Diagram syntax
- Technical Debt Metaphor - Understanding technical debt
Questions or suggestions?
- Slack: //todo
- Architecture Team: //todo
- Pull requests welcome for documentation updates