AI Platform

The AI chat experience in ignitionstack.pro is implemented on top of the src/app/lib/ai stack. It orchestrates OpenAI, Google Gemini, and self-hosted Ollama models through a Strategy Router, retrieval augmented generation (RAG), and Server-Sent Events (SSE) API routes. This page also documents the developer workflows stored under /AI/ (prompts, templates, tools) and the companion .cursor / .windsurf rulesets used when pairing with AI copilots.

Provider Matrix

Provider	Integration	Env vars	Notes
OpenAI	REST API via `openai` SDK	`OPENAI_API_KEY`	Default provider (`gpt-4o-mini`, `gpt-4-turbo-preview`).
Google Gemini	REST API via `@google/generative-ai`	`GOOGLE_AI_API_KEY`	Cost-effective creative/analysis tasks (`gemini-pro`).
Ollama	Local HTTP server	`OLLAMA_BASE_URL` (default `http://localhost:11434`)	Streams responses from self-hosted models (e.g., `llama2`, `llama3`).
Ollama Remote	Remote HTTP server	`OLLAMA_REMOTE_BASE_URL`, `OLLAMA_REMOTE_API_KEY`	Cloud-hosted Ollama with API key auth.

Place these keys in .env.local (and .env.production as needed):


# AI providers
OPENAI_API_KEY=sk-...
GOOGLE_AI_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-... # optional Claude support
OLLAMA_BASE_URL=http://localhost:11434
 
# Ollama Remote (cloud-hosted Ollama server)
OLLAMA_REMOTE_BASE_URL=https://ollama.yourcompany.com
OLLAMA_REMOTE_API_KEY=your-api-key-here
 
# Feature toggles
DEFAULT_AI_PROVIDER=openai
ENABLE_RAG=true
EMBEDDING_MODEL=text-embedding-3-small

Architecture Overview

Key Modules

Path	Responsibility
`src/app/api/ai/chat/route.ts`	Authenticates user, enforces rate limits, saves messages, streams SSE chunks.
`src/app/api/ai/upload/route.ts`	Accepts documents for RAG (Supabase Storage + embeddings).
`src/app/api/ai/share/route.ts`	Generates shareable conversation links.
`src/app/lib/ai/router/strategy-router.ts`	Chooses provider based on preference, task type, and provider health.
`src/app/lib/ai/factory/provider-factory.ts`	Builds provider adapters with API keys or `OLLAMA_BASE_URL`.
`src/app/lib/ai/circuit-breaker/breaker.ts`	Protects against cascading provider failures.
`src/app/lib/ai/rag/*`	RAG service, document processor, embeddings retrieval.
`src/app/lib/repositories/{conversation,message,document}-repository.ts`	Supabase persistence for chat records.

Request Lifecycle

Auth & Rate Limit – getUser() returns Supabase session; checkAPIRateLimit() throttles per user (20 chat requests/min).
Conversation Management – ConversationRepository.create() seeds metadata (provider/model/system prompt).
Message Persistence – MessageRepository stores user + assistant messages (including attachments) before streaming completes.
RAG – RAGService checks conversation flags, fetches embeddings (match_embeddings RPC), augments messages.
Routing – StrategyRouter picks the provider (e.g., code tasks → Claude, creative → OpenAI). ProviderFactory instantiates the adapter with API key or OLLAMA_BASE_URL.
Streaming – Provider-specific adapters produce tokens; route handler serializes them into SSE chunks.
Post-processing – ToolExecutor runs actions mid-stream; final assistant message is persisted and caches revalidated.

Local Development


# Start Next.js (includes /api routes)
npm run dev
 
# Optional: start Ollama locally and pull models
ollama serve
ollama pull llama2
ollama run llama2 "ping"

Gemini and OpenAI require valid API keys. Add them to .env.local and restart npm run dev so process.env updates.

Testing

Unit/Integration: src/app/test/unit/ai and src/app/test/integration/actions/* mock provider factories + repositories.
E2E: Playwright specs under src/app/test/e2e/tests/ai/*.spec.ts exercise /chat UI and SSE plumbing.
Manual: Send a cURL request to http://localhost:3000/api/ai/chat with Supabase cookies. For docs dev server, use http://localhost:3001/api/ai/chat.

Security & Guardrails

Rate limits – Chat (20/min), document upload (5/hour). Responses include Retry-After headers.
Moderation – moderateContent uses OpenAI moderation API for inbound/outbound text.
Circuit breaker – Trips after repeated provider failures and falls back to healthy providers.
RAG privacy – ai-documents bucket is per-user; embeddings reference user IDs enforced via Supabase RLS.

AI Developer Toolkit (`/AI` folder)

The repository includes /AI/ to streamline AI-assisted development:

Directory	Description
`AI/context/`	Project overviews, coding standards, architecture summaries to paste into ChatGPT/Claude.
`AI/prompts/`	Optimized prompts (feature dev, bug fix, code review, performance). Paste these into your AI tool of choice.
`AI/templates/`	Skeletons for components, API routes, server actions, tests. Combine with prompts for consistent output.
`AI/guidelines/`	Quality guardrails (performance, security, RLS, i18n). Review when requesting AI changes.
`AI/tools/`	Helper scripts (context builders, prompt chaining).
`AI/workflows/`	Step-by-step flows for debugging, deploying, or running tests with AI assistance.

Usage pattern:

Paste AI/context/project-overview.md into your AI tool.
Paste the relevant prompt (e.g., prompts/feature-development.md).
Reference templates (e.g., templates/server-action.md).
Cross-check against guidelines before applying suggestions.

Pair-programming Rulesets

.cursor/rules.md – Custom instructions for Cursor IDE agents (naming, repository pattern, logging rules). Load them via Cursor’s “Instructions” panel.
.windsurf/rules.md – Similar rules tuned for Windsurf AI. Ensure these files stay updated when architecture/patterns evolve.
AI README (/AI/README.md) – Quick start guide showing how to combine context + prompts for feature/bu fix/review tasks.

When onboarding new devs or configuring AI copilots (ChatGPT, Claude, Copilot, Cursor, Windsurf), point them to these rules so generated code matches the repo standards (ActionResult pattern, no direct Supabase in components, logging via createServiceLogger, etc.).

Keep this page updated whenever we add new providers, change routing logic, or evolve the AI workflows/templates so everyone (humans and AI agents) works off the same blueprint.