From 26b3e6112853f162d6db13446dc698e9af0e9fc2 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Tue, 7 Apr 2026 16:38:41 +0000 Subject: [PATCH] docs: sync from docs/wiki/ at commit 21a41326 --- AI-Providers.md | 50 ++++++++++++++++++------------------------------- Architecture.md | 36 ++++++++++++++++++++++++++--------- Home.md | 4 ++-- 3 files changed, 47 insertions(+), 43 deletions(-) diff --git a/AI-Providers.md b/AI-Providers.md index 74c1f40..037d964 100644 --- a/AI-Providers.md +++ b/AI-Providers.md @@ -147,33 +147,25 @@ Standard OpenAI `/chat/completions` endpoint with Bearer authentication. ### Format: Custom REST -**Motorola Solutions Internal GenAI Service** — Enterprise AI platform with centralized cost tracking and model access. +**Enterprise AI Gateway** — For AI platforms that use a non-OpenAI request/response format with centralized cost tracking and model access. | Field | Value | |-------|-------| | `config.provider_type` | `"custom"` | | `config.api_format` | `"custom_rest"` | -| API URL | `https://genai-service.commandcentral.com/app-gateway` (prod)
`https://genai-service.stage.commandcentral.com/app-gateway` (stage) | -| Auth Header | `x-msi-genai-api-key` | -| Auth Prefix | `` (empty - no Bearer prefix) | -| Endpoint Path | `` (empty - URL includes full path `/api/v2/chat`) | - -**Available Models (dropdown in Settings):** -- `VertexGemini` — Gemini 2.0 Flash (Private/GCP) -- `Claude-Sonnet-4` — Claude Sonnet 4 (Public/Anthropic) -- `ChatGPT4o` — GPT-4o (Public/OpenAI) -- `ChatGPT-5_2-Chat` — GPT-4.5 (Public/OpenAI) -- Full list is sourced from [GenAI API User Guide](../GenAI%20API%20User%20Guide.md) -- Includes a `Custom model...` option to manually enter any model ID +| API URL | Your gateway's base URL | +| Auth Header | Your gateway's auth header name | +| Auth Prefix | `` (empty if no prefix needed) | +| Endpoint Path | `` (empty if URL already includes full path) | **Request Format:** ```json { - "model": "VertexGemini", + "model": "model-name", "prompt": "User's latest message", "system": "Optional system prompt", "sessionId": "uuid-for-conversation-continuity", - "userId": "user.name@motorolasolutions.com" + "userId": "user@example.com" } ``` @@ -191,32 +183,27 @@ Standard OpenAI `/chat/completions` endpoint with Bearer authentication. - **Single prompt** instead of message array (server manages history via `sessionId`) - **Response in `msg` field** instead of `choices[0].message.content` - **Session-based** conversation continuity (no need to resend history) -- **Cost tracking** via `userId` field (optional — defaults to API key owner if omitted) -- **Custom client header**: `X-msi-genai-client: tftsr-devops-investigation` +- **Cost tracking** via `userId` field (optional) **Configuration (Settings → AI Providers → Add Provider):** ``` -Name: Custom REST (MSI GenAI) +Name: Custom REST Gateway Type: Custom API Format: Custom REST -API URL: https://genai-service.stage.commandcentral.com/app-gateway -Model: VertexGemini -API Key: (your MSI GenAI API key from portal) -User ID: your.name@motorolasolutions.com (optional) -Endpoint Path: (leave empty) -Auth Header: x-msi-genai-api-key -Auth Prefix: (leave empty) +API URL: https://your-gateway/api/v2/chat +Model: your-model-name +API Key: (your API key) +User ID: user@example.com (optional, for cost tracking) +Endpoint Path: (leave empty if URL includes full path) +Auth Header: x-custom-api-key +Auth Prefix: (leave empty if no prefix) ``` -**Rate Limits:** -- $50/user/month (enforced server-side) -- Per-API-key quotas available - **Troubleshooting:** | Error | Cause | Solution | |-------|-------|----------| -| 403 Forbidden | Invalid API key or insufficient permissions | Verify key in MSI GenAI portal, check model access | +| 403 Forbidden | Invalid API key or insufficient permissions | Verify key in your gateway portal, check model access | | Missing `userId` field | Configuration not saved | Ensure UI shows User ID field when `api_format=custom_rest` | | No conversation history | `sessionId` not persisted | Session ID stored in `ProviderConfig.session_id` — currently per-provider, not per-conversation | @@ -224,7 +211,6 @@ Auth Prefix: (leave empty) - Backend: `src-tauri/src/ai/openai.rs::chat_custom_rest()` - Schema: `src-tauri/src/state.rs::ProviderConfig` (added `user_id`, `api_format`, custom auth fields) - Frontend: `src/pages/Settings/AIProviders.tsx` (conditional UI for Custom REST + model dropdown) -- CSP whitelist: `https://genai-service.stage.commandcentral.com` and production domain --- @@ -239,7 +225,7 @@ All providers support the following optional configuration fields (v0.2.6+): | `custom_auth_prefix` | `Option` | Prefix before API key | `Bearer ` | | `api_format` | `Option` | API format (`openai` or `custom_rest`) | `openai` | | `session_id` | `Option` | Session ID for stateful APIs | None | -| `user_id` | `Option` | User ID for cost tracking (Custom REST MSI contract) | None | +| `user_id` | `Option` | User ID for cost tracking (Custom REST gateways) | None | **Backward Compatibility:** All fields are optional and default to OpenAI-compatible behavior. Existing provider configurations are unaffected. diff --git a/Architecture.md b/Architecture.md index 0cb4284..2a3a059 100644 --- a/Architecture.md +++ b/Architecture.md @@ -29,7 +29,8 @@ TFTSR uses a Tauri 2.x architecture: a Rust backend runs natively, and a React/T pub struct AppState { pub db: Arc>, pub settings: Arc>, - pub app_data_dir: PathBuf, // ~/.local/share/tftsr on Linux + pub app_data_dir: PathBuf, // ~/.local/share/trcaa on Linux + pub integration_webviews: Arc>>, } ``` @@ -46,10 +47,10 @@ All command handlers receive `State<'_, AppState>` as a Tauri-injected parameter | `commands/analysis.rs` | Log file upload, PII detection, redaction | | `commands/docs.rs` | RCA and post-mortem generation, document export | | `commands/system.rs` | Ollama management, hardware probe, settings, audit log | -| `commands/integrations.rs` | Confluence / ServiceNow / ADO — v0.2 stubs | +| `commands/integrations.rs` | Confluence / ServiceNow / ADO — OAuth2, WebView auth, tool calling | | `ai/provider.rs` | `Provider` trait + `create_provider()` factory | | `pii/detector.rs` | Multi-pattern PII scanner with overlap resolution | -| `db/migrations.rs` | Versioned schema (10 migrations in `_migrations` table) | +| `db/migrations.rs` | Versioned schema (14 migrations tracked in `_migrations` table) | | `db/models.rs` | All DB types — see `IssueDetail` note below | | `docs/rca.rs` + `docs/postmortem.rs` | Markdown template builders | | `audit/log.rs` | `write_audit_event()` — called before every external send | @@ -178,14 +179,31 @@ Use `detail.issue.title`, **not** `detail.title`. ``` 1. Initialize tracing (RUST_LOG controls level) -2. Determine data directory (~/.local/share/tftsr or TFTSR_DATA_DIR) -3. Open / create SQLite database (run migrations) -4. Create AppState (db + settings + app_data_dir) -5. Register Tauri plugins (stronghold, dialog, fs, shell, http, cli, updater) -6. Register all 39 IPC command handlers -7. Start WebView with React app +2. Determine data directory (state::get_app_data_dir() or TFTSR_DATA_DIR) +3. Auto-generate or load .dbkey / .enckey (mode 0600) — see ADR-005 +4. Open / create SQLCipher encrypted database + - If plain SQLite detected (debug→release upgrade): auto-migrate + backup +5. Run DB migrations (14 schema versions) +6. Create AppState (db + settings + app_data_dir + integration_webviews) +7. Register Tauri plugins (stronghold, dialog, fs, shell, http) +8. Register all IPC command handlers via generate_handler![] +9. Start WebView with React app ``` +## Architecture Documentation + +Full architecture documentation with C4 diagrams, data flow diagrams, and Architecture Decision Records (ADRs) is available in [`docs/architecture/`](../architecture/README.md): + +| Document | Contents | +|----------|----------| +| [Architecture Overview](../architecture/README.md) | C4 diagrams, data flows, security model | +| [ADR-001](../architecture/adrs/ADR-001-tauri-desktop-framework.md) | Why Tauri over Electron | +| [ADR-002](../architecture/adrs/ADR-002-sqlcipher-encrypted-database.md) | SQLCipher encryption choices | +| [ADR-003](../architecture/adrs/ADR-003-provider-trait-pattern.md) | AI provider trait design | +| [ADR-004](../architecture/adrs/ADR-004-pii-regex-aho-corasick.md) | PII detection implementation | +| [ADR-005](../architecture/adrs/ADR-005-auto-generate-encryption-keys.md) | Key auto-generation design | +| [ADR-006](../architecture/adrs/ADR-006-zustand-state-management.md) | Frontend state management | + ## Data Flow ``` diff --git a/Home.md b/Home.md index fe15cb0..58074eb 100644 --- a/Home.md +++ b/Home.md @@ -24,7 +24,7 @@ - **5-Whys AI Triage** — Interactive guided root cause analysis via multi-turn AI chat - **PII Auto-Redaction** — Detects and redacts sensitive data before any AI send -- **Multi-Provider AI** — OpenAI, Anthropic Claude, Google Gemini, Mistral, AWS Bedrock (via LiteLLM), MSI GenAI (Motorola internal), local Ollama (fully offline) +- **Multi-Provider AI** — OpenAI, Anthropic Claude, Google Gemini, Mistral, AWS Bedrock (via LiteLLM), Custom REST gateways, local Ollama (fully offline) - **Custom Provider Support** — Flexible authentication (Bearer, custom headers) and API formats (OpenAI-compatible, Custom REST) - **External Integrations** — Confluence, ServiceNow, Azure DevOps with OAuth2 PKCE flows - **SQLCipher AES-256** — All issue history and credentials encrypted at rest @@ -37,7 +37,7 @@ | Version | Status | Highlights | |---------|--------|-----------| -| v0.2.6 | 🚀 Latest | MSI GenAI support, OAuth2 shell permissions, user ID tracking | +| v0.2.6 | 🚀 Latest | Custom REST AI gateway support, OAuth2 shell permissions, user ID tracking | | v0.2.3 | Released | Confluence/ServiceNow/ADO REST API clients (19 TDD tests) | | v0.1.1 | Released | Core application with PII detection, RCA generation |