# Backend Agent Instructions

## Stack

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

## Commands

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

## Testing

All Go code is tested using the [testify](https://github.com/stretchr/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)