diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml new file mode 100644 index 0000000..40629a0 --- /dev/null +++ b/.github/workflows/sync-docs.yml @@ -0,0 +1,46 @@ +name: Sync Documentation Content + +on: + push: + branches: [ main ] + paths: + - 'docs/**' + pull_request: + branches: [ main ] + paths: + - 'docs/**' + workflow_dispatch: # Manual trigger + +jobs: + sync-docs-content: + runs-on: ubuntu-latest + + steps: + - name: Checkout docs repository + uses: actions/checkout@v4 + with: + path: docs-repo + + - name: Checkout edgemining.energy repository + uses: actions/checkout@v4 + with: + repository: edge-mining/edgemining.energy + token: ${{ secrets.EDGEMINING_ENERGY_TOKEN }} + path: edgemining-energy + + - name: Sync docs content to edgemining.energy + run: | + # Remove existing docs directory + rm -rf edgemining-energy/docs + + # Copy docs content + cp -r docs-repo/docs edgemining-energy/ + + - name: Commit and push to edgemining.energy + working-directory: edgemining-energy + run: | + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + git add docs/ + git commit -m "Auto-sync: Update docs content from edge-mining/docs [skip ci]" + git push origin main diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e1b6935 --- /dev/null +++ b/.gitignore @@ -0,0 +1,29 @@ +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Temporary files +*.tmp +*.temp + +# Backup files +*.bak +*.backup \ No newline at end of file diff --git a/README.md b/README.md index 76a8c27..e572d27 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,116 @@ -⚠️ **Disclaimer**: *This project is in a preliminary state and under active development. Features and functionality may change significantly.* +# Edge Mining Documentation Repository -➑️ **Development Note**: -- This is the **Docs repository**, specifically dedicated to documentation of the Edge Mining application. -- The [Core repository](https://github.com/edge-mining/core) contains the main engine of the Edge Mining system. -- The [Add-on repository](https://github.com/edge-mining/addon) provides the Home Assistant integration. +This repository contains **only the documentation content** (Markdown files) for the Edge Mining website. The live site at [edgemining.energy](https://edgemining.energy) is automatically built and deployed from the [edge-mining/edgemining.energy](https://github.com/edge-mining/edgemining.energy) repository. +## 🎯 For Documentation Editors -# ⚑ Bitcoin Mining for Energy Efficiency +This repository is specifically for **editing and maintaining the documentation content**. All documentation changes should be made here and will be automatically synced to the website repository. -Bitcoin mining represents a unique opportunity to improve efficiency in both the production and use of energy, whether on an industrial scale or for smaller setups. This project aims to make mining accessible and easy to implement, providing tools to integrate mining into energy systems and maximize the use of the energy produced. +> **πŸ“ For Editors**: This repository is for **content editing** - writing, updating, and maintaining documentation. If you're a **developer** making technical changes to the website, use the [edge-mining/edgemining.energy](https://github.com/edge-mining/edgemining.energy) repository instead. -## 🌞 The Challenge: Managing Excess Energy +## πŸ“ Repository Structure -In energy production plants, especially those relying on renewable sources like solar and wind, there's often a surplus of energy generated during peak hours (for example, when there is a lot of sun or wind) that doesn't align with peak demand times. Today, the main options for managing this excess energy include: +``` +docs/ +β”œβ”€β”€ intro.md # Introduction +β”œβ”€β”€ about-us.md # About Edge Mining +β”œβ”€β”€ product/ # Product documentation +β”‚ └── product-cycle.md +β”œβ”€β”€ modelling/ # Architecture & DDD +β”‚ β”œβ”€β”€ README.md +β”‚ β”œβ”€β”€ domain-driven-architecture-overview.md +β”‚ └── glossary.md +β”œβ”€β”€ contribution.md # How to contribute +└── faq.md # Frequently asked questions +``` -- **Selling the energy to the national grid**: This is possible only if the grid accepts the surplus, and often at unfavorable economic conditions. -- **Purchasing additional storage systems**: Such as batteries, which can be expensive and not always scalable, limiting this option for many small producers. -- **Using the energy for various purposes**: For instance, producing hydrogen through electrolysis, charging electric vehicles, or pumping water for hydroelectric storage. However, these solutions are often challenging and costly to implement, especially for small- and medium-sized plants. -- **Using energy for marginal purposes**: Such as resistive heating, which generally doesn’t add significant economic value. -- **Wasting the energy**: Which is a loss that reduces the overall efficiency of the plant. +## πŸ”„ Workflow for Documentation Changes -## πŸ”Œ The Solution: Bitcoin Mining +### **How to Contribute:** -Bitcoin mining is a computational process that verifies and validates transactions on the Bitcoin network. This process ensures network security, using electrical energy to power specialized devices called miners. In return for this activity, miners receive a reward in Bitcoin, making mining not only useful for the network but also economically beneficial for participants. +1. **Edit Documentation**: Modify Markdown files in the `docs/` directory +2. **Test Locally**: Use the VuePress site to preview changes +3. **Commit Changes**: Push to this repository +4. **Automatic Sync**: Changes are automatically synced to [edge-mining/edgemining.energy](https://github.com/edge-mining/edgemining.energy) +5. **Live Update**: Website is automatically updated at [edgemining.energy](https://edgemining.energy) -This process has a unique feature that makes it particularly suitable for integration with renewable energy production plants: it is extremely flexible, able to be activated to consume energy during times of surplus and stopped immediately when energy is needed for other purposes. +### **Repository Relationships:** -Moreover, mining produces heat as a byproduct. 100% of the electrical energy used by a miner is converted into heat, making it similar to an electric heater that, in addition to providing warmth, also generates a constant economic reward. +``` +Documentation Repository (edge-mining/docs) - FOR EDITORS + ↓ (Auto-sync) +Website Repository (edge-mining/edgemining.energy) - FOR DEVELOPERS + ↓ (Auto-deploy) +Live Site (edgemining.energy) +``` -These characteristics make mining an ideal solution for managing excess energy, particularly in small- and medium-sized plants. +## πŸ› οΈ Local Development -## 🏑 Edge Mining: A Practical Approach for Everyone +### **For Documentation Editing:** -Aside from electrical power, mining only requires a miner and a low-speed internet connection. It virtually needs nothing else, making it a very simple activity to implement anywhere. +```bash +# Clone this repository +git clone https://github.com/edge-mining/docs.git +cd docs -You could say that the hardware implementation of a mining system is not particularly complex from a technical standpoint. In trying to implement it ourselves, we realized that the only missing element for a fully functional system was a management and automation solution for the mining process, specifically software that connects the energy production plant to the miners, regulating power on/off and energy consumption. +# Edit Markdown files in docs/ +# Test with VuePress (see below) +# Commit and push changes +``` -Our project aims to develop a mining management system that: +### **For Preview with VuePress:** -- Connects the power generation plant with one or more ASIC devices for mining. -- Allows users, even non-experts, to automate the mining process based on specific energy requirements. -- Helps users manage and make the most of the heat generated by the ASICs for space heating, thereby maximizing the energy surplus of the plant. +```bash +# Navigate to the website repository +cd ../edgemining.energy -## πŸ’Ύβ€‹ Development +# Install dependencies +npm install -Following the general overview of the project, the following link provides a deeper technical insight into how the system is structured according to Domain-Driven Design (DDD) principles. It identifies the core domain of energy optimization, categorizes supporting and generic subdomains, defines the internal structure of each, and maps the interactions between them. This approach allows us to align the software architecture with real-world needs, ensuring clarity, modularity, and scalability. The document is continuously evolving and reflects an iterative design processβ€”nothing is final, and all aspects are considered open to revision as the system and its understanding mature over time. +# Start development server +npm run docs:dev -[πŸ‘‰Domain-Driven Architecture Overview](./modelling/domain-driven-architecture-overview.md) +# View at http://localhost:8080 +``` -The following link provides access to a shared vocabulary used throughout the Edge Mining project, following the principles of Ubiquitous Language from Domain-Driven Design (DDD). It is organized by subdomain and offers simplified definitions based on domain expertise. The goal is to ensure consistent communication between developers, domain experts, and stakeholders, and to serve as a reference point during design and implementation. +## πŸ“ Documentation Guidelines -[πŸ‘‰Glossary](./modelling/glossary.md) +### **File Organization:** +- **`docs/intro.md`**: Project introduction and overview +- **`docs/about-us.md`**: Mission, values, and team information +- **`docs/product/`**: Product-specific documentation +- **`docs/modelling/`**: Architecture and technical documentation +- **`docs/contribution.md`**: How to contribute to the project +- **`docs/faq.md`**: Frequently asked questions ---- +### **Markdown Standards:** +- Use relative links: `./about-us.md` instead of `/docs/about-us.html` +- Include proper frontmatter for VuePress +- Follow consistent formatting and structure +- Update table of contents when adding new pages + +## πŸ”— Important Links + +- **Website Repository**: [edge-mining/edgemining.energy](https://github.com/edge-mining/edgemining.energy) (for developers) +- **Live Website**: [edgemining.energy](https://edgemining.energy) +- **Community**: [Discord](https://discord.com/invite/VQa9UY5SsS) -## ✏️ Conclusion +## ⚠️ Important Notes -Edge Mining proposes an innovative solution to optimize the use of excess energy produced by small power plants, particularly renewable ones. Integrating Bitcoin mining is a flexible, economically advantageous, and easy-to-implement choice. With our mining management system, users can maximize the efficiency of their plant, utilize the heat produced, and contribute positively to the Bitcoin network. This approach turns a potential inefficiency into a concrete opportunity for profit and sustainable energy use. +- **Auto-sync**: Changes here are automatically synced to the website repository +- **No direct editing**: Don't edit the website repository directly for documentation changes +- **Immediate deployment**: Changes appear on the live site after sync +- **Editor-focused**: This repository is for content editors, not developers -## 🀝 Contributions and Feedback +## 🎯 Next Steps for Contributors -We welcome contributions and feedback to make this project even better. Feel free to open issues or submit pull requests. +1. **Fork this repository** (if you haven't already) +2. **Make your changes** to the documentation +3. **Test locally** using the VuePress development server +4. **Create a Pull Request** to this repository +5. **Wait for review and merge** +6. **Changes will automatically appear** on the live site + +--- -Let’s mine smarter, together. +**Note**: This repository is for documentation content only. The VuePress website and deployment infrastructure are in the [edge-mining/edgemining.energy](https://github.com/edge-mining/edgemining.energy) repository. \ No newline at end of file diff --git a/docs/about-us.md b/docs/about-us.md new file mode 100644 index 0000000..50069db --- /dev/null +++ b/docs/about-us.md @@ -0,0 +1,74 @@ +# About Us + +## Our Story + +Edge Mining was born from a simple observation: energy often goes unused during low-demand periods. Instead of selling this energy cheaply, investing in costly storage solutions, or simply wasting it, we saw an opportunity to convert surplus energy directly into Bitcoin, creating sustainable and intelligent value. + +## Our Mission + +We believe that energy should never go to waste. Our mission is to unlock new economic possibilities from otherwise wasted resources by leveraging the power of Bitcoin mining to create value from surplus energy. + +## Why We Exist + +Energy often goes unused during low-demand periods. Instead of selling cheaply, investing in costly storage, or wasting this energy, Edge Mining converts it directly into Bitcoin, creating value sustainably and intelligently. + +## Our Approach + +### Research-Driven Development + +We take a research-driven approach to everything we do. Our team continuously explores new technologies, methodologies, and approaches to ensure that Edge Mining remains at the forefront of energy optimization. + +### Open Source Philosophy + +We believe in the power of open source. By making our code transparent and accessible, we enable collaboration, innovation, and community-driven development. There are no licensing fees - Edge Mining is 100% open source. + +### Community Focus + +Our community is at the heart of everything we do. We believe that the best solutions come from collaboration and shared knowledge. Whether you're a developer, energy enthusiast, or simply curious about the project, there's a place for you in our community. + +## We're in Alpha + +Edge Mining is currently in an early, alpha stage of development. Our research-driven approach is rapidly evolving, and features, performance, and reliability are continuously improving. + +### What This Means + +- **Active Development**: We're constantly working on new features and improvements +- **Research Phase**: We're exploring different approaches and technologies +- **Community Input**: Your feedback and contributions are invaluable +- **Rapid Evolution**: The project is changing and improving quickly + +## Key Features + +### Smart Automation + +Intelligent automation based on energy availability to maximize efficiency. Our systems automatically adjust to energy availability, ensuring optimal performance. + +### Heat Recovery + +Advanced heat recovery systems for practical applications. We don't just mine Bitcoin - we also recover and utilize the heat generated during the mining process. + +### Versatile Sizing + +Designed for small to medium energy installations. Whether you have a small solar setup or a medium-sized wind farm, Edge Mining can work for you. + +### 100% Open Source + +Fully open-source with no licensing fees. You can inspect, modify, and contribute to the codebase. + +## Get Involved + +Join our growing community of developers and energy enthusiasts. Together, we're building the future of energy optimization. + +### Discord + +Connect with our community to discuss ideas, ask questions, and collaborate on new features. + +### GitHub + +Explore our codebase, contribute to development, or fork the project to create your own solution. + +## Contact + +- **GitHub**: [edge-mining](https://github.com/edge-mining) +- **Discord**: [Join our community](https://discord.com/invite/VQa9UY5SsS) +- **Website**: [edgemining.energy](https://edgemining.energy) \ No newline at end of file diff --git a/docs/contribution.md b/docs/contribution.md new file mode 100644 index 0000000..959863c --- /dev/null +++ b/docs/contribution.md @@ -0,0 +1,168 @@ +# Contribution + +## Get Involved + +Join our growing community of developers and energy enthusiasts. Together, we're building the future of energy optimization. + +## How to Contribute + +There are many ways to contribute to Edge Mining: + +### πŸ› Report Bugs + +If you find a bug, please: + +1. Search existing [issues](https://github.com/edge-mining/docs/issues) to see if it's already been reported +2. Create a new issue with: + - Clear description of the problem + - Steps to reproduce the bug + - System information (OS, version, etc.) + - Screenshots if applicable + +### πŸ’‘ Suggest New Features + +To suggest new features: + +1. Create an issue with the `enhancement` tag +2. Describe the feature and its value to users +3. Include mockups or examples if possible + +### πŸ“ Improve Documentation + +Documentation is crucial! You can contribute by: + +- Fixing grammatical errors +- Adding examples +- Improving clarity +- Translating to other languages + +### πŸ”§ Contribute Code + +#### Prerequisites + +- Node.js 18+ +- Git +- Knowledge of JavaScript/TypeScript +- Familiarity with Domain-Driven Design principles + +#### Development Environment Setup + +```bash +# Fork and clone the repository +git clone https://github.com/your-username/edge-mining.git +cd edge-mining + +# Install dependencies +npm install + +# Start development server +npm run docs:dev + +# Run tests +npm test +``` + +#### Contribution Process + +1. **Fork** the repository on GitHub +2. **Create a branch** for your feature/fix: + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Make changes** and commit: + ```bash + git add . + git commit -m "feat: add new feature" + ``` +4. **Push** to your fork: + ```bash + git push origin feature/your-feature-name + ``` +5. **Create a Pull Request** on GitHub + +#### Commit Conventions + +We use [Conventional Commits](https://www.conventionalcommits.org/): + +- `feat:` for new features +- `fix:` for bug fixes +- `docs:` for documentation changes +- `style:` for formatting changes +- `refactor:` for code refactoring +- `test:` for adding or modifying tests +- `chore:` for build/configuration changes + +### πŸ§ͺ Testing + +Help us test: + +- Try new features +- Verify bug fixes +- Test on different operating systems +- Report performance issues + +## Code Guidelines + +### Code Style + +- Follow the project's ESLint conventions +- Write readable, well-commented code +- Add tests for new features +- Maintain high test coverage + +### Architecture + +- Keep code modular +- Follow SOLID principles +- Avoid code duplication +- Document public APIs + +### Domain-Driven Design + +Since Edge Mining follows Domain-Driven Design principles: + +- **Entities**: Implement as classes with identity and lifecycle +- **Value Objects**: Immutable objects representing concepts +- **Aggregates**: Clusters of entities with consistency boundaries +- **Repositories**: Abstract data access for aggregates +- **Services**: Domain logic that doesn't belong to entities + +## Review Process + +1. **Automatic checks**: All PRs must pass automatic tests +2. **Code review**: At least one maintainer must approve +3. **Testing**: Changes must be tested +4. **Documentation**: Update documentation if necessary + +## Community + +### Communication Channels + +- **GitHub Issues**: For bugs and feature requests +- **GitHub Discussions**: For general discussions +- **Discord**: [Join our community](https://discord.gg/edgemining) +- **Main Website**: [edgemining.energy](https://edgemining.energy) + +### Events + +- **Hacktoberfest**: Participate every October +- **Community calls**: Monthly community calls +- **Development sprints**: Intensive development sessions + +## Acknowledgments + +All contributors are listed in the [CONTRIBUTORS.md](https://github.com/edge-mining/docs/blob/main/CONTRIBUTORS.md) file. + +## License + +By contributing to Edge Mining, you agree that your contributions will be released under the MIT license of the project. + +## Questions? + +If you have questions about contributing, don't hesitate to: + +- Open an issue on GitHub +- Ask on GitHub Discussions +- Contact the maintainers on Discord + +Thank you for your contribution! πŸš€ \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..e62a35e --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,157 @@ +# Frequently Asked Questions (FAQ) + +## General Questions + +### What is Edge Mining? + +Edge Mining is a research-driven, open-source project that transforms surplus energy into Bitcoin-powered digital value. Instead of wasting energy during low-demand periods, Edge Mining converts it directly into Bitcoin, creating sustainable and intelligent value. + +### Why does Edge Mining exist? + +Energy often goes unused during low-demand periods. Instead of selling cheaply, investing in costly storage, or wasting this energy, Edge Mining converts it directly into Bitcoin, creating value sustainably and intelligently. + +### What stage of development is Edge Mining in? + +Edge Mining is currently in an **alpha stage** of development. Our research-driven approach is rapidly evolving, and features, performance, and reliability are continuously improving. + +## Technical Questions + +### What are the key features of Edge Mining? + +- **Smart Automation**: Intelligent automation based on energy availability to maximize efficiency +- **Heat Recovery**: Advanced heat recovery systems for practical applications +- **Versatile Sizing**: Designed for small to medium energy installations +- **100% Open Source**: Fully open-source with no licensing fees + +### What energy sources does Edge Mining support? + +Edge Mining is designed to work with various energy sources, including: +- Solar power +- Wind energy +- Hydroelectric power +- Any other renewable or surplus energy source + +### How does the heat recovery system work? + +Our advanced heat recovery systems capture the heat generated during Bitcoin mining and convert it into useful energy for practical applications, improving overall efficiency. + +### Is Edge Mining really 100% open source? + +Yes! Edge Mining is fully open-source with no licensing fees. You can inspect, modify, and contribute to the codebase. + +## Getting Started + +### How can I get involved with Edge Mining? + +There are several ways to get involved: + +1. **Join our Discord community** to discuss ideas and ask questions +2. **Explore our GitHub repository** to understand the codebase +3. **Contribute to development** by submitting pull requests +4. **Help with documentation** and testing +5. **Share feedback** and suggestions + +### Do I need technical skills to contribute? + +While technical skills are helpful, there are many ways to contribute: +- **Documentation**: Help improve our documentation +- **Testing**: Test features and report bugs +- **Community**: Help answer questions and support other users +- **Feedback**: Share ideas and suggestions + +### How can I stay updated on Edge Mining development? + +- **GitHub**: Follow our [repository](https://github.com/edge-mining) for code updates +- **Discord**: Join our [community](https://discord.com/invite/VQa9UY5SsS) for real-time discussions +- **Website**: Check [edgemining.energy](https://edgemining.energy) for updates + +## Community and Support + +### Where can I get help? + +- **Discord**: [Join our community](https://discord.gg/edgemining) for real-time support +- **GitHub Issues**: Report bugs and request features +- **GitHub Discussions**: Ask questions and share ideas +- **Documentation**: Explore our comprehensive documentation + +### How can I report a bug? + +1. Search existing [issues](https://github.com/edge-mining/docs/issues) to see if it's already been reported +2. Create a new issue with: + - Clear description of the problem + - Steps to reproduce the bug + - System information (OS, version, etc.) + - Screenshots if applicable + +### How can I suggest a new feature? + +1. Create an issue with the `enhancement` tag +2. Describe the feature and its value to users +3. Include mockups or examples if possible + +## Development and Architecture + +### What is Domain-Driven Design (DDD)? + +Domain-Driven Design is an approach to software development that focuses on creating a shared understanding between technical and non-technical stakeholders. Edge Mining uses DDD principles to organize code around business domains. + +### What technologies does Edge Mining use? + +Edge Mining uses modern web technologies and follows best practices for: +- **Backend**: Node.js/TypeScript with clean architecture +- **Frontend**: Modern web frameworks +- **Database**: Efficient data storage solutions +- **Infrastructure**: Scalable deployment options + +### How is the project organized? + +The project follows a modular architecture with clear separation of concerns: +- **Mining Domain**: Core mining functionality +- **Network Domain**: Communication and connectivity +- **Wallet Domain**: Cryptocurrency management +- **User Domain**: User management and authentication + +## Future Plans + +### What's the roadmap for Edge Mining? + +**Short Term (Next 6 Months)**: +- Complete alpha stage development +- Stabilize core features +- Improve documentation +- Expand community engagement + +**Medium Term (6-12 Months)**: +- Release beta version +- Implement advanced automation features +- Enhance heat recovery systems +- Scale to larger installations + +**Long Term (1+ Years)**: +- Production-ready release +- Advanced AI-powered optimization +- Integration with multiple energy sources +- Global community adoption + +### Will Edge Mining support other cryptocurrencies? + +Currently, Edge Mining focuses on Bitcoin. Future support for other cryptocurrencies will be considered based on community needs and technical feasibility. + +## Contact and Links + +### Where can I find more information? + +- **Website**: [edgemining.energy](https://edgemining.energy) +- **GitHub**: [edge-mining/docs](https://github.com/edge-mining/docs) +- **Discord**: [Join our community](https://discord.gg/edgemining) + +### How can I contact the team? + +The best way to contact us is through: +- **Discord**: For real-time communication +- **GitHub Issues**: For bug reports and feature requests +- **GitHub Discussions**: For general questions and discussions + +--- + +*This FAQ is continuously updated. If you have a question that's not answered here, please ask in our [Discord community](https://discord.gg/edgemining) or create a [GitHub discussion](https://github.com/edge-mining/docs/discussions).* \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000..7872e2c --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,39 @@ +# Introduction + +Welcome to Edge Mining - a research-driven, open-source project that transforms surplus energy into Bitcoin-powered digital value. + +## What is Edge Mining? + +Edge Mining is an innovative solution that addresses the challenge of unused energy during low-demand periods. Instead of selling energy cheaply, investing in costly storage, or simply wasting it, Edge Mining converts surplus energy directly into Bitcoin, creating sustainable and intelligent value. + +## Our Mission + +We believe that energy should never go to waste. Our mission is to unlock new economic possibilities from otherwise wasted resources by leveraging the power of Bitcoin mining to create value from surplus energy. + +## Key Principles + +- **Sustainability**: Convert waste energy into valuable digital assets +- **Intelligence**: Smart automation based on energy availability +- **Efficiency**: Maximize the value of every kilowatt-hour +- **Open Source**: Transparent, community-driven development +- **Innovation**: Research-driven approach to energy optimization + +## Current Status + +Edge Mining is currently in an **alpha stage** of development. Our research-driven approach is rapidly evolving, and features, performance, and reliability are continuously improving. + +## Getting Started + +To get involved with Edge Mining: + +1. **Explore the Documentation**: Start with our [About Us](./about-us.md) page +2. **Understand the Product**: Learn about our [Product Cycle](./product/product-cycle.md) +3. **Study the Architecture**: Dive into our [Domain-Driven Architecture](./modelling/domain-driven-architecture-overview.md) +4. **Join the Community**: Connect with us on [Discord](https://discord.com/invite/VQa9UY5SsS) and [GitHub](https://github.com/bitsalv/edgemining.energy) + +## Next Steps + +- [About Us](./about-us.md) - Learn more about our mission and values +- [Product Cycle](./product/product-cycle.md) - Understand our development process +- [Contribution](./contribution.md) - Find out how to contribute +- [FAQ](./faq.md) - Get answers to common questions \ No newline at end of file diff --git a/docs/modelling/README.md b/docs/modelling/README.md new file mode 100644 index 0000000..25a24b7 --- /dev/null +++ b/docs/modelling/README.md @@ -0,0 +1,59 @@ +# Architecture Documentation + +This section contains the architectural documentation for the Edge Mining platform, focusing on Domain-Driven Design principles and system architecture. + +## Overview + +Edge Mining follows a **Domain-Driven Design (DDD)** approach to create a clean, maintainable, and scalable architecture. The system is organized into distinct domains and subdomains, each with clear boundaries and responsibilities. + +## Documentation Structure + +### [Domain-Driven Architecture Overview](./domain-driven-architecture-overview.md) + +A comprehensive overview of the Edge Mining architecture, including: + +- **Core Domains**: Mining, Network, Wallet, and User domains +- **Subdomains**: Specific areas within each domain +- **Bounded Contexts**: Clear boundaries between domains +- **Architectural Patterns**: Clean Architecture, CQRS, Event Sourcing +- **Technology Stack**: Backend, frontend, and infrastructure choices +- **Implementation Guidelines**: Code organization and testing strategies + +### [Glossary](./glossary.md) + +A comprehensive glossary of terms and concepts used throughout the Edge Mining documentation and codebase, including: + +- **Domain-Driven Design terms**: Aggregate, Entity, Value Object, etc. +- **Cryptocurrency terms**: Block, Hash, Mining Pool, etc. +- **Technical terms**: API, Repository, Service, etc. + +## Key Architectural Principles + +1. **Domain-Driven Design**: Organize code around business domains +2. **Clean Architecture**: Separate concerns into layers +3. **CQRS**: Separate read and write operations +4. **Event Sourcing**: Store all changes as events +5. **Microservices**: Decompose into small, focused services + +## Getting Started with Architecture + +1. **Read the Overview**: Start with the [Domain-Driven Architecture Overview](./domain-driven-architecture-overview.md) +2. **Understand the Glossary**: Familiarize yourself with the [Glossary](./glossary.md) +3. **Explore the Code**: Look at the actual implementation in the main repository +4. **Join Discussions**: Participate in architectural discussions on GitHub + +## Contributing to Architecture + +When contributing to the architecture: + +1. **Follow DDD Principles**: Organize code around business domains +2. **Maintain Boundaries**: Keep bounded contexts separate +3. **Document Changes**: Update this documentation when making architectural changes +4. **Get Review**: Have architectural changes reviewed by the team + +## Related Resources + +- [Main Project Repository](https://github.com/bitsalv/edgemining.energy) +- [Domain-Driven Design Resources](https://martinfowler.com/bliki/DomainDrivenDesign.html) +- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) +- [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) \ No newline at end of file diff --git a/docs/modelling/domain-driven-architecture-overview.md b/docs/modelling/domain-driven-architecture-overview.md new file mode 100644 index 0000000..1bdd2f3 --- /dev/null +++ b/docs/modelling/domain-driven-architecture-overview.md @@ -0,0 +1,245 @@ +# Domain-Driven Architecture Overview + +## Introduction + +Edge Mining follows a **Domain-Driven Design (DDD)** approach to create a clean, maintainable, and scalable architecture. This document provides an overview of the domain model and architectural decisions that guide the development of the Edge Mining platform. + +## Core Domains + +The Edge Mining system is organized into several core domains, each representing a distinct area of business functionality: + +### 1. Mining Domain + +The **Mining Domain** is the heart of the system, responsible for all mining-related operations. + +**Key Concepts:** +- **Mining Pool**: A collection of miners working together to solve cryptographic puzzles +- **Mining Task**: A specific computational task assigned to miners +- **Hash Rate**: The computational power contributed by a miner +- **Block Reward**: The cryptocurrency reward for successfully mining a block + +**Responsibilities:** +- Task distribution and management +- Hash rate calculation and monitoring +- Block validation and submission +- Reward distribution + +### 2. Network Domain + +The **Network Domain** handles all network-related operations and peer-to-peer communication. + +**Key Concepts:** +- **Node**: A participant in the Edge Mining network +- **Peer**: Another node in the network +- **Connection**: A network connection between nodes +- **Message**: A communication unit between nodes + +**Responsibilities:** +- Peer discovery and management +- Message routing and delivery +- Network topology maintenance +- Connection health monitoring + +### 3. Wallet Domain + +The **Wallet Domain** manages cryptocurrency wallets and transactions. + +**Key Concepts:** +- **Wallet**: A digital wallet for storing cryptocurrency +- **Address**: A unique identifier for a wallet +- **Transaction**: A transfer of cryptocurrency +- **Balance**: The current amount of cryptocurrency in a wallet + +**Responsibilities:** +- Wallet creation and management +- Transaction processing +- Balance tracking +- Security and encryption + +### 4. User Domain + +The **User Domain** handles user management and authentication. + +**Key Concepts:** +- **User**: An individual using the Edge Mining platform +- **Account**: A user's account information +- **Profile**: User profile and preferences +- **Session**: An active user session + +**Responsibilities:** +- User registration and authentication +- Profile management +- Session handling +- Access control + +## Subdomains + +Each core domain is further divided into subdomains that handle specific aspects of the domain: + +### Mining Subdomains + +- **Task Management**: Handles mining task creation, distribution, and completion +- **Performance Monitoring**: Tracks mining performance and statistics +- **Reward Processing**: Manages reward calculation and distribution + +### Network Subdomains + +- **Peer Discovery**: Finds and maintains connections with other nodes +- **Message Handling**: Processes and routes network messages +- **Topology Management**: Maintains network structure and routing + +### Wallet Subdomains + +- **Address Management**: Handles wallet address creation and validation +- **Transaction Processing**: Manages transaction creation and verification +- **Security**: Implements wallet security measures + +### User Subdomains + +- **Authentication**: Handles user login and session management +- **Profile Management**: Manages user profiles and preferences +- **Authorization**: Controls access to system resources + +## Bounded Contexts + +Each domain is implemented within its own **Bounded Context**, which defines clear boundaries and interfaces: + +### Context Mapping + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Mining β”‚ β”‚ Network β”‚ β”‚ Wallet β”‚ +β”‚ Context │◄──►│ Context │◄──►│ Context β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ User β”‚ β”‚ Analytics β”‚ β”‚ Notification β”‚ +β”‚ Context β”‚ β”‚ Context β”‚ β”‚ Context β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Context Relationships + +- **Shared Kernel**: Common utilities and shared models +- **Customer-Supplier**: Clear dependencies between contexts +- **Conformist**: Adherence to external standards and protocols +- **Anti-Corruption Layer**: Protection against external system changes + +## Architectural Patterns + +### Clean Architecture + +The system follows Clean Architecture principles with clear separation of concerns: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Presentation Layer β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Application Layer β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Domain Layer β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Infrastructure Layer β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### CQRS (Command Query Responsibility Segregation) + +The system separates read and write operations: + +- **Commands**: Operations that change system state +- **Queries**: Operations that retrieve data +- **Command Handlers**: Process commands and update state +- **Query Handlers**: Retrieve and format data for display + +### Event Sourcing + +Key domain events are stored and can be replayed to reconstruct system state: + +- **Domain Events**: Significant occurrences in the domain +- **Event Store**: Persistent storage of domain events +- **Event Handlers**: React to domain events +- **Projections**: Build read models from events + +## Technology Stack + +### Backend + +- **Language**: Node.js/TypeScript +- **Framework**: Express.js or Fastify +- **Database**: PostgreSQL with event sourcing +- **Message Queue**: Redis or RabbitMQ +- **Caching**: Redis + +### Frontend + +- **Framework**: React or Vue.js +- **State Management**: Redux or Vuex +- **UI Library**: Material-UI or Vuetify +- **Real-time**: WebSocket connections + +### Infrastructure + +- **Containerization**: Docker +- **Orchestration**: Kubernetes +- **Monitoring**: Prometheus + Grafana +- **Logging**: ELK Stack (Elasticsearch, Logstash, Kibana) + +## Implementation Guidelines + +### Domain Model Implementation + +1. **Entities**: Implement as classes with identity and lifecycle +2. **Value Objects**: Immutable objects representing concepts +3. **Aggregates**: Clusters of entities with consistency boundaries +4. **Repositories**: Abstract data access for aggregates +5. **Services**: Domain logic that doesn't belong to entities + +### Code Organization + +``` +src/ +β”œβ”€β”€ domains/ +β”‚ β”œβ”€β”€ mining/ +β”‚ β”‚ β”œβ”€β”€ entities/ +β”‚ β”‚ β”œβ”€β”€ value-objects/ +β”‚ β”‚ β”œβ”€β”€ aggregates/ +β”‚ β”‚ β”œβ”€β”€ repositories/ +β”‚ β”‚ └── services/ +β”‚ β”œβ”€β”€ network/ +β”‚ β”œβ”€β”€ wallet/ +β”‚ └── user/ +β”œβ”€β”€ shared/ +β”‚ β”œβ”€β”€ domain/ +β”‚ β”œβ”€β”€ infrastructure/ +β”‚ └── application/ +└── presentation/ + β”œβ”€β”€ api/ + └── web/ +``` + +### Testing Strategy + +- **Unit Tests**: Test individual domain objects and services +- **Integration Tests**: Test interactions between components +- **End-to-End Tests**: Test complete user workflows +- **Performance Tests**: Ensure system meets performance requirements + +## Benefits of This Architecture + +1. **Maintainability**: Clear separation of concerns makes the code easier to maintain +2. **Scalability**: Modular design allows for independent scaling of components +3. **Testability**: Domain logic is isolated and easily testable +4. **Flexibility**: Changes in one domain don't affect others +5. **Team Productivity**: Teams can work on different domains independently + +## Next Steps + +1. **Detailed Domain Models**: Create detailed models for each domain +2. **API Design**: Design RESTful APIs for each bounded context +3. **Database Schema**: Design database schemas for each context +4. **Implementation Plan**: Create a phased implementation plan +5. **Team Structure**: Organize teams around domain boundaries + +This architecture provides a solid foundation for building a robust, scalable, and maintainable Edge Mining platform that can evolve with changing requirements and growing user needs. \ No newline at end of file diff --git a/docs/modelling/glossary.md b/docs/modelling/glossary.md new file mode 100644 index 0000000..dda71aa --- /dev/null +++ b/docs/modelling/glossary.md @@ -0,0 +1,160 @@ +# Glossary + +This glossary defines key terms and concepts used throughout the Edge Mining documentation and codebase. + +## A + +### Aggregate +A cluster of domain objects that can be treated as a single unit for data changes. Aggregates have a root entity that maintains consistency boundaries. + +### Anti-Corruption Layer +A design pattern that isolates a system from external dependencies by translating between different data models and protocols. + +### API (Application Programming Interface) +A set of rules and protocols that allows different software applications to communicate with each other. + +## B + +### Block +A collection of transactions in a blockchain that has been cryptographically linked to the previous block. + +### Block Reward +The cryptocurrency reward given to miners for successfully mining a new block in the blockchain. + +### Bounded Context +A boundary within which a particular domain model is defined and applicable. It helps manage complexity by clearly defining what belongs to the domain and what doesn't. + +## C + +### Command +An object that represents an intention to change the state of the system. Commands are processed by command handlers. + +### CQRS (Command Query Responsibility Segregation) +A pattern that separates read and write operations for a data store, allowing them to be optimized independently. + +### Cryptocurrency +A digital or virtual currency that uses cryptography for security and operates on a decentralized network. + +## D + +### Domain +A sphere of knowledge, influence, or activity. In Domain-Driven Design, a domain represents a specific area of business functionality. + +### Domain Event +A significant occurrence that happened within the domain. Domain events are used to communicate changes between different parts of the system. + +### Domain Model +A conceptual model of the domain that incorporates both behavior and data. It represents the core business logic and rules. + +### Domain Service +A service that implements domain logic that doesn't naturally belong to any entity or value object. + +## E + +### Edge Device +A computing device that performs data processing at the edge of a network, closer to the data source, rather than in a centralized location. + +### Entity +An object that has a unique identity and a lifecycle that can change over time. Entities are defined by their identity rather than their attributes. + +### Event Sourcing +A pattern where all changes to application state are stored as a sequence of events. The current state can be reconstructed by replaying these events. + +## F + +### Fork +A situation where a blockchain splits into two separate chains, usually due to a disagreement in the network about which version of the blockchain to follow. + +## H + +### Hash +A mathematical function that converts input data of any size into a fixed-size string of characters. In cryptocurrency mining, hashes are used to secure the blockchain. + +### Hash Rate +The speed at which a computer or network can perform hash operations. It's a measure of mining power and is typically expressed in hashes per second (H/s). + +## M + +### Mining +The process of validating and adding new transactions to a blockchain by solving complex mathematical puzzles. + +### Mining Pool +A group of miners who combine their computational resources to increase their chances of successfully mining blocks and earning rewards. + +### Mining Task +A specific computational task assigned to miners, typically involving finding a hash that meets certain criteria. + +## N + +### Node +A computer or device that participates in a blockchain network by maintaining a copy of the blockchain and validating transactions. + +### Nonce +A number used once in cryptographic communications. In mining, it's a value that miners change to try to find a valid hash. + +## P + +### Peer +Another node in the network with which a node can communicate directly. + +### Proof of Work (PoW) +A consensus mechanism that requires participants to perform computational work to validate transactions and create new blocks. + +## Q + +### Query +An object that represents a request for data from the system. Queries are processed by query handlers and do not change system state. + +## R + +### Repository +An abstraction that encapsulates the logic required to access data sources. Repositories provide a collection-like interface for accessing domain objects. + +### Reward +The cryptocurrency payment given to miners for successfully mining a block or contributing to the network. + +## S + +### Service +A stateless object that implements domain logic that doesn't belong to any entity or value object. + +### Shared Kernel +A design pattern where multiple bounded contexts share a common subset of the domain model, including code, database schema, and language. + +### Smart Contract +A self-executing contract with the terms of the agreement directly written into code. Smart contracts run on blockchain platforms. + +## T + +### Transaction +A record of a cryptocurrency transfer from one address to another. Transactions are grouped together in blocks. + +### Transaction Fee +A small amount of cryptocurrency paid to miners for processing and validating a transaction. + +## U + +### User Story +A description of a feature from the perspective of the end user. User stories help guide development by focusing on user value. + +## V + +### Value Object +An object that represents a descriptive aspect of the domain with no conceptual identity. Value objects are defined by their attributes rather than their identity. + +## W + +### Wallet +A digital tool that allows users to store, send, and receive cryptocurrency. Wallets contain private keys that are used to sign transactions. + +### WebSocket +A communication protocol that provides full-duplex communication channels over a single TCP connection, enabling real-time data exchange. + +## Z + +### Zero-Knowledge Proof +A cryptographic method that allows one party to prove to another that a statement is true without revealing any information beyond the validity of the statement itself. + +--- + +This glossary is a living document that will be updated as the Edge Mining platform evolves. If you encounter terms that are not defined here, please contribute to the documentation by adding them. \ No newline at end of file diff --git a/docs/product/product-cycle.md b/docs/product/product-cycle.md new file mode 100644 index 0000000..c060d2d --- /dev/null +++ b/docs/product/product-cycle.md @@ -0,0 +1,139 @@ +# Product Cycle + +## Overview + +Edge Mining follows a research-driven product development cycle that emphasizes continuous improvement, community feedback, and sustainable innovation. + +## Development Phases + +### Alpha Stage (Current) + +We are currently in the alpha stage of development. This means: + +- **Research Phase**: Exploring different approaches and technologies +- **Prototype Development**: Building and testing initial concepts +- **Community Feedback**: Gathering input from early adopters +- **Rapid Iteration**: Quickly implementing improvements based on feedback + +### Key Characteristics of Alpha + +- **Experimental Features**: New features are being tested and refined +- **Performance Optimization**: Continuous work on efficiency and reliability +- **Architecture Evolution**: The system architecture is being refined +- **Documentation Development**: Comprehensive documentation is being created + +## Development Process + +### 1. Research and Planning + +- Identify energy optimization opportunities +- Research new technologies and approaches +- Plan feature development and architecture improvements +- Gather community feedback and requirements + +### 2. Design and Architecture + +- Design new features using Domain-Driven Design principles +- Create architectural diagrams and documentation +- Plan integration with existing systems +- Consider scalability and maintainability + +### 3. Development and Testing + +- Implement new features following open-source best practices +- Conduct thorough testing and validation +- Optimize performance and efficiency +- Ensure code quality and documentation + +### 4. Community Review + +- Share developments with the community +- Gather feedback and suggestions +- Incorporate improvements based on community input +- Maintain transparency throughout the process + +### 5. Release and Iteration + +- Release new versions with improvements +- Monitor performance and gather usage data +- Plan next iteration based on feedback +- Continue the cycle of improvement + +## Key Focus Areas + +### Smart Automation + +- **Energy Availability Detection**: Automatically detect when surplus energy is available +- **Intelligent Scheduling**: Optimize mining operations based on energy patterns +- **Performance Monitoring**: Track and optimize system performance +- **Adaptive Algorithms**: Continuously improve automation logic + +### Heat Recovery Systems + +- **Thermal Management**: Efficient heat capture and utilization +- **Practical Applications**: Convert heat into useful energy +- **System Integration**: Seamless integration with existing infrastructure +- **Efficiency Optimization**: Maximize heat recovery efficiency + +### Versatile Sizing + +- **Scalable Architecture**: Support for various installation sizes +- **Modular Design**: Easy to adapt to different energy sources +- **Flexible Configuration**: Customizable for specific needs +- **Resource Optimization**: Efficient use of available resources + +### Open Source Development + +- **Transparent Codebase**: All code is open and accessible +- **Community Contributions**: Welcome contributions from the community +- **Documentation**: Comprehensive documentation for all features +- **Licensing**: No licensing fees or restrictions + +## Future Roadmap + +### Short Term (Next 6 Months) + +- Complete alpha stage development +- Stabilize core features +- Improve documentation +- Expand community engagement + +### Medium Term (6-12 Months) + +- Release beta version +- Implement advanced automation features +- Enhance heat recovery systems +- Scale to larger installations + +### Long Term (1+ Years) + +- Production-ready release +- Advanced AI-powered optimization +- Integration with multiple energy sources +- Global community adoption + +## Community Involvement + +The product cycle is heavily influenced by community feedback and contributions: + +- **Feature Requests**: Community suggestions drive new features +- **Bug Reports**: Community helps identify and fix issues +- **Code Contributions**: Community members contribute to development +- **Testing and Validation**: Community provides real-world testing +- **Documentation**: Community helps improve documentation + +## Get Involved + +To participate in the product development cycle: + +1. **Join the Community**: Connect with us on [Discord](https://discord.gg/edgemining) +2. **Explore the Code**: Check out our [GitHub repository](https://github.com/edge-mining/docs) +3. **Provide Feedback**: Share your ideas and suggestions +4. **Contribute Code**: Submit pull requests and improvements +5. **Test Features**: Help test new features and provide feedback + +## Contact + +- **GitHub**: [edge-mining/docs](https://github.com/edge-mining/docs) +- **Discord**: [Join our community](https://discord.gg/edgemining) +- **Website**: [edgemining.energy](https://edgemining.energy) \ No newline at end of file diff --git a/images/domain-and-subdomains.png b/images/domain-and-subdomains.png deleted file mode 100644 index 13801db..0000000 Binary files a/images/domain-and-subdomains.png and /dev/null differ diff --git a/images/logo 3.png b/images/logo 3.png deleted file mode 100644 index 0bce0c0..0000000 Binary files a/images/logo 3.png and /dev/null differ diff --git a/modelling/domain-driven-architecture-overview.md b/modelling/domain-driven-architecture-overview.md deleted file mode 100644 index 4de3064..0000000 --- a/modelling/domain-driven-architecture-overview.md +++ /dev/null @@ -1,107 +0,0 @@ - -# Domain-Driven Architecture Overview - -The central problem the application solves is the *optimization of energy usage* using excess energy production (especially from renewables) by integrating Bitcoin mining. This isn't just about mining; it's about using mining as *a tool* for energy management. The core domain revolves around the intelligent automation and control of mining based on energy availability and goals. - -# Domains Brake Down - -This outlines a strategic categorization of subdomains according to their importance within the system. Furthermore, it details the internal composition of each subdomain, breaking it down into entities, value objects, and aggregates to clarify responsibilities and structure. - -- πŸŸ’β€‹ **Core:** The *automation/decision logic* is central. This is where the unique value proposition lies. -- 🟣 **Supporting:** These domains are necessary for the core domain to function but aren't the primary differentiator. -- ⚫ **Generic:** These are common problems solved elsewhere, not specific to this domain. - -The identified domains are: -- 🟒 [Energy Optimization & Mining Automation](#energy-optimization--mining-automation) -- 🟣 [Energy System Monitoring](#energy-system-monitoring) -- 🟣 [Mining Device Management](#mining-device-management) -- 🟣 [Home Consumption Analytics](#home-consumption-analytics) -- 🟣 [Energy Forecast](#energy-forecast) -- 🟣 [Heat Utilization](#heat-utilization) -- 🟣 [Mining Performance Analysis](#mining-performance-analysis) -- ⚫ [User Settings](#user-settings) -- ⚫ [Notification System](#notification-system) - -## Energy Optimization & Mining Automation -This is the **Core** domain that captures the intelligence, making smart decisions about *when* to mine based on energy conditions. - -**Components**: - - `OptimizationPolicy`Β (Entity? Aggregate Root?): A collection of rules and goals driving the automation decisions. It makes decisions based on input (e.g. "*stabilizes hashrate*", "*battery health*" or "*heats the room*"). - - `AutomationRule`Β (Entity? Maybe Value Object within a Policy?): Represents a user-defined or system rule (e.g., "*turn on if battery > 80% AND forecast > X*"). TheΒ *logic*Β itself. - - `MiningDecision`Β (Value Object): The output of the policy (e.g., `StartMining`, `StopMining`, `MaintainState`, `ChangeState`). - -## Energy System Monitoring -This is a **Supporting** domain, focuses on data acquisition from the energy plant (production, storage, consumption) and to provide them to the core domain. It doesn'tΒ *decide*Β anything, just reports. - -**Components**: - - `EnergyPlant`Β (Entity or Aggregate Root): Represents the overall energy production system. - - `EnergySource`Β (Entity): e.g., Solar Panel Array, Wind Turbine. Has properties likeΒ `CurrentProduction`Β (VO). - - `EnergyStorage`Β (Entity): e.g., Battery. Has properties likeΒ `StateOfCharge` (VO),Β `NominalCapacity`Β (VO), `ActualCapacity` (VO). - - `EnergyLoad`Β (Entity): Represents the user's main energy load. Contains `CurrentConsumption` (VO) - - `EnergyReading`Β (Value Object): A specific measurement (e.g., 5 kW production at timestamp T). - - `EnergyStateSnapshot`Β (Value Object): Represents the state of the energy system at a point in time (*production*, *consumption*, *battery level*, *forecast*). Used as input for decisions. - -## Mining Device Management -This is a **Supporting** domain, focuses on controlling and possibly monitoring the state of the ASIC miners. Needs to execute the commands from the core domain (turn on/off) and maybe report miner status. It doesn'tΒ *decide*Β when to turn on/off. - -**Components**: - - `Miner`Β (ASIC) (Entity): Represents a physical mining device. Has a `MinerId` (VO),Β `Status`Β (VO: *On, Off, Error*), maybeΒ `PowerConsumption`Β (VO). - - `MiningFarm`Β (Entity? Aggregate Root? Optional): If managing multiple miners as a group. - - `ControlCommand`Β (Value Object): e.g., `TurnOn`, `TurnOff`, `SetHashboard`. - -## Energy Forecast -This is a ***Supporting** domain, focuses on data collection from forecast external services and to provide them to the core domain. - -**Components**: - - `ForecastData` (Value Object): Represents the relevant solar/energy forecast. - -## Home Consumption Analytics -This is a **Supporting** domain, focuses on home energy loads forcasts. Needs to provide data (estimate consumptions, times) of the home energy loads (Washing machine, Dishwasher, Boiler, EV Charger) to the core domain. It can be a **core subdomain** (thanks to [this post](https://vladikk.com/2018/01/26/revisiting-the-basics-of-ddd/)), but let's keep it as supporting for now. - -**Components**: - - `HomeLoadsProfile` (Aggregate Root): Represents the typical energy load profile of a household. - - `LoadDevice` (Entity): Represents a specific energy load inside the home. Includes `ConsumptionForecast`. - -## Heat Utilization -This is a **Supporting** domain, could become more core if heatΒ *demand*Β starts driving mining decisions, but based on the actual needs, it's primarily aboutΒ *using*Β the byproduct. - -**Components**: - - (Potentially) `HeatOutput`Β (Value Object?): Associated with aΒ Miner's operation. - - (Potentially) `HeatingZone`Β (Entity?): If actively managing heat distribution. - - (Potentially) `TemperatureSensor`Β (Entity?): To monitor effectiveness. - -## Mining Performance Analysis -This is a **Supporting** domain, focuses on reporting earnings, hash rates, etc. Important for the user, but the coreΒ *automation*Β doesn't strictly depend on real-time profitability calculations (though it could influence userΒ *goals*). - -**Components**: - - `MiningSession`Β (Entity?): Represents a period when a miner was active. - - `MiningReward`Β (Value Object): Satoshi earned. - - `HashRate`Β (Value Object): Mining speed. - - `PoolConnectionDetails`Β (Value Object/Entity?): Details about the mining pool being used. - -## User Settings -This is a **Generic** domain. Handles user settings, goals, and UI presentation. Let's treat it as Supporting as it presents data from other domains and takes user input that influences the Core domain. - -**Components**: - - `User`Β (Entity): The system user. - - `SystemSettings`Β (Entity/VO): Global or specific settings. - - `NotificationPreference`Β (VO): Notification settings. - -## Notification System -This is a **Generic** domain. Informing users about events. - -# Context Mapping: Subdomain Interactions - -Shows how different subdomains interact by exchanging information and triggering actions. This helps define the flow of responsibilities in the system. - -| From (Subdomain) | ➑️ | To (Subdomain) | Data/Action Provided | -| ----------------------------------- | --- | --------------------------------------- | ------------------------------------------------- | -| Energy System Monitoring | ➑️ | Energy Optimization & Mining Automation | `EnergyStateSnapshot` | -| External Integrations (Forecast) | ➑️ | Energy Optimization & Mining Automation | `ForecastData` | -| User Configuration & Interaction | ➑️ | Energy Optimization & Mining Automation | User parameters for `OptimizationPolicy` | -| Energy Optimization & Mining Auto. | ➑️ | Mining Device Management | `ControlCommand` (e.g., TurnOn Miner X) | -| Mining Device Management | ➑️ | Energy Optimization & Mining Automation | Miner status reports | -| Mining Device Management | ➑️ | Mining Performance Analysis | Uptime, possibly hashrate | -| External Integrations (Mining Pool) | ➑️ | Mining Performance Analysis | `MiningReward` data | -| Home Consumption Analytics | ➑️ | Energy Optimization & Mining Automation | Aggregate `ConsumptionForecast` | -| Monitoring Subdomains | ➑️ | User Configuration & Interaction | Data for display (status, performance, heat, ...) | diff --git a/modelling/glossary.md b/modelling/glossary.md deleted file mode 100644 index 49aef1b..0000000 --- a/modelling/glossary.md +++ /dev/null @@ -1,90 +0,0 @@ -# Glossary - -Following the **Ubiquitous Language** approach of Domain-Driven Design (DDD), this glossary is organized by subdomains and contains simplified definitions gathered from domain experts. Its purpose is to establish a clear and consistent vocabulary, essential for effective communication and development of the application. - -Subdomains: -- 🟒 [Energy Optimization & Mining Automation](#energy-optimization--mining-automation) -- 🟣 [Energy System Monitoring](#energy-system-monitoring) -- 🟣 [Mining Device Management](#mining-device-management) -- 🟣 [Home Consumption Analytics](#home-consumption-analytics) -- 🟣 [Energy Forecast](#energy-forecast) -- 🟣 [Heat Utilization](#heat-utilization) -- 🟣 [Mining Performance Analysis](#mining-performance-analysis) -- ⚫ [User Settings](#user-settings) -- ⚫ [Notification System](#notification-system) - -## Energy Optimization & Mining Automation -**Automation Rule**: Rules that automate the process of turning on, controlling, or turning off a miner. For example, turn off the miner if the battery has dropped below 80%. - -**Optimization Policy**: Collection of automation rules that define energy optimization policies aimed at achieving a goal. For example: -- *Preserve Battery*: a collection of rules designed to provide power to the miner only if the battery is full without ever discharging it. -- *Stop Export*: a collection of rules aimed at reduce or totally stopping the energy exported to the Grid Operator. - -## Energy System Monitoring -**Inverter**: A machine that produces energy using solar panels. It may have one or multiple MPPTs and can be either on-grid or off-grid. - -**Solar panel**: A hardware component that produces energy from sunlight. - -**Battery**: A hardware component that stores energy. - -**Battery SoC**: *State of Charge* of the battery; it represents the total amount of energy stored in the battery. - -**Battery Discharge**: The process by which energy exits the battery. - -**Battery Charge**: The process by which energy enters the battery. - -**Unused Energy**: -- In On-Grid systems, this is the energy not used by the loads and fed into the national electric grid. -- In Off-Grid systems, this is the energy not produced by the system because it is not required by the loads/batteries. - -**Loads**: Devices that consume energy. - -## Mining Device Management -**Miner**: A machine that uses electrical energy to solve mathematical calculations and produce heat. - -**Hashboard**: The part of the miner that contains the chips responsible for calculating hashes. - -**Control board**: The main controller in a miner that manages communication, power distribution, and operational logic. - -**Fan**: A cooling component that regulates the miner's internal temperature by moving air across heated parts. - -**Smart plug**: A remotely controllable power outlet that can be used to power on/off a miner automatically or based on conditions. - -**Hashrate**: A measurement of the computing power of a miner. - -**Energy consumption**: The electrical energy used by the miner. - -**Core temperature**: The temperature of the main chips. - -**Efficiency**: The power consumption in relation to the produced hashrate. Can be measured in W/TH or J/TH. - -**Mining pool**: A group of miners who combine their computational resources to increase the probability of mining a block and share the reward proportionally. - -**Stock Firmware**: The original firmware pre-installed by the miner's manufacturer. It governs low-level operations such as startup sequences, thermal management, fan control, hashrate adjustment, and network communication. Typically more stable but less customizable than third-party firmware. - -**Third-Party Firmware**: Custom firmware developed by independent developers or communities that replaces the stock firmware on a miner. It often provides enhanced functionality, greater configurability, performance tuning options, and additional features such as API access, advanced monitoring, or custom fan curves. It may, however, require more technical knowledge and can void warranties. - -## Home Consumption Analytics - -*to complete...* - -## Energy Forecast - -*to complete...* - -## Heat Utilization - -*to be complete...* - -## Mining Performance Analysis - -*to be complete...* - -## User Settings - -*to be complete...* - -## Notification System - -*to be complete...* -