Contributing

Contributions are welcome — whether that’s a new inverter profile, a feature, or a fix.

Get set up

Follow Manual Setup to get the stack running against the simulator. The Scripts reference lists every workspace command.

Before opening a PR, run the checks for the area you touched:

bun run check         # oxlint + oxfmt
bun run check-types   # TypeScript across the monorepo

Repository conventions

This is a bun + Turborepo monorepo. A few rules worth knowing up front (see the AGENTS.md files throughout the repo for the authoritative, area-specific version):

• Environment variables are declared and validated only in packages/env (server.ts / web.ts). Don’t parse process.env or add per-package env schemas elsewhere. See Environment Variables.
• Runtime configuration (inverter connection, MQTT, tariff, profile sources) lives in the app_settings table with per-key Zod schemas in packages/db — not in env. See Settings.
• Inverter support is data. Prefer adding a profile over touching the engine. New canonical concepts go through the role catalog (packages/inverter-core/src/roles.ts).
• Dead code / duplication — the repo uses bunx fallow (dead-code, dupes, health) for code-health checks.

Commit style

Conventional commits: type(scope): summary.

• Imperative, specific subject; lowercase types (feat, fix, refactor, docs, test, chore); scope when useful.
• One commit = one logical change. Don’t mix refactor + feature + formatting noise.

Examples:

• feat(web): add onboarding empty state
• fix(server): prevent duplicate task creation
• docs: clarify post-clone setup

Where things live

Area	Path
Core engine (poll loop, API, MQTT)	apps/server
Dashboard	apps/web
Documentation (this site)	apps/docs
Modbus engine, registry, entity model	packages/inverter-core
Deye / Sunsynk profile	packages/inverter-deye-sg05lp3
Profile SDK + CLI	packages/profile-sdk
Schema, TimescaleDB, runtime settings	packages/db
Env schema, auth, shared config	packages/env, packages/auth, packages/config

See the Architecture Deep-Dive for how these fit together.

Editing these docs

The docs site is Astro Starlight under apps/docs. Pages are Markdown/MDX in src/content/docs; the sidebar is configured in astro.config.mjs. Run it with cd apps/docs && bun dev.