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 ./...

Testing

All Go code is tested using the testify framework with comprehensive test coverage:

• Unit Tests: Each function and method is thoroughly tested including edge cases
• Integration Tests: Store implementations are tested end-to-end
• Error Handling: All error conditions are explicitly tested
• Concurrency: Thread-safety of concurrent operations is verified
• File Operations: File-based storage tests use temporary directories

Tests follow these conventions:

• Use require.NoError(t, err) for fatal errors that break test flow
• Use assert.NoError(t, err) for non-fatal assertions
• Test both success and error paths for all methods
• Use table-driven tests where appropriate
• All tests are run with go test ./... or go test -v ./...

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) with in-memory alternative (InMemoryStore)

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)