# fzorri/second-opinion architecture

> Architecture diagram of the GitHub repository fzorri/second-opinion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fzorri/second-opinion
- Repository: https://github.com/fzorri/second-opinion

## Overview

##### What this project is (type + purpose)
**Second Opinion** is a **local Python CLI application** that lets a user chat with **many different LLM providers** through a single interface, with:
- **Runtime model selection** (currently “26” models, configurable)
- **Provider-specific adapters/wrappers** (OpenAI, Anthropic, Groq, Google, etc.)
- **Local persistence of conversation history** (JSON on disk, per model/folder)
- A **models registry/config** (`models.yaml`) + **secrets** (`.env`)

So the architecture is best represented as:
- A **client-side CLI app** (no server you deploy)
- That orchestrates **outbound API calls** to multiple external LLM services
- And reads/writes local config + local history storage

This is not a typical “frontend/backend/database” web system; it’s a **pluggable CLI orchestrator + adapters**.

##### Read the file tree as architecture hints (what each area likely represents)
Top-level:
- `secop.py` → **main entrypoint / CLI controller** (menu, model selection, chat loop, autocheck, history mode)
- `tools.py` → shared **utilities** (formatting, IO helpers, request helpers, etc.)
- `config.py` → config loading / environment handling / defaults (likely `.env`, paths, toggles)
- `models.yaml` → **model catalog + settings** (enable/disable models, provider mapping, folders, params)
- `history.py` → **local conversation persistence & history operations** (browse, preview, merge, delete, resume)
- `llm_classes/` → **provider abstraction layer**:
- `llm_base.py` → common interface/contract used by `secop.py`
- `llm_*_base.py` → provider-specific implementations (Anthropic/Google/OpenAI/Groq/etc.)
- `requirements.txt` → Python deps (implies runtime environment and 3rd-party HTTP SDKs)
- `secop.bat` → Windows convenience launcher

This tree strongly suggests a “core app” that depends on a “provider adapter layer” and a “local storage/history layer”.

**Nodes to include:**
- **User (CLI Operator)**
- **Second Opinion CLI App (Python process)**
- **Local File System**
- `.env` (secrets) *(even if not committed, it’s runtime-critical)*
- `models.yaml` (model definitions)
- `history/…` folders (JSON conversation logs; structure determined by `model_folder` in `models.yaml`)
- **External LLM Providers (Internet)**
- OpenAI API
- Anthropic API
- Google API
- Groq API
- xAI API
- DeepSeek / Fireworks / GLM / etc. (group them if needed)

- User → CLI: prompts, commands (“end”, menu selection)
- CLI → External LLM APIs: prompt/messages + model params
- External APIs → CLI: completions/responses
- CLI ↔ Local FS: read config + write/read history JSON

Goal: show the **major subsystems inside the Python process** and how they interact.

Recommended containers/components inside “Second Opinion CLI”:
##### CLI Controller / Orchestrator (`secop.py`)
- menu
- chat loop
- autocheck loop
- routing to history mode
##### Configuration & Model Registry
- `models.yaml` loader (often in `config.py` or in `secop.py`)
- `.env` secret loader (via `config.py`)
- Produces: “Enabled models list” + provider mapping + per-model params
##### LLM Provider Abstraction Layer (`llm_classes/`)
- `LLMBase` interface (`llm_base.py`)
- concrete providers (`llm_openai_chatgpt_base.py`, `llm_anthropic_base.py`, etc.)
- responsibility: normalize “send messages” / “get response” across vendors
##### History / Persistence Subsystem (`history.py`)
- write conversation JSON
- browse/preview/resume/merge/delete
##### Utilities (`tools.py`)
- formatting/markup rendering
- shared helpers for file IO, validation, etc.

- `secop.py` → Config/Registry: “load enabled models”
- `secop.py` → LLMBase implementations: “send conversation”
- `secop.py` → History subsystem: “save conversation”, “load conversation”, “merge”
- Provider implementations → External APIs (outbound HTTPS)
- History subsystem → Local disk (JSON)

