# ChatCraft AI - Full Technical & System Specification

> Complete reference manual for ChatCraft AI: architecture, retrieval-augmented generation (RAG) vector pipelines, embedding integration, authentication, and REST API endpoints.

## 1. System Architecture Overview

ChatCraft AI operates as a unified RAG chatbot construction platform consisting of:
- **Client Application:** React + Vite Single Page Application incorporating real-time visual customizer and responsive live preview.
- **Backend API:** Node.js Express server managing document ingestion, semantic chunking, embedding generation, vector similarity matching, and LLM orchestration.
- **LLM Engine:** Multi-provider interface supporting Google Gemini Pro and OpenAI GPT models with prompt safety guardrails and system persona injection.
- **Universal Embed Widget:** Standalone zero-dependency vanilla JavaScript runtime (`widget.js`) embeddable on any web host.

## 2. Document Ingestion & RAG Vector Pipeline

ChatCraft ingests multi-format documentation to build isolated, bot-specific vector knowledge bases:
- **Supported Formats:**
  - PDF (`application/pdf` via `pdf-parse`)
  - Microsoft Word (`.docx` via `mammoth`)
  - Plain Text (`.txt`, `.md`, `.json`)
  - Direct Web Crawling (automated HTTP scraping, HTML sanitization, and text extraction)
- **Chunking Algorithm:** Recursive character splitting with dynamic token overlapping (500 tokens per chunk with 50-token semantic overlap) to prevent context fragmentation at sentence boundaries.
- **Vector Search:** Cosine similarity calculation over normalized dense vector embeddings to retrieve top-k (default k=4) most relevant knowledge chunks per user query.

## 3. Universal Embed Integration

To deploy ChatCraft on any website, CMS, or application, add the following script snippet immediately before the closing `</body>` tag:

```html
<!-- ChatCraft Universal AI Chatbot Embed -->
<script 
  src="https://chatcraftstdo.com/widget.js" 
  data-bot-id="YOUR_BOT_ID" 
  async
></script>
```

### CMS Quick Guides
- **WordPress:** Insert into `footer.php` or use a "Headers and Footers" plugin.
- **Shopify:** Navigate to `Online Store > Themes > Edit Code > theme.liquid` and paste before `</body>`.
- **Webflow / Framer:** Paste into the custom footer code section in Site Settings.
- **React / Next.js:** Place in `index.html` or load dynamically via `useEffect`.

## 4. REST API Reference

All protected endpoints require an `Authorization: Bearer <TOKEN>` header.

### Authentication
- `POST /api/auth/register` - Create user account (returns JWT).
- `POST /api/auth/login` - Authenticate existing user.
- `GET /api/auth/me` - Validate session and retrieve user profile.

### Bot Management
- `GET /api/bots` - List all bots belonging to the authenticated user.
- `POST /api/bots` - Create a new chatbot instance.
- `GET /api/bots/:id` - Retrieve full configuration (theme, identity, prompts, knowledge).
- `PUT /api/bots/:id` - Update styling and prompt parameters.
- `DELETE /api/bots/:id` - Permanently remove bot and associated vector memory.

### Knowledge Ingestion
- `POST /api/bots/:id/knowledge/upload` - Upload PDF/DOCX/TXT file for ingestion.
- `POST /api/bots/:id/knowledge/crawl` - Ingest web URL contents.
- `DELETE /api/bots/:id/knowledge/:docId` - Remove specific document from vector store.

### Chat & Messaging
- `POST /api/chat/:id` - Public messaging endpoint used by embed widget and test runner. Accepts `{ message, history }` and returns `{ answer, sources }`.

## 5. Subscription & Resource Limits

| Feature | Starter Plan | Pro Plan | Agency Plan |
| :--- | :---: | :---: | :---: |
| Monthly Price | $0 / mo | $29 / mo | $99 / mo |
| Active Chatbots | 1 Bot | 5 Bots | Unlimited |
| Message Volume | 500 msgs / mo | 10,000 msgs / mo | 100,000 msgs / mo |
| Document Storage | 5 MB | 100 MB | 1 GB |
| ChatCraft Branding | Displayed | Removable | 100% White-Label |
| Support | Community / Email | Priority Email | Dedicated Slack Channel |

## 6. Security, Compliance & Data Isolation

- **Tenant Isolation:** Bot vector stores and message histories are strictly isolated per user identifier.
- **Data Privacy:** Customer documents and chats are used exclusively for real-time RAG context retrieval and are never submitted to public model training corpora.
- **Transport Security:** Strict HTTPS / TLS 1.3 encryption across all API and widget communications.
- **Support Contact:** support@chatcraftstdo.com
- **Official Domain:** https://chatcraftstdo.com