@@ -217,6 +217,49 @@ flowchart LR
217217 MCPProxy --> SpaceMolt["SpaceMolt MCP Server"]
218218 ```
219219
220+## Provider Architecture
221+
222+Zoea Nova supports two types of LLM providers:
223+
224+### OpenAI-Compatible Providers
225+Providers that follow the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create) specification.
226+
227+**Examples:** OpenCode Zen, OpenAI, Azure OpenAI, Together AI, etc.
228+
229+**Implementation:**
230+- Use shared code in `internal/provider/openai_common.go`
231+- Strict message ordering (system first, alternating user/assistant)
232+- Tool call validation and orphaned message removal
233+- Fallback user message if only system messages exist
234+
235+**Location:** `internal/provider/opencode.go` (reference implementation)
236+
237+### Ollama Provider
238+Custom provider with flexible API that differs from OpenAI standard.
239+
240+**Ollama-Specific Behavior:**
241+- System messages allowed anywhere (not just first)
242+- Custom response types with `reasoning()` method
243+- Flexible message ordering
244+
245+**Implementation:**
246+- Isolated in `internal/provider/ollama.go`
247+- Uses custom types (`ollamaReqMessage`, `chatCompletionResponse`, etc.)
248+- Custom message merging (`mergeConsecutiveSystemMessagesOllama`)
249+- **DO NOT** use Ollama code for OpenAI-compatible providers
250+
251+**Location:** `internal/provider/ollama.go`
252+
253+### Key Files
254+- `internal/provider/openai_common.go` - Shared OpenAI-compliant code (use for new OpenAI-compatible providers)
255+- `internal/provider/opencode.go` - OpenCode Zen implementation (OpenAI-compatible reference)
256+- `internal/provider/ollama.go` - Ollama implementation (isolated, custom)
257+- `documentation/architecture/OPENAI_COMPATIBILITY.md` - Full compatibility guide
258+
259+### Adding New Providers
260+- **OpenAI-compatible:** Use `openai_common.go` functions, follow OpenCode pattern
261+- **Custom API:** Create isolated implementation like Ollama, document differences
262+
220263 ## State Machine
221264
222265 See `documentation/architecture/MYSIS_STATE_MACHINE.md` for valid Mysis transitions and triggers.