Home
Relevant source files
The following files were used as context for generating this wiki page:BMSview is an advanced web application designed for the analysis of Battery Management System (BMS) screenshots. It utilizes Google's Gemini AI to provide users with detailed insights into battery performance. The application also integrates features for solar energy estimation and correlates this data with battery charging activity. It is built on a modern technology stack with a focus on a robust, local-first architecture to ensure offline functionality and efficient data synchronization.
A critical aspect of the application is its data privacy model. BMSview is currently a free, unauthenticated application where analysis data is shared globally. Screenshots are identified by their SHA-256 content hash, meaning anyone who uploads an identical image will see the same analysis results. Users should not upload screenshots containing sensitive information.
Sources: GEMINI.md:8-11, README.md:9-13
Core Features
BMSview offers a suite of features for comprehensive battery system analysis.
| Feature | Description |
|---|---|
| AI-Powered Screenshot Analysis | Users can upload BMS screenshots for automated analysis by the Gemini AI. |
| Historical Performance Tracking | The application stores and displays historical battery data through interactive charts and graphs. |
| BMS System Management | Allows users to register and manage multiple distinct BMS systems. |
| Ultimate AI Battery Guru | A context-aware AI assistant that provides rich insights based on system analytics, forecasts, and historical data. It can access the full history of a system to answer complex queries. |
| Solar Integration | Provides solar energy generation estimates based on location and panel specs, and correlates them with battery charging data to identify inefficiencies. |
| Anomaly Detection | Automatically identifies potential issues, performance gaps, and charging problems. |
Sources: GEMINI.md:14-23, README.md:16-37, IMPLEMENTATION_COMPLETE.md:10-14
Technology Stack
The project is built using a modern web stack, leveraging serverless functions for the backend and a reactive frontend library.
| Component | Technology |
|---|---|
| Frontend | React 18, Vite, TypeScript, Tailwind CSS |
| Backend | Netlify Functions (Node.js/TypeScript) |
| Database | MongoDB |
| AI | Google Gemini (specifically Gemini 2.5 Flash) |
| External APIs | Solar Charge Estimator API, OpenWeather API |
| Authentication | Netlify Identity (for admin access) |
Sources: GEMINI.md:26-32, README.md:94-100
The following diagram illustrates the high-level technology integration.
Sources: GEMINI.md:26-32, README.md:94-100
System Architecture
BMSview is designed with a local-first sync architecture. This model prioritizes offline functionality and performance by storing data primarily in the user's browser (IndexedDB) and using intelligent, periodic synchronization with the server.
Sources: GEMINI.md:34-36
Architectural Principles
- Local-First: Data is stored locally in IndexedDB. The server is the authoritative source for conflict resolution.
- Intelligent Sync: Synchronization is triggered by comparing metadata (timestamps, record counts) rather than on every operation, minimizing server load.
- Periodic Sync: A background timer automatically syncs data every 90 seconds.
- Dual-Write for Critical Actions: Key actions, like a new analysis, are written to both the local cache and the server immediately to ensure data persistence.
- UTC Timestamps: All timestamps use the ISO 8601 UTC format for consistency.
Sources: GEMINI.md:39-47
Core Components
The architecture is managed by several key components:
| Component | File Path | Description |
|---|---|---|
SyncManager | src/services/syncManager.ts | Orchestrates the entire sync process, including scheduling and decision-making. |
LocalCache | src/services/localCache.ts | Manages IndexedDB storage using Dexie.js. |
ClientService | services/clientService.ts | An API wrapper that implements the cache-first data fetching strategy. |
AppState | state/appState.tsx | The global React state, managed with useReducer and useContext. |
| Sync Functions | netlify/functions/sync-*.cjs | Serverless functions for backend sync logic. |
Sources: GEMINI.md:50-58
Data Flow
The local-first architecture dictates specific data flow patterns for reading and writing data.
This diagram shows the cache-first strategy for reading data.
Sources: GEMINI.md:61-62
This diagram illustrates the dual-write pattern for critical actions.
Sources: GEMINI.md:63-65
Project Structure
The repository is organized into distinct directories for frontend components, backend functions, services, and state management.
| Directory | Purpose |
|---|---|
components/ | React UI components, including admin and solar-specific ones. |
services/ | API clients and data services for Gemini, solar, and weather APIs. |
hooks/ | Custom React hooks. |
utils/ | Shared utility functions for both frontend and backend. |
types/ | TypeScript type definitions. |
state/ | Global state management using React Context and reducers. |
netlify/functions/ | Serverless backend functions written in Node.js. |
tests/ | Test files for the application. |
Sources: CONTRIBUTING.md:204-213, README.md:64-77
Development and Contribution
Local Setup
To run the project locally, you need Node.js (v20 or later).
- Install Dependencies:
npm install - Configure Environment: Create a
.env.localfile with the necessary API keys and database connection strings.GEMINI_API_KEY=your_gemini_api_key MONGODB_URI=your_mongodb_connection_string MONGODB_DB_NAME=your_database_name - Run Development Server:
npm run dev
The application will be available at http://localhost:5173.
Sources: GEMINI.md:83-100, CONTRIBUTING.md:27-46
Contribution Guidelines
The project accepts contributions from both human developers and AI coding agents.
- Human Contributors: Should create feature branches, follow coding standards, ensure tests pass, and submit pull requests with clear descriptions. Conventional commit messages are used.
- AI Agent Contributors: The repository is configured with detailed instructions for AI agents in
.github/copilot-instructions.md. Issues for AI agents should be well-defined with clear acceptance criteria.
A critical requirement for all contributions is that the code must build successfully using npm run build before a pull request can be merged.
Sources: CONTRIBUTING.md:50-141, GEMINI.md:131-145
Conclusion
BMSview is a sophisticated tool for battery analysis that combines a modern frontend, a serverless backend, and powerful AI capabilities. Its local-first architecture is a key design choice that ensures a responsive user experience and offline availability. The project is well-documented, with clear guidelines for development, contribution, and deployment, making it a robust and maintainable system.
Sources: GEMINI.md:8-11, AUDIT_REPORT.md:13-17