https://github.com/sequenzia/mamba-chat
https://github.com/sequenzia/mamba-chat
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/sequenzia/mamba-chat
- Owner: sequenzia
- Created: 2026-01-19T20:48:15.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-25T03:44:33.000Z (4 months ago)
- Last Synced: 2026-01-25T12:40:41.568Z (4 months ago)
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Mamba Chat
A modern, feature-rich AI chatbot application built with React and TypeScript. Mamba Chat provides a streaming chat interface with rich content blocks, offline-first persistence, and a pluggable architecture for AI backend integration. Currently configured to connect to a mamba-server backend.
---
## Overview
Mamba Chat is a modular Single-Page Application (SPA) that delivers a polished conversational AI experience. The architecture emphasizes clean separation of concerns through a service layer pattern for AI abstraction, repository pattern via custom hooks for data access, and context-based state management.
### Key Features
- **Streaming Chat Interface** - Real-time streaming responses with character-by-character display
- **Rich Content Blocks** - Interactive forms, charts, code snippets, and cards rendered from AI tool calls
- **Offline-First Persistence** - IndexedDB storage for conversations and messages via Dexie
- **Multi-Model Support** - Architecture supports switching between AI providers and models
- **Theme Support** - Dark/light mode with flash prevention
- **Responsive Design** - Mobile-first with adaptive layouts
- **Auto Title Generation** - Automatically generates conversation titles from context
---
## Tech Stack
| Category | Technologies |
|----------|--------------|
| Language | TypeScript 5.0 |
| Framework | React 18.3.1, Vite 6.0 |
| AI Integration | @ai-sdk/react, ai SDK |
| Database | Dexie 4.2.1 (IndexedDB) |
| UI Components | Radix UI, Material UI 7.3.5, shadcn/ui (49 components) |
| Styling | TailwindCSS 4.0, Emotion, class-variance-authority |
| Animation | motion 12.23.24 |
| Forms | React Hook Form 7.55.0, Zod 3.23.0 |
| Charts | Recharts 2.15.2 |
| Code Highlighting | Shiki 3.20.0 |
---
## Project Structure
```
mamba-chat/
├── src/
│ ├── components/ # React components
│ │ ├── ai-elements/ # AI SDK UI elements (10 files)
│ │ ├── blocks/ # Content block components (5 files)
│ │ ├── chat/ # Core chat components (5 files)
│ │ ├── layout/ # Layout components (Sidebar)
│ │ ├── providers/ # Context providers (ThemeProvider)
│ │ └── ui/ # shadcn/ui components (49 files)
│ ├── hooks/ # Custom React hooks (7 files)
│ ├── lib/ # Utility libraries
│ │ ├── ai/ # AI configs (models, prompts, tools)
│ │ ├── db/ # Dexie IndexedDB schema and types
│ │ ├── motion/ # Animation utilities
│ │ └── utils/ # General utilities
│ ├── pages/ # Page components
│ ├── services/ # Business logic services
│ │ └── chat/ # Chat service layer (mock/real/transport)
│ ├── styles/ # CSS files
│ ├── types/ # TypeScript type definitions
│ └── constants/ # Application constants
├── public/ # Static assets
└── internal/ # Internal documentation
```
---
## Getting Started
### Prerequisites
- Node.js 18+
- pnpm (recommended)
### Installation
1. Clone the repository:
```bash
git clone https://github.com/your-username/mamba-chat.git
cd mamba-chat
```
2. Install dependencies:
```bash
pnpm install
```
3. Create environment configuration:
```bash
cp .env.example .env.local
```
4. Start the development server:
```bash
pnpm dev
```
5. Open [http://localhost:5173](http://localhost:5173) in your browser.
---
## Configuration
Create a `.env.local` file from `.env.example` and configure the following variables:
| Variable | Description | Default |
|----------|-------------|---------|
| `VITE_USE_MOCK_CHAT` | Enable mock backend (set `false` for real backend) | `true` |
| `VITE_API_BASE_URL` | Backend API URL (when mock disabled) | `http://localhost:8000` |
| `VITE_MOCK_STREAM_DELAY_MS` | Character streaming delay in milliseconds | `25` |
| `VITE_AI_DEFAULT_MODEL` | Default AI model identifier | `openai/gpt-4o` |
| `VITE_AI_DEBUG_ON` | Enable debug logging | `false` |
**Backend Modes:**
- **Mock Mode** (`VITE_USE_MOCK_CHAT=true`): Uses simulated AI responses for development without a backend
- **Real Mode** (`VITE_USE_MOCK_CHAT=false`): Connects to mamba-server backend at the configured URL
---
## Available Scripts
| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server on port 5173 |
| `pnpm build` | Build for production |
| `pnpm preview` | Preview production build locally |
| `pnpm lint` | Run ESLint for code quality checks |
| `pnpm test` | Run tests with Vitest |
| `pnpm test:ui` | Run tests with Vitest UI |
---
## License
[MIT](LICENSE)