##### Flow 1: “Start app → pick model → chat → save”
Sequence (recommended lifelines):
- User
- `secop.py` (controller)
- Config loader (`config.py` / `models.yaml`)
- Provider instance (`LLMBase` + specific implementation)
- External LLM API
- History manager (`history.py`)
- Local disk

Steps to show:

##### Flow 2: “History mode → resume conversation”
Show:
- user selects prior JSON conversation
- history loads JSON
- secop routes to provider and continues messages

##### Flow 3: “Autocheck option A”
Show:
- loop over enabled models in `models.yaml`
- attempt lightweight request per provider
- report success/failure (and potentially store diagnostics)

##### Architectural patterns/design principles to explicitly call out
These are visible from the structure and should be represented:

##### Adapter/Strategy pattern for providers
- `LLMBase` = stable interface
- `llm_*` = interchangeable strategies chosen by config

##### Configuration-driven composition
- `models.yaml` controls which models exist + parameters + storage folders.
- `.env` controls secrets without code changes.

##### Local-first persistence
- history is stored on disk as JSON, per model folder.

##### Single-process CLI runtime
- everything runs in one Python process; no internal network hops.

Labels directly on components:
- **Python 3.10+** runtime (Conda env recommended by README)
- **CLI** interface (terminal)
- **YAML** config (`models.yaml`)
- **Environment variables** (`.env` from `.env.template`)
- **JSON** persistence (conversation logs)
- **Outbound HTTPS** to external LLM APIs

