Inpetra - Project Overview

# Inpetra - Project Overview

## What We're Building

A 24/7 emergency chat assistant for **first-time pet parents**. Users can ask questions about their pets' health, nutrition, behavior, and get immediate guidance during stressful situations. The AI has a friendly, supportive persona - like a knowledgeable friend who happens to know a lot about pets.

## Tech Stack

- **Framework:** Next.js 16 (App Router)
- **Language:** TypeScript
- **UI Components:** shadcn/ui
- **Styling:** Tailwind CSS 4 with centralized design tokens
- **AI Backend:** Pluggable — any OpenAI-compatible API (env-driven)
- **State Management:** React hooks (useChat custom hook)

## Project Structure

```
src/
├── app/
│   ├── api/chat/           # KIMI AI chat endpoint
│   ├── globals.css         # Design tokens & theme
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Main chat page
├── components/
│   ├── chat/
│   │   ├── ChatContainer   # Main chat wrapper
│   │   ├── ChatMessage     # Message bubble (memoized)
│   │   ├── ChatInput       # Message input
│   │   └── EmergencyPrompts# Quick-action buttons
│   ├── layout/
│   │   └── Header          # App header
│   └── ui/                 # shadcn components
├── hooks/
│   ├── useChat.ts          # Chat state management
│   ├── useAutoScroll.ts    # ChatGPT-style anchor-to-top scrolling
│   └── useKeyboardHeight.ts # Mobile keyboard detection (visualViewport)
├── lib/
│   ├── utils.ts            # Utility functions
│   └── prompts.ts          # AI persona & emergency prompts
├── services/
│   ├── ai.ts               # Pluggable AI provider service
│   └── zilliz.ts           # Vector search for product recommendations
└── types/
    └── index.ts            # TypeScript interfaces
```

## Design System

Using shadcn/ui with custom pet-care themed design tokens:
- **Primary (Teal):** Calm, medical trust
- **Accent (Coral):** Friendly, inviting
- **Destructive (Red):** Emergency alerts

Design tokens are centralized in `globals.css` using CSS variables.

### Floating UI Pattern

We use a **Floating UI** (chromeless) design for fixed elements:

```jsx
{/* Container: invisible, only for positioning */}
<div className="fixed left-0 right-0 z-20 pb-safe">
  {/* Component: the only visible element */}
  <ChatInput />
</div>
```

**Principles:**
- Containers have **no visual presence** (no background, border, padding)
- Only the actual UI component (pill-shaped input, header bar) is visible
- Elements appear to "float" on the canvas independently
- Use `pb-safe` / `pt-safe` for iOS safe areas on fixed elements

This applies to:
- Header (fixed top, pill-shaped bar)
- Chat input (fixed bottom, pill-shaped input)
- Any floating action elements

## Key Features

- [x] Real-time chat interface
- [x] KIMI AI integration for pet care responses
- [x] Emergency triage quick-action buttons
- [x] Mobile-responsive design
- [x] Friendly, supportive AI persona
- [ ] Chat history persistence
- [ ] Dark mode support

## Environment Variables

See `.env.tencent.local.example` for a complete ready-to-fill template.

### AI Chat Provider
```bash
AI_BASE_URL=https://openrouter.ai/api/v1   # Any OpenAI-compatible endpoint
AI_API_KEY=sk-or-v1-...                     # API key
AI_MODEL=moonshotai/kimi-k2-0905            # Chat model
AI_VISION_MODEL=moonshotai/kimi-k2.5        # Vision model
# AI_TEMPERATURE=0.7                        # Optional
# AI_SUPPORTS_VISION=true                   # Optional, default true
# AI_USE_MAX_COMPLETION_TOKENS=false         # Optional
```

### Embedding / Zilliz (product vector search)
```bash
ZILLIZ_ENDPOINT=https://...zillizcloud.com
ZILLIZ_API_KEY=...
# EMBEDDING_API_KEY=                        # Optional, falls back to AI_API_KEY
# EMBEDDING_BASE_URL=https://openrouter.ai/api/v1  # Optional
# EMBEDDING_MODEL=qwen/qwen3-embedding-8b          # Optional
```

### Database (provider-dependent)
```bash
CLOUD_PROVIDER=tencent                      # or "vercel" (default)

# Tencent path:
TENCENT_PG_HOST=...
TENCENT_PG_PORT=5432
TENCENT_PG_USER=...
TENCENT_PG_PASSWORD=...
TENCENT_PG_DATABASE=postgres

# Vercel path:
POSTGRES_URL=postgresql://...
```

### Tencent COS (image storage on Tencent Cloud)
```bash
TENCENT_SECRET_ID=...
TENCENT_SECRET_KEY=...
TENCENT_BUCKET=your-bucket-125xxxxxx
TENCENT_REGION=ap-guangzhou
# TENCENT_ACCELERATE=true                   # Optional
```

### Auth
```bash
JWT_SECRET=<64-char-random-string>
```

### Build-time (Docker only)
```bash
STANDALONE=true   # Enables Next.js standalone output; omit for Vercel
```

## Commands

```bash
npm run dev    # Start development server
npm run build  # Production build
npm run start  # Start production server
npm run lint   # Run ESLint
```

## Tencent Cloud Deployment (Docker)

The Docker tar contains two images: the main app (Next.js + nginx + SSL)
and Dozzle (Docker log viewer). Both are loaded from a single tar file.

```bash
# Build locally (requires .env.tencent.local + cert/ to be present)
docker build -t inpetra-chat:latest .

# Export both images as a single portable tar
docker pull amir20/dozzle:latest
docker save inpetra-chat:latest amir20/dozzle:latest | gzip > inpetra-chat.tar.gz

# Transfer to Lighthouse
scp inpetra-chat.tar.gz root@<lighthouse-ip>:~/

# On Lighthouse — load both images from the tar
docker load < inpetra-chat.tar.gz

# Run the main app
docker run -d --restart unless-stopped --name inpetra-chat \
  -p 80:80 -p 443:443 \
  inpetra-chat:latest

# Run Dozzle agent (Docker log viewer on port 7007)
docker run -d --restart unless-stopped --name dozzle \
  -p 7007:7007 -e DOZZLE_HOSTNAME=Inpetra-Chat \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  amir20/dozzle:latest agent
```

The `-v /var/run/docker.sock` mount is only needed for the Dozzle container.
The main app image is fully self-contained with no volume mounts required.

## Best Practices

Follow the Vercel React best practices in `.agents/skills/vercel-react-best-practices/`:
- Eliminate request waterfalls
- Optimize bundle size with dynamic imports
- Memoize expensive components
- Use proper loading states