aethera/backend/AGENTS.md

Backend Agent Instructions

Stack

• Go 1.25.5
• cobra (CLI framework)
• logrus (structured logging)
• openai-go/v3 (OpenAI API client)
• golangci-lint (linting)

Commands

go build -o ./dist/aethera ./cmd
golangci-lint run
go test ./...

Non-Negotiables

• ❌ No unhandled errors - always check err
• ❌ No ignored linter warnings
• ❌ No sensitive data in logs
• ❌ No hardcoded paths - use path.Join
• ❌ No unsafe file access - use filepath.Base
• ❌ Don't skip tests or linting

Code Style

• tab indentation, PascalCase exports, camelCase internal
• Error wrapping with context: fmt.Errorf("...: %w", err)
• Custom error types for domain errors (e.g., ChatNotFoundError)
• Struct tags for JSON with omitempty
• Log with context: log.WithField("key", val)
• Clean up resources with defer

Key Patterns

• Interfaces: Store interface for swappable backends
• DI: Dependencies through constructors (New* functions)
• HTTP: Handlers receive store.Store, validate inputs, return proper status codes
• Streaming: Use FlushWriter for SSE/text streams
• Storage: JSON file-based (FileStore implementation)

What Goes Where

• CLI entry: cmd/ (main.go, config.go)
• HTTP handlers: internal/api/
• OpenAI client: internal/client/
• Server setup: internal/server/
• Storage interface & impl: internal/store/
• Storage utilities: internal/storage/
• Utilities: pkg/ (ptr, slices)