# TealSub

> AI chatbots trained on your content.

This document provides high-level context for AI coding assistants, LLMs, and automated agents working with the TealSub codebase. It focuses on product architecture, repository organization, and the core concepts required to understand the project.

For complete documentation, implementation details, APIs, pricing, and FAQs, see: https://tealsub.com/llms-full.txt

---

# Product

TealSub is a SaaS platform that enables businesses to create AI-powered chatbots trained exclusively on their own knowledge.

Instead of relying on general internet knowledge, every chatbot retrieves answers from content provided by the workspace, producing grounded and source-aware responses.

The platform is designed for fast deployment through an embeddable JavaScript widget that can be added to any website.

---

# Primary Use Cases

TealSub is commonly used for:
- Customer support
- Product documentation
- Internal knowledge bases
- Help centers
- Developer documentation
- AI website assistants

---

# Target Users

- SaaS companies
- Startups
- Product teams
- Customer success teams
- Support teams
- Documentation teams
- Businesses with large knowledge bases

---

# Core Product Concepts

## Workspace
The top-level tenant. A workspace owns:
- Bots
- Members
- Billing
- Subscription
- Usage
- Sources

Most permissions and limits are enforced at the workspace level.

## Bot
A chatbot deployed by a workspace. A bot has:
- Knowledge sources
- Widget configuration
- Appearance settings
- Retrieval configuration
- Public embed endpoint

Bots answer questions using only indexed workspace content.

## Source
Content used to train a bot. Supported sources include:
- PDF
- Markdown
- Plain text
- Websites
- Individual URLs
- XML sitemaps

Sources are processed asynchronously before becoming searchable.

## Widget
A lightweight JavaScript embed that allows visitors to chat with a bot from any website. Widget customization includes:
- Theme
- Colors
- Branding
- Position
- Behavior

## Plans
Subscription plans determine:
- Usage limits
- Feature availability
- Workspace quotas
- Team capabilities

---

# High-Level Architecture

The product follows a simple pipeline:
Knowledge Sources -> Content Ingestion -> Chunking -> Embeddings -> Vector Storage -> Semantic Retrieval -> LLM Response -> Embeddable Chat Widget

The primary objective is grounded retrieval rather than general-purpose chat.

---

# Repository Structure

- `app/`: Next.js App Router pages, server actions, and API routes.
- `components/`: Dashboard, widget customization, pricing pages, marketing pages, and reusable UI.
- `db/`: Database schema, models, and persistence.
- `lib/`: Core application logic including retrieval, embeddings, chat runtime, utilities, and business logic.
- `trigger/`: Background jobs responsible for content ingestion, processing, indexing, and synchronization (Trigger.dev).
- `public/`: Static assets and AI-readable metadata files.
- `config/`: Pricing, plans, feature flags, and site configuration.

---

# Public Marketing Pages

- Home: https://tealsub.com/
- Pricing: https://tealsub.com/pricing
- Features: https://tealsub.com/features
- How It Works: https://tealsub.com/how-it-works
- About: https://tealsub.com/about
- Changelog: https://tealsub.com/changelog
- Blog: https://tealsub.com/blog

---

# Typical User Journey

1. Create a workspace
2. Create a chatbot
3. Connect knowledge sources
4. Process and index content
5. Customize the widget
6. Embed the widget
7. Visitors ask questions
8. The bot retrieves relevant content and generates grounded answers

---

# Design Principles

When modifying this repository, prioritize:
- Grounded responses over hallucinations
- Fast retrieval
- Simple onboarding
- Lightweight widget performance
- Secure workspace isolation
- Predictable subscription behavior
- Reliable content ingestion
- Good developer experience

---

# Important Areas

If you're making product changes, these directories are usually the best starting points:
- `app/`
- `components/`
- `lib/`
- `trigger/`
- `db/schema.ts`

---

# AI Guidance

When assisting with this repository:
- Preserve retrieval quality.
- Preserve workspace isolation.
- Preserve billing and usage enforcement.
- Avoid changes that break widget compatibility.
- Treat ingestion and indexing as critical product functionality.
- Prefer simple, maintainable solutions over unnecessary abstraction.

This repository represents a production SaaS platform focused on grounded AI chatbots rather than a general-purpose LLM framework.