Contributing

Thank you for your interest in contributing to Claw Insights! This guide covers everything from setting up your development environment to submitting a pull request.

Getting Set Up

git clone https://github.com/LucaL6/claw-insights.git
cd claw-insights
npm install
npm run dev    # Starts codegen watch + tsx server + vite HMR

Requires Node.js ≥ 22.5 and a running OpenClaw gateway for full functionality.

Open http://localhost:41042 (Vite dev server) to see the dashboard with hot-reload.

Project Structure

packages/
  server/    Express + GraphQL Yoga + SQLite + Satori renderer
  web/       React 19 + Vite + Tailwind + ECharts + urql
  shared/    Generated TypeScript types (from schema.graphql)
bin/         CLI entry (start/stop/restart/status/logs/snapshot)
codegen.ts   GraphQL codegen config (3 targets)

→ For deeper understanding, see Architecture Overview and Data Pipeline.

Workflow: From Issue to PR

1. Understand the Problem

Before writing code, make sure you understand what you're fixing or building:

• Read the issue — understand the expected vs actual behavior
• Reproduce it — can you trigger the bug locally?
• Locate the code — which package? which module? Use the Architecture Overview to orient yourself

2. Create a Branch

git checkout -b fix/issue-description   # for bug fixes
git checkout -b feat/feature-name       # for new features

3. Make Your Changes

Server changes (packages/server/):

• GraphQL schema → edit packages/server/src/schema/schema.graphql
• After schema changes: npm run codegen (regenerates TypeScript types)
• Data pipeline → sources, adapters, ports in packages/server/src/
• Snapshot renderer → packages/server/src/renderer/

Web changes (packages/web/):

• React components → packages/web/src/
• GraphQL queries → urql hooks, types from packages/shared/
• Styles → Tailwind CSS

Documentation (docs/ in the docs repo):

• VitePress markdown files
• Preview locally: npx vitepress dev docs

4. Test Your Changes

npm test                  # Vitest unit tests (fast, run frequently)
npm run test:integration  # GraphQL resolver tests with real server
npm run test:e2e          # End-to-end with mock CLI + fixture data
npx tsc --noEmit          # Type check across all packages

All four must pass before submitting a PR.

5. Submit a PR

git push origin your-branch-name

Then open a pull request on GitHub. In your PR description:

• What — describe the change
• Why — link to the issue or explain the motivation
• How — brief explanation of your approach
• Testing — what you tested and how

Pre-commit Checklist

• [ ] Schema changed → npm run codegen → commit generated files
• [ ] All tests pass: npm test && npm run test:integration && npm run test:e2e
• [ ] Types clean: npx tsc --noEmit
• [ ] No linting errors

Tips

• Start small — a focused PR is easier to review than a large one
• Ask questions — if something is unclear, open an issue or discussion first
• Check existing tests — they often show how a feature is expected to work
• Run npm run dev — the three-process dev server gives you instant feedback on both server and web changes