Analytics platform that turns conversational AI interactions into actionable product insights without traditional UI tracking.

Quick Start • Features • Examples • Contributing

What is this?

ConvoMetrics is an analytics platform designed for founders and product teams building chat‑based AI products. It captures conversational interactions and turns them into measurable insights, eliminating the need for traditional UI‑based tracking tools.
Example usage:

$ ./init.sh
[INFO] Frontend dev server running on http://localhost:3000
[INFO] Backend API running on http://localhost:8000

Problem

Founders building chat-based AI products can't use traditional analytics tools like heatmaps or click funnels because there's no UI to track. They're flying blind trying to understand what users actually want from their conversational interfaces, making it impossible to iterate effectively on AI products.

Features

Feature	Description
Project Foundation	Sets up React + Vite frontend with Tailwind and Shadcn/ui, and FastAPI backend with CORS configured.
Database Setup	Defines SQLite/PostgreSQL schema, creates Pydantic models, and includes seed data for development.
API Endpoints	Implements RESTful CRUD endpoints with request validation, error handling, and OpenAPI documentation.
Frontend UI Components	Builds reusable, responsive components with loading/error states using Tailwind utility classes.
Frontend‑Backend Integration	Connects React UI to FastAPI via an API client, handling optimistic updates and network errors.

Quick Start

1. Clone the repository: git clone <repository-url>
2. Enter the project directory: cd ConvoMetrics
3. Install frontend dependencies: bun install
4. Install backend dependencies: uv sync
5. Copy the example environment file and add your API key: cp .env.example .env && edit .env
6. Start the application: ./init.sh

Examples

Health check
Verify the backend is reachable.

$ curl -s http://localhost:8000/api/health | jq
{
  "status": "ok",
  "timestamp": "2025-09-16T12:34:56Z"
}

Create a new conversation item
Add a mock interaction to the database.

$ curl -X POST http://localhost:8000/api/items \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user-123","title":"Pricing question","description":"User asked about subscription tiers","status":"new"}' | jq
{
  "id":"item-abc",
  "user_id":"user-123",
  "title":"Pricing question",
  "description":"User asked about subscription tiers",
  "status":"new",
  "created_at":"2025-09-16T12:34:56Z"
}

List all items for a user
Retrieve stored interactions.

$ curl -s http://localhost:8000/api/items?user_id=user-123 | jq '.[] | .title'
"Pricing question"
"Feature request"
"Bug report"

File Structure

ConvoMetrics/
  frontend/          # React Vite app with Tailwind & Shadcn/ui
    src/
      components/   # Reusable UI elements (buttons, modals, cards)
      pages/        # Route‑level components (Dashboard, ItemDetail)
      lib/          # API client, utils, and TypeScript types
      App.tsx
      main.tsx
    index.html
    package.json
    vite.config.ts
  backend/           # FastAPI server (Python 3.11+)
    main.py          # Application entry point and middleware setup
    routes.py        # REST endpoint definitions
    models.py        # Pydantic models for request/response validation
    database.py      # SQLAlchemy engine, session handling, and migrations
    requirements.txt # Python dependencies (uv lockfile optional)
  init.sh            # Starts both frontend (bun dev) and backend (uvicorn) servers
  README.md
  .env.example       # Template for environment variables

Tech Stack

Technology	Purpose
React 19	Frontend UI library
Vite	Frontend build tool & dev server
Tailwind CSS	Utility‑first styling
Shadcn/ui	Pre‑built accessible components
FastAPI	Backend API framework
Python 3.11+	Backend language
SQLite/PostgreSQL	Persistent storage
bun	Frontend package manager
uv	Backend package manager
Claude (Anthropic API)	Optional LLM-powered insights

Contributing

Fork the repo, create a feature branch, make your changes, ensure tests pass, and submit a pull request. Please follow the existing code style.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio