docs: add project essentials (12/12 complete)

Vision, domain model, architecture, patterns, process flows, UML diagrams, API contracts, tech stack, constraints, milestones (M1-M11), decision log (6 ADRs), and risk register. Key decisions: single binary, pull-based streaming, Mistral as M1 reference provider, discriminated unions, multi-provider collaboration as core identity.
2026-04-02 18:09:07 +02:00
parent f909733bff
commit efcb5a2901
14 changed files with 1638 additions and 0 deletions
@@ -0,0 +1,85 @@
+---
+essential: tech-stack
+status: complete
+last_updated: 2026-04-02
+project: gnoma
+depends_on: []
+---
+
+# Tech Stack & Conventions
+
+## Languages
+
+| Language | Version | Role |
+|----------|---------|------|
+| Go | 1.26 | Primary — all application code |
+
+## Frameworks & Libraries
+
+| Library | Module | Purpose |
+|---------|--------|---------|
+| Mistral SDK | `somegit.dev/vikingowl/mistral-go-sdk` | Mistral API client (user-maintained) |
+| Anthropic SDK | `github.com/anthropics/anthropic-sdk-go` | Anthropic API client |
+| OpenAI SDK | `github.com/openai/openai-go` | OpenAI API client (+ compat endpoints) |
+| Google GenAI | `google.golang.org/genai` | Google Gemini API client |
+| TOML | `github.com/BurntSushi/toml` | Configuration file parsing |
+| Bubble Tea | `github.com/charmbracelet/bubbletea/v2` | Terminal UI framework |
+| Lip Gloss | `github.com/charmbracelet/lipgloss` | Terminal styling |
+| Bubbles | `github.com/charmbracelet/bubbles` | TUI components (input, viewport) |
+| Doublestar | `github.com/bmatcuk/doublestar/v4` | Glob with `**` support |
+
+## Go 1.26 Features Used
+
+| Feature | Where |
+|---------|-------|
+| `new(expr)` | Optional pointer fields in config/params |
+| `errors.AsType[E](err)` | Provider error handling |
+| `sync.WaitGroup.Go(f)` | Goroutine management |
+| `slog.NewMultiHandler()` | Fan-out logging |
+| `testing/synctest` | Concurrent test support |
+| Green Tea GC (default) | No action needed — 10-40% less GC overhead |
+| `io.ReadAll` 2x faster | File tool reads |
+
+## Tooling
+
+- **Build:** `go build` via Makefile
+- **CI/CD:** none yet (planned)
+- **Linting:** `golangci-lint`
+- **Testing:** stdlib `testing`, `testing/synctest`
+- **Package management:** Go modules
+
+## Conventions
+
+### Naming
+
+- Files: lowercase, underscores for multi-word (`tool_result.go`)
+- Packages: short, lowercase, no underscores (`provider`, `stream`)
+- Functions/methods: camelCase (`NewUserText`, `HasToolCalls`)
+- Types/structs: PascalCase (`ToolCall`, `ProviderError`)
+- Constants: PascalCase for exported (`StopEndTurn`), camelCase for unexported
+- Interfaces: describe behavior (`Provider`, `Stream`, `Tool`), not implementation
+
+### Error Handling
+
+- Explicit error types with `%w` wrapping
+- `errors.AsType[E]` for type-safe extraction (Go 1.26)
+- `Err` prefix for sentinel errors (`ErrDenied`)
+- `*Error` suffix for error types (`ProviderError`)
+- Fail fast — never swallow errors
+- Include context in error messages
+
+### File Organization
+
+- By layer within `internal/`: `message/`, `stream/`, `provider/`, `tool/`, `engine/`, `session/`
+- Provider adapters: one directory per provider under `internal/provider/`
+- Tool implementations: one directory per tool type under `internal/tool/`
+- Three files per provider adapter: `provider.go`, `translate.go`, `stream.go`
+
+### Commit Style
+
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
+- No co-signing
+
+## Changelog
+
+- 2026-04-02: Initial version