Skip to content

development.md

Latest commit

 

History

History
103 lines (78 loc) · 4.51 KB

development.md

File metadata and controls

103 lines (78 loc) · 4.51 KB
Raw

Development Guide

This guide covers local development for Ech0 — environment setup, hot reload, and front-/back-end integration. For higher-level architecture see CLAUDE.md and CONTRIBUTING.md.

Backend Requirements

📌 Go 1.27.0+

📌 C Compiler When using CGO-dependent libraries such as go-sqlite3, install:

  • Windows:
    • MinGW-w64
    • Add the bin directory to PATH after extraction
  • macOS: brew install gcc
  • Linux: sudo apt install build-essential

📌 Google Wire Install wire for dependency injection file generation:

  • go install github.com/google/wire/cmd/wire@latest

📌 Golangci-Lint Install Golangci-Lint for linting and formatting:

  • Run golangci-lint run in the project root for linting
  • Run golangci-lint fmt in the project root for formatting

📌 Air (Optional, Backend Hot Reload)

  • Recommended via justfile: just air-install
  • Or install manually: go install github.com/air-verse/air@latest

📌 Swagger Install Swagger to generate/use OpenAPI docs:

  • Run swag init -g internal/server/server.go -o internal/swagger in project root to generate or update Swagger docs
  • Visit http://localhost:6277/swagger/index.html in your browser to view and use docs

📌 Event Runtime Parameters (Busen)

  • ECH0_EVENT_DEFAULT_BUFFER / ECH0_EVENT_DEFAULT_OVERFLOW
  • ECH0_EVENT_SYSTEM_BUFFER
  • ECH0_EVENT_AGENT_BUFFER / ECH0_EVENT_AGENT_PARALLELISM
  • ECH0_EVENT_WEBHOOK_POOL_WORKERS / ECH0_EVENT_WEBHOOK_POOL_QUEUE

📌 Agent (Copilot) Parameters

  • ECH0_AGENT_TIMEOUT_SECONDS — generation budget (seconds) for one Copilot chat run: model streaming plus non-interactive tools; default 120, <=0 disables it. Time spent waiting on a person is credited back rather than charged here.
  • ECH0_AGENT_MAX_ROUNDS — how many tool-calling rounds one run may take before it must answer; default 4.
  • ECH0_AGENT_ASK_TIMEOUT_SECONDS — how long a run parks waiting for you to answer a question or confirm a write (ask_user, create_echo, update_echo, delete_echo); default 300. A round that expires performs nothing.

📌 OpenAPI Docs Panel

  • ECH0_OPENAPI_DOCS_RENDERER — renderer for the /api/docs panel: stoplight (default, Huma's built-in Stoplight Elements, loaded from CDN) or scalar (self-hosted offline Scalar, asset embedded in the binary — no network needed). Unknown values fall back to stoplight.

Frontend Requirements

📌 NodeJS v26.0.0+, PNPM v10.30.0+

Note: if you need multiple Node.js versions, use fnm to manage them.

Start Backend & Frontend

Step 1: Backend (in Ech0 root directory)

just run # normal backend start (equivalent to go run main.go serve)
just dev # backend hot reload with Air

If dependency injection relationships change, run wire first in ech0/internal/di/ to regenerate wire_gen.go.

Step 2: Frontend (new terminal)

cd web # enter frontend directory

pnpm install # run if dependencies are not installed

pnpm dev # start frontend preview
# or run from project root: just web dev

Step 3: After both are running

  • Frontend preview: http://localhost:5173 (actual port shown in terminal after start)
  • Backend preview: http://localhost:6277 (default backend port is 6277)

When importing packages in a layered architecture, use standardized alias names:

  • model layer: xxxModel
  • util layer: xxxUtil
  • handler layer: xxxHandler
  • service layer: xxxService
  • repository layer: xxxRepository

Pre-PR Checklist

just check        # backend fmt + lint + openapi, web format + lint + i18n:check
just wire-check   # ensure wire_gen.go is up-to-date
go build ./...
pnpm -C web build

See CONTRIBUTING.md for the full PR workflow.

More Reference Docs