Skip to content

Latest commit

 

History

History
124 lines (87 loc) · 3.99 KB

CLAUDE.md

File metadata and controls

124 lines (87 loc) · 3.99 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

evcc is an extensible EV Charge Controller and home energy management system written in Go with a Vue.js frontend. It manages electric vehicle charging, integrates with solar systems, and provides local energy management without cloud dependencies.

Core Development Commands

Build & Development

  • make - Build the full application (UI + Go binary)
  • make build - Build Go binary only
  • make ui - Build UI assets only
  • go run ./... - Run without building binary
  • ./evcc - Run the built binary
  • ./evcc --demo - Run with demo configuration

Dependencies

  • make install - Install Go tools and dependencies
  • make install-ui - Install Node.js dependencies (npm ci)

Testing & Quality

  • make test - Run Go tests
  • make test-ui - Run frontend tests (npm test)
  • make lint - Run Go linting (golangci-lint)
  • make lint-ui - Run frontend linting (Prettier, ESLint, TypeScript)

Frontend Development

Device Templates

  • evcc --template-type charger --template new-charger-template.yaml - Test device templates
  • make docs - Generate template documentation

Architecture

Core Components

  • main.go - Entry point, embeds web assets and i18n files
  • cmd/ - CLI commands and application setup
  • core/ - Core business logic:
    • loadpoint.go - EV charging point management
    • site.go - Site-wide energy management
    • planner/ - Smart charging planning
    • coordinator/ - Multi-loadpoint coordination
  • api/ - API definitions and types
  • server/ - HTTP server, WebSocket, MQTT, and database
  • charger/, meter/, vehicle/ - Device integrations
  • tariff/ - Tariff integrations
  • plugin/ - Plugin system for device and tariff communication
  • assets/ - Vue.js frontend application

Frontend Structure

  • assets/js/ - TypeScript/Vue.js application
  • assets/views/ - Vue components and pages
  • i18n/ - Internationalization files
  • dist/ - Built frontend assets (generated)

Configuration

  • Uses YAML configuration files
  • Templates in templates/definition/ for device and tariff configurations
  • Database: SQLite (default: evcc.db)

Key Development Patterns

Device Integration

  • Device types: chargers, meters, vehicles (and tariffs)
  • Plugin system supports: Modbus, HTTP, MQTT, JavaScript, Go
  • Templates define device capabilities and configuration
  • Use _blueprint.go as starting point for new Go implementations

Testing

  • Go tests use standard testing package
  • Frontend tests use Vitest
  • Integration tests use Playwright
  • Simulator available for testing without real devices

Internationalization

  • Translations managed via Weblate
  • Update both i18n/de.json and i18n/en.json for new strings
  • Use $t() function in Vue components

Important File Locations

  • Configuration: evcc.yaml (or specified with --config)
  • Database: evcc.db (or specified with --database)
  • Device templates: templates/definition/
  • Web assets: assets/ (source), dist/ (built)
  • Generated code: Files ending in _enumer.go, *_decorators.go

Common Development Workflows

Adding New Device Support

  1. Create template in templates/definition/[type]/
  2. If Go code needed, implement in respective package
  3. Test with evcc --template-type [type] --template [file]
  4. Run make docs to update documentation

Frontend Development

  1. Start backend: make build && ./evcc
  2. Start frontend dev server: npm run dev
  3. Access development UI at http://127.0.0.1:7071

Integration Testing

  1. Build application: make ui build
  2. Run tests: npm run playwright
  3. Use simulator for device testing: npm run simulator