Add StormPilot chat UI, settings and routes

COMPREHENSIVE_STORMPILOT_OLLAMA_ANALYSIS_2026-03-19.md

@@ -0,0 +1,256 @@
+# Comprehensive Review Analysis — StormCom API, Ollama Chat, and StormPilot UX
+
+Date: 2026-03-19  
+Branch: `copilot/build-cloud-chat-interface`
+
+## 1) Scope & Method
+
+This review covered:
+
+1. **Project-wide API landscape** (all `src/app/api/**/route.ts` handlers)
+2. **Ollama AI chat backend** (schema, routes, security, tenancy, rate limit, OpenAI compatibility)
+3. **Official Ollama Cloud/API docs online** (docs.ollama.com via web fetch)
+4. **New UX/UI design and implementation** for a separate chat experience named **StormPilot**
+5. **Browser validation** with business-owner style workflows (login, session management, prompting, settings, attachments)
+
+---
+
+## 2) Project-wide API Audit Summary
+
+Generated inventory file: `COMPREHENSIVE_API_INVENTORY_GENERATED.md`
+
+### Key inventory numbers
+- **Total route handlers:** 256
+- Highest-volume domains:
+  - `admin` (31)
+  - `integrations` (28)
+  - `chat` (25)
+  - `stores` (23)
+  - `subscriptions` (16)
+
+### API architecture observations
+- Large modular API surface organized by business domains (admin, commerce, subscriptions, stores, integrations, chat).
+- Strong use of Next.js App Router route handlers with clear domain folders.
+- Chat domain is a substantial subsystem, not a thin wrapper.
+
+### Security pattern observations (cross-cutting)
+- Broad use of session-authenticated routes (`getServerSession(authOptions)` patterns).
+- Route-level permission/ownership checks exist in many domains.
+- Multi-tenant patterns are present across store/org-aware routes.
+
+> Full endpoint list is intentionally generated into `COMPREHENSIVE_API_INVENTORY_GENERATED.md` for traceability and future audits.
+
+---
+
+## 3) Ollama Chat System — DB Schema Deep Dive
+
+Primary schema file: `prisma/schema.prisma`
+
+### Core AI/Chat models
+
+#### `OllamaConfig`
+Stores user/org/store scoped model runtime configuration:
+- `userId`, `organizationId`, `storeId` scope
+- `host`, `model`, `temperature`, `systemPrompt`
+- `apiKeyEncrypted` (encrypted at rest)
+- `isCloudMode`, `isActive`
+- usage/test metadata (`lastTestAt`, `lastUsedAt`)
+
+#### `ChatSession`
+Conversation container with tenancy & lifecycle metadata:
+- `userId`, `organizationId`, `storeId`
+- `title`, `summary`
+- `isArchived`, `isPinned`
+- `lastMessageAt`, `totalMessages`
+- `metadata` JSON
+
+#### `ChatMessage`
+Per-message records with inference telemetry:
+- `role` (`USER`, `ASSISTANT`, `SYSTEM`, `TOOL`)
+- `content`, optional `thinking`
+- `model`, token metrics (`promptTokens`, `completionTokens`, `totalTokens`)
+- `executionTimeMs`, `toolCalls` JSON
+- linked `attachments`
+
+#### `ChatAttachment`
+Attachment metadata (uploaded/generated/external) linked to `ChatMessage`.
+
+#### `ChatUsageLog`
+Usage/accounting table with model/action/type/token/cost dimensions.
+
+### Schema strengths
+- Good normalized separation of config/session/message/attachment/usage.
+- Strong basis for observability and cost tracking.
+- Multi-tenant identifiers are embedded into session-level records.
+
+---
+
+## 4) Ollama Chat API Deep Dive (In-Project)
+
+### Core chat routes
+- `/api/chat/ollama` — primary chat endpoint (streaming NDJSON, sessions, attachments, model routing)
+- `/api/chat/sessions` and `/api/chat/sessions/[sessionId]` — session lifecycle
+- `/api/chat/messages` — message retrieval and cleanup
+- `/api/chat/history` — compatibility/history operations
+- `/api/chat/usage` — usage stats
+
+### Capability & model routes
+- `/api/chat/models`
+- `/api/chat/models/[name]`
+- `/api/chat/models/running`
+- `/api/chat/models/manage`
+- `/api/chat/capabilities`
+
+### Advanced/feature routes
+- `/api/chat/embed`
+- `/api/chat/image-generate`
+- `/api/chat/semantic-search/products`
+- `/api/chat/tools/execute`
+- `/api/chat/websearch`
+- `/api/chat/webfetch`
+- `/api/chat/actions/parse`
+
+### OpenAI compatibility routes
+- `/api/chat/openai/v1/chat/completions`
+- `/api/chat/openai/v1/embeddings`
+- `/api/chat/openai/v1/images/generations`
+- `/api/chat/openai/v1/models`
+- `/api/chat/openai/v1/models/[name]`
+- plus wrappers:
+  - `/api/v1/chat/completions`
+  - `/api/v1/models`
+
+### Security/tenancy/reliability controls found
+- Session auth checks on chat routes.
+- Tenant resolution via `resolveChatTenantContext(...)`.
+- Session ownership and tenant checks in message/session operations.
+- Rate limiting in primary chat flow (`enforceChatRateLimit`).
+- Input sanitization pattern in `ollama` route.
+- Attachment validation (count/type/size) in `ollama` route.
+
+### Notable implementation details
+- `src/lib/ollama.ts` centralizes client construction and config resolution (DB → env fallback).
+- OpenAI-compatible endpoints are implemented server-side with model translation.
+
+---
+
+## 5) Official Ollama Cloud/API Documentation Audit (Online)
+
+Sources fetched from docs.ollama.com included:
+- API overview (`/api`)
+- Authentication (`/api/authentication`)
+- chat/generate/embed/tags/show/ps/create/pull/push/copy/delete pages
+- OpenAI compatibility (`/openai`)
+- capabilities pages (tool-calling, structured outputs, web-search/fetch)
+
+### Confirmed endpoint families (official docs)
+- Native API patterns:
+  - `POST /api/chat`
+  - `POST /api/generate`
+  - `POST /api/embed`
+  - `GET /api/tags`
+  - `POST /api/show`
+  - model management endpoints for create/pull/push/copy/delete
+- OpenAI compatibility patterns:
+  - `/v1/chat/completions`
+  - `/v1/embeddings`
+  - `/v1/models` (and model details)
+- Cloud auth patterns documented with API key usage.
+
+### Practical finding from live app
+- Web-search helper route can return upstream `502` in current environment.
+- StormPilot now handles this gracefully with explicit fallback messaging and anti-hallucination instruction.
+
+---
+
+## 6) StormPilot UX Strategy (Business Owner Lens)
+
+Design principle: **Keep main chat simple and action-oriented; move tuning/config to dedicated settings page.**
+
+### Main interface goals
+- Fast operation prompts for store owners (sales snapshot, low stock, delayed orders, coupon performance)
+- Session continuity for recurring operational conversations
+- Attachment-first support for notes/docs/images
+- Clean streaming response UX with reasoning visibility
+
+### Separate settings goals
+- Keep advanced AI host/key/model setup in existing `/settings/ai`
+- Keep StormPilot interaction preferences in dedicated `/settings/stormpilot`
+
+### Responsive strategy
+- **Mobile**: single-column chat + slide-out sessions sheet
+- **Tablet**: compact single-column with prominent controls
+- **Desktop**: grid layout designed for session pane + chat pane behavior
+
+### UX flow artifact (FigJam)
+- [StormPilot UX Flow Diagram](https://www.figma.com/online-whiteboard/create-diagram/1c0df189-2bbe-466a-a88a-0383f0858ed7?utm_source=other&utm_content=edit_in_figjam&oai_id=&request_id=b8c9c899-8770-4744-bfb3-5e1494439539)
+
+---
+
+## 7) Implemented Changes
+
+### New files
+- `src/lib/stormpilot.ts`
+- `src/components/stormpilot/stormpilot-chat-app.tsx`
+- `src/components/stormpilot/stormpilot-preferences-form.tsx`
+- `src/app/stormpilot/page.tsx`
+- `src/app/settings/stormpilot/page.tsx`
+- `COMPREHENSIVE_API_INVENTORY_GENERATED.md`
+- `COMPREHENSIVE_STORMPILOT_OLLAMA_ANALYSIS_2026-03-19.md`
+
+### Updated files
+- `src/components/app-sidebar.tsx`
+  - Added nav items for StormPilot and StormPilot Settings
+- `middleware.ts`
+  - Added `/stormpilot` to protected paths
+
+### Behavior implemented in StormPilot
+- Session list + archive/delete operations
+- Message history loading and streaming response rendering
+- Attachment upload flow to `/api/chat/ollama`
+- Quick business-owner prompts
+- Model selector + capabilities badges
+- Web research mode (pre-fetch context via `/api/chat/websearch`)
+- Graceful fallback when websearch fails
+- Anti-hallucination prompt guard when live web context unavailable
+
+---
+
+## 8) Browser Validation Findings & Fixes
+
+### Validated flows
+- Login and route protection
+- StormPilot load + session persistence
+- Prompt send and response rendering
+- Settings save and effect on chat UI (web research toggle)
+- Attachment upload and analysis flow
+- Mobile session drawer behavior
+
+### Issues found and fixed during validation
+1. **Streaming race condition** on first-session message could hide assistant placeholder.
+   - **Fix**: prevent message reload during active send stream and improve scroll container handling.
+2. **Websearch upstream failures (502)** caused degraded experience.
+   - **Fix**: explicit status feedback + anti-hallucination fallback constraint in outbound prompt.
+
+---
+
+## 9) Remaining Recommended Enhancements
+
+1. **True source-cited web research mode**
+   - If `/api/chat/websearch` fails frequently, add retry/backoff and provider health diagnostics in UI.
+2. **Attachment content extraction transparency**
+   - Surface parsed snippets/metadata in UI so users know what model actually received.
+3. **Desktop pane verification in broader viewport contexts**
+   - Due tooling viewport constraints, complete final visual QA on full browser window with real monitor width.
+4. **Optional stop-generation control**
+   - Add AbortController cancel button for long-running streams.
+
+---
+
+## 10) Validation Status
+
+- Type-check: ✅
+- Build: ✅
+- Changed-file lint: ✅
+- Browser UX validation: ✅ (with issues found and fixed)
+