Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• vite.config.ts
• netlify.toml
• README.md
• CONTRIBUTING.md
• GEMINI.md

BMSview is an advanced web application for analyzing Battery Management System (BMS) screenshots. It utilizes Google's Gemini AI to provide users with detailed insights into their battery performance, including historical tracking, solar energy estimation, and anomaly detection. This guide provides all the necessary steps to set up the development environment, understand the project structure, and start contributing.

The application is built on a modern technology stack featuring a React frontend and a serverless backend using Netlify Functions. For more in-depth information on the system's design, refer to the Architecture and Deployment sections.

Sources: README.md:5-7, GEMINI.md:9-16, CONTRIBUTING.md:3, CODEBASE.md:7-8

Prerequisites

Before you begin, ensure you have the following software and credentials installed and configured on your local machine.

• Node.js: Version 20 or higher is required.
• Package Manager: npm or yarn.
• MongoDB: A running instance, either locally or on a cloud service like MongoDB Atlas.
• Google Gemini API Key: An API key for accessing the Gemini AI model.

Sources: CONTRIBUTING.md:19-23, README.md:40

Local Environment Setup

Follow these steps to get a local copy of the project up and running for development.

1. Fork and Clone

First, create a fork of the repository on GitHub and then clone your fork to your local machine.

git clone https://github.com/YOUR_USERNAME/BMSview.git
cd BMSview

Sources: CONTRIBUTING.md:26-29

2. Install Dependencies

Install the required Node.js packages using npm.

npm install

Sources: CONTRIBUTING.md:32-34, README.md:43-45

3. Configure Environment Variables

Create a .env.local file in the root of the project directory. This file will hold your secret keys and database connection strings.

GEMINI_API_KEY=your_gemini_api_key
MONGODB_URI=your_mongodb_connection_string
MONGODB_DB_NAME=bmsview

The following table describes the necessary environment variables:

Variable	Description	Example
GEMINI_API_KEY	Your API key for the Google Gemini service.	AIzaSy...
MONGODB_URI	The connection string for your MongoDB instance.	mongodb+srv://...
MONGODB_DB_NAME	The name of the database to use.	bmsview

Sources: CONTRIBUTING.md:36-41, README.md:47-52, GEMINI.md:70-75

4. Run the Development Server

Once the dependencies are installed and the environment is configured, you can start the local development server.

npm run dev

The application will be available at http://localhost:5173.

Sources: CONTRIBUTING.md:43-45, README.md:54-56, GEMINI.md:77-80

The local setup process can be visualized with the following diagram.

Project Structure

The repository is organized into distinct directories for the frontend, backend, and shared utilities. This structure separates concerns and improves maintainability.

BMSview/
├── components/           # React UI components
├── services/             # API clients and data services
├── hooks/                # Custom React hooks
├── utils/                # Shared utility functions (frontend)
├── types/                # TypeScript type definitions
├── state/                # State management (Context API)
├── netlify/functions/    # Serverless backend functions
└── tests/                # Test files

• components/: Contains all React components, which form the UI of the application.
• services/: Houses modules for interacting with external and internal APIs (e.g., geminiService.ts, solarService.ts).
• hooks/: Stores custom React hooks used across the application.
• utils/: Contains shared utility functions for the frontend. Backend utilities are located within netlify/functions/utils/.
• types/: Defines shared TypeScript types and interfaces.
• state/: Manages global application state using React's Context API.
• netlify/functions/: The serverless backend, with each file representing a separate API endpoint.
• tests/: Contains all test files for the project.

Sources: CONTRIBUTING.md:175-184, README.md:79-92

Technology Stack

BMSview is built with a modern technology stack designed for performance and scalability.

Category	Technology	Description
Frontend	React 18, Vite, TypeScript	A fast, modern single-page application framework.
Styling	Tailwind CSS	A utility-first CSS framework for rapid UI development.
Backend	Netlify Functions (Node.js)	Serverless functions for handling API requests.
Database	MongoDB	A NoSQL database for storing analysis data and user information.
AI	Google Gemini	Powers the core screenshot analysis and insights generation.
APIs	OpenWeather API, Solar Charge Estimator	Used for integrated weather and solar features.

Sources: README.md:106-112, GEMINI.md:20-26

Development Workflow

Contributors should follow a consistent workflow to ensure code quality and a clean project history.

This diagram illustrates the standard contribution workflow.

Key Steps

1. Create a Branch: Always create a new feature or fix branch from the main branch.

   git checkout -b feature/your-feature-name
   

2. Make Changes: Implement your feature or bug fix, adhering to the project's Coding Standards.
3. Test Locally: Before committing, run all tests and a production build to ensure nothing is broken. This is a mandatory step.

   npm test
   npm run build
   

4. Commit Changes: Use conventional commit messages to clearly describe your changes (e.g., feat:, fix:, docs:).
5. Push and Open PR: Push your branch to your fork and open a pull request against the main repository.

Sources: CONTRIBUTING.md:49-91

Available Scripts

The package.json file defines several scripts for common development tasks.

Script	Description
npm run dev	Starts the Vite development server for local development.
npm run build	Builds the application for production. This must pass before a PR is merged.
npm run preview	Serves the production build locally for previewing.
npm test	Runs the entire test suite.
npm run lint:fix	Automatically fixes linting issues in the codebase.

Sources: package.json:7-16, CONTRIBUTING.md:58-61, README.md:54-64

Deployment

The application is configured for continuous deployment via Netlify.

The deployment process is automated:

1. Changes are pushed to the main branch on GitHub.
2. Netlify detects the push and automatically triggers a new build using the npm run build command.
3. If the build is successful, Netlify deploys the new version to production.

This flow is defined in the netlify.toml configuration file, which specifies the build command and the publish directory.

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

Sources: netlify.toml:2-4, README.md:114-118, CONTRIBUTING.md:60-61