- Chat flow
- History resume (or Autocheck)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (Top)
    %% =========================
    U["User (CLI Operator)\nTerminal commands + prompts"]:::external

    subgraph "Second Opinion (Local Python 3.10+ CLI Process)"
        SO["CLI Controller / Orchestrator\n(menu • model selection • chat loop • autocheck • history mode)"]:::core

        subgraph "Configuration & Registry (Configuration-driven composition)"
            CFG["Config & Environment Handling\n(load .env • defaults • paths/toggles)"]:::core
            REG["Model Registry / Catalog\n(enabled models • provider mapping • model params)"]:::core
            ENV[".env (secrets)\nAPI keys per provider"]:::doc
            MYAML["models.yaml (YAML)\nmodel definitions + params + model_folder"]:::doc
        end

        TOOLS["Utilities / Shared Helpers\n(formatting • IO helpers • validation)"]:::core

        subgraph "LLM Provider Abstraction Layer (Adapter/Strategy Pattern)"
            PKG["llm_classes/ (Provider Adapters Package)"]:::pkg
            IBASE["LLMBase Interface / Contract\n(normalize send_messages/get_response)"]:::iface

            subgraph "Provider Adapters (Vendor strategies)"
                OA["OpenAI Adapter\n(auth: API key from .env)"]:::adapter
                AN["Anthropic Adapter\n(auth: API key from .env)"]:::adapter
                GG["Google Adapter\n(auth: API key from .env)"]:::adapter
                GQ["Groq Adapter\n(auth: API key from .env)"]:::adapter
                XA["xAI Adapter\n(auth: API key from .env)"]:::adapter
                DS["DeepSeek Adapter\n(auth: API key from .env)"]:::adapter
                FW["Fireworks Adapter\n(auth: API key from .env)"]:::adapter
                GL["GLM Adapter\n(auth: API key from .env)"]:::adapter
                OT["Other Providers\n(etc.)"]:::adapter
            end
        end

        HIST["History / Persistence Subsystem\n(JSON conversations • browse/preview/resume/merge/delete)\n(per-model folder from model_folder)"]:::core
        STORE[("Local History Store\nhistory/... JSON files per model")]:::storage

        REQ["Dependencies List\n(Vendor SDKs + HTTP client libs)"]:::doc
        BAT["Windows Launcher (optional)\nConvenience entry to run CLI"]:::doc
    end

    subgraph "External LLM Providers (Outbound HTTPS)"
        OAI["OpenAI API"]:::cloud
        ANT["Anthropic API"]:::cloud
        GGL["Google API"]:::cloud
        GRQ["Groq API"]:::cloud
        XAI["xAI API"]:::cloud
        OTH["DeepSeek / Fireworks / GLM / etc."]:::cloud
    end

    %% =========================
    %% Context Flows
    %% =========================
    U -->|"commands/prompt"| SO
    SO -->|"rendered output"| U

    %% Config dependencies (dashed)
    SO -.->|"load config"| CFG
    CFG -.->|"read secrets"| ENV
    SO -.->|"read models"| REG
    REG -.->|"parse YAML"| MYAML

    %% Utilities
    SO -->|"format/IO helpers"| TOOLS
    HIST -->|"shared helpers"| TOOLS

    %% History read/write (bidirectional)
    SO -->|"save/load/browse history"| HIST
    HIST <-->|"read/write JSON"| STORE

    %% Provider selection + runtime calls
    SO -->|"select provider+model\n(from models.yaml mapping)"| IBASE
    IBASE -->|"instantiate adapter strategy"| OA
    IBASE -->|"instantiate adapter strategy"| AN
    IBASE -->|"instantiate adapter strategy"| GG
    IBASE -->|"instantiate adapter strategy"| GQ
    IBASE -->|"instantiate adapter strategy"| XA
    IBASE -->|"instantiate adapter strategy"| DS
    IBASE -->|"instantiate adapter strategy"| FW
    IBASE -->|"instantiate adapter strategy"| GL
    IBASE -->|"instantiate adapter strategy"| OT

    %% Outbound HTTPS to vendors (solid)
    OA -->|"HTTPS request\n(messages+params)"| OAI
    AN -->|"HTTPS request\n(messages+params)"| ANT
    GG -->|"HTTPS request\n(messages+params)"| GGL
    GQ -->|"HTTPS request\n(messages+params)"| GRQ
    XA -->|"HTTPS request\n(messages+params)"| XAI
    DS -->|"HTTPS request\n(messages+params)"| OTH
    FW -->|"HTTPS request\n(messages+params)"| OTH
    GL -->|"HTTPS request\n(messages+params)"| OTH
    OT -->|"HTTPS request\n(messages+params)"| OTH

    OAI -->|"completion/response"| OA
    ANT -->|"completion/response"| AN
    GGL -->|"completion/response"| GG
    GRQ -->|"completion/response"| GQ
    XAI -->|"completion/response"| XA
    OTH -->|"completion/response"| OT

    %% Autocheck flow (represented as dependency edges)
    SO -->|"autocheck loops\n(over enabled models)"| REG
    SO -->|"autocheck ping"| IBASE

    %% Package grouping hint
    PKG --> IBASE

    %% =========================
    %% Click Events (paths only)
    %% =========================
    click SO "https://github.com/fzorri/second-opinion/blob/main/secop.py"
    click BAT "https://github.com/fzorri/second-opinion/blob/main/secop.bat"
    click CFG "https://github.com/fzorri/second-opinion/blob/main/config.py"
    click REG "https://github.com/fzorri/second-opinion/blob/main/models.yaml"
    click MYAML "https://github.com/fzorri/second-opinion/blob/main/models.yaml"
    click HIST "https://github.com/fzorri/second-opinion/blob/main/history.py"
    click TOOLS "https://github.com/fzorri/second-opinion/blob/main/tools.py"
    click IBASE "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_base.py"
    click AN "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_anthropic_base.py"
    click OA "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_openai_chatgpt_base.py"
    click GG "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_google_base.py"
    click GQ "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_groq_base.py"
    click XA "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_xai_base.py"
    click DS "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_deepseek_base.py"
    click FW "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_fireworks_base.py"
    click GL "https://github.com/fzorri/second-opinion/blob/main/llm_classes/llm_glm_base.py"
    click PKG "https://github.com/fzorri/second-opinion/tree/main/llm_classes/"
    click REQ "https://github.com/fzorri/second-opinion/blob/main/requirements.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef core fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1.2px
    classDef adapter fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1.2px
    classDef iface fill:#5b21b6,stroke:#2e1065,color:#ffffff,stroke-width:1.2px
    classDef pkg fill:#4f46e5,stroke:#1e3a8a,color:#ffffff,stroke-width:1.2px
    classDef storage fill:#16a34a,stroke:#14532d,color:#ffffff,stroke-width:1.2px
    classDef doc fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.2px
    classDef cloud fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.2px
    classDef external fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.2px
```
