{"id":16382618,"url":"https://github.com/kengu/no.kengu.smart_dash","last_synced_at":"2025-08-17T22:11:19.642Z","repository":{"id":219166866,"uuid":"748318615","full_name":"kengu/no.kengu.smart_dash","owner":"kengu","description":"Smart Home Dashboard App (for my personal use)","archived":false,"fork":false,"pushed_at":"2025-04-19T16:55:58.000Z","size":193171,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T13:19:38.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","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/kengu.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}},"created_at":"2024-01-25T18:19:30.000Z","updated_at":"2025-04-20T17:55:15.000Z","dependencies_parsed_at":"2024-03-10T19:45:04.798Z","dependency_job_id":"bf855670-2f3c-4751-a19b-fee263f4f058","html_url":"https://github.com/kengu/no.kengu.smart_dash","commit_stats":{"total_commits":211,"total_committers":2,"mean_commits":105.5,"dds":0.3981042654028436,"last_synced_commit":"c1f89f2e2ff35499e742e8e46bce081e306e35a8"},"previous_names":["kengu/no.kengu.smart_dash"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kengu/no.kengu.smart_dash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kengu%2Fno.kengu.smart_dash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kengu%2Fno.kengu.smart_dash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kengu%2Fno.kengu.smart_dash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kengu%2Fno.kengu.smart_dash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kengu","download_url":"https://codeload.github.com/kengu/no.kengu.smart_dash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kengu%2Fno.kengu.smart_dash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270912602,"owners_count":24666751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2024-10-11T04:05:53.782Z","updated_at":"2025-08-17T22:11:19.596Z","avatar_url":"https://github.com/kengu.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Dash Project \n\n[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=rounded-square)](https://github.com/invertase/melos) [![Publish](https://github.com/kengu/no.kengu.smart_dash/actions/workflows/publish.yml/badge.svg)](https://github.com/kengu/no.kengu.smart_dash/actions/workflows/publish.yml)\n\n_A Smart Dashboard project for my personal use._\n\nThis document provides a summary of the architecture to help developers \nquickly understand how the various modules are structured and interact. \nThe project is organized as a monorepo and it follows a modular architecture \nto ensure scalability and maintainability.\n\n# Developing\n\nThis project is organized as a mono-repo using [Melos](https://pub.dev/packages/melos).\n\nBootstrap monorepo management tool (only needed once)\n```bash\ndart pub global activate melos\n```\n\nPrepare development environment (macOS only for now)\n```bash\nmelos run prepare\n```\n\nRun each time you add or remove a feature or package\n```bash\nmelos bootstrap\n```\n\nUpgrade all dependencies at once\n```bash\nmelos run upgrade\n```\n\n# Modules\nThe project is divided into four type of modules, \nwhere each module type serves a specific purpose:\n\n* [Apps](#apps): Top-level frontend modules that build user interfaces by utilizing lower-level modules.\n* [Backends](#backends): Provides APIs that top-level modules use to implement business logic and data persistence.\n* [Features](#features): Implements vertical slices of business logic for both apps and backends. Integrations with third-party services are typically done in the backend, following [BFF](https://bff-patterns.com/) pattern.\n* [Packages](#packages): Low-level modules that provide reusable functionality to higher-level modules.\n\n## Apps\n* [SmartDash App](apps/smart_dash_app/README.md): Primary frontend focusing on user homes, devices, and automation.\n\n## Backends\n* [SmartDash Cloud](backends/smart_dash_cloud/README.md): Manages accounts, configurations and monitoring.\n* [SmartDash Daemon](backends/smart_dash_daemon/README.md): Runs local smart device and third party service integrations.\n* [SmartDash Gateway](backends/smart_dash_gateway/README.md): Acts as the reverse proxy for accessing daemons, especially when they are behind NAT or dynamic IP addresses.\n\n## Features\n* [SmartDash Account](features/smart_dash_account/README.md): Manages user accounts, authentication, and authorization.\n* [SmartDash Home](features/smart_dash_home/README.md): Manages integration for each home.\n* [SmartDash Geocoder](features/smart_dash_geocoder/README.md): Provides geolocation services and address resolution.\n* [SmartDash Analytics](features/smart_dash_analytics/README.md): Handles metrics and analysis of home and device data.\n* [SmartDash Flow](features/smart_dash_flow/README.md): Implements workflows and automations for smart homes.\n* [SmartDash MQTT](features/smart_dash_mqtt/README.md): MQTT-based services for real-time device communication.\n* [SmartDash Snow](features/smart_dash_snow/README.md): Provides snow depth and snow conditions integrations.\n* [SmartDash Energy](features/smart_dash_energy/README.md): Monitors and manages energy usage and related analytics.\n* [SmartDash Device](features/smart_dash_device/README.md): Manages device-level interactions and control.\n* [SmartDash Camera](features/smart_dash_camera/README.md): Handles camera devices and related media streams.\n* [SmartDash Weather](features/smart_dash_weather/README.md): Integrates weather information services.\n* [SmartDash Presence](features/smart_dash_presence/README.md): Manages presence detection and occupancy monitoring.\n* [SmartDash Notification](features/smart_dash_notification/README.md): Sends notifications to users based on system events or alerts.\n\n## Packages\n* [SmartDash Common](packages/smart_dash_common/README.md): Shared utilities and functionality.\n* [SmartDash Endpoint](packages/smart_dash_endpoint/README.md): Shared functionality for API clients and controllers.\n* [SmartDash Integration](packages/smart_dash_integration/README.md): Common logic for integrating with third-party services.\n* [SmartDash Websocket](packages/smart_dash_websocket/README.md): Supports multiplexing messages over same connection.\n* [SmartDash Datasource](packages/smart_dash_datasource/README.md): Data access and persistence-related utilities.\n* [Restoration Web Plugin](packages/restoration_web_plugin/README.md): Flutter plugin to manage browser-related data persistence.\n\n## Architectural Approach\nThe architecture adheres to the following principles.\n\n### Local-First with Cloud Fallback\nThe Smart Dash app follows a **local-first approach**. It attempts to connect directly to a local daemon using mDNS or UPnP to provide the lowest latency and best user experience. If no local daemon is found or accessible, the app will fall back to connect via the **SmartDash Gateway** in the cloud.\n\n- **Daemon Discovery**: Each time the network state changes, the app checks for local daemons. If it detects a new daemon that hasn't been onboarded, the app will initiate an onboarding process (requiring user authentication and authorization).\n- **REST and WebSocket Support**: Daemons expose both **REST** (for lookups and commands) and **WebSocket** (for listening to real-time updates) APIs, ensuring flexible communication methods for different types of interactions.\n\n### Backend-For-Frontend (BFF) Pattern\nThe **BFF pattern** is used for integrating third-party services, especially in backends like **SmartDash Daemon** and **SmartDash Cloud**. Each integration is tailored for the needs of specific apps or user contexts, ensuring efficient and secure data handling.\n\n### Persistent WebSocket for Monitoring and Control\nThe **SmartDash Daemon** maintains a **persistent WebSocket connection** to the cloud for monitoring and control purposes. This WebSocket is used only for administrative tasks and diagnostics, not for acting as a reverse proxy or for general command execution from the app to the daemon.\n\n## Development Guidelines\n- **Separation of Concerns**: Features encapsulate distinct aspects of business logic, making it easy to maintain and extend functionality as the project evolves.\n- **Local-First Priority**: Always prioritize local connections for daemons when building or modifying features. The fallback to the cloud should be seamless for users.\n- **Vertical Slice Implementation**: When adding new features, implement them as vertical slices that can be utilized by both apps and backends without duplicating logic.\n\nThis modular approach ensures the codebase remains scalable and maintainable while supporting the complexities of managing smart home environments across multiple user contexts and device types.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkengu%2Fno.kengu.smart_dash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkengu%2Fno.kengu.smart_dash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkengu%2Fno.kengu.smart_dash/lists"}