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:

{/* 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

• Real-time chat interface
• KIMI AI integration for pet care responses
• Emergency triage quick-action buttons
• Mobile-responsive design
• 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

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)

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)

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)

TENCENT_SECRET_ID=...
TENCENT_SECRET_KEY=...
TENCENT_BUCKET=your-bucket-125xxxxxx
TENCENT_REGION=ap-guangzhou
# TENCENT_ACCELERATE=true                   # Optional

Auth

JWT_SECRET=<64-char-random-string>

Build-time (Docker only)

STANDALONE=true   # Enables Next.js standalone output; omit for Vercel

Commands

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.

# 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