GitHub - Zeb88/prometheus-nps: A modern NPS feedback system with email integration, vector database storage, and AI-powered feedback analysis.

Prometheus NPS

A modern Net Promoter Score (NPS) feedback system with email integration, vector database storage, and AI-powered feedback analysis.

Features

🎯 NPS Feedback Collection: Easy-to-use form for collecting customer feedback and NPS scores
📊 Real-time Analytics: Live NPS score calculation and AI-generated feedback summaries
📧 Email Integration: Automated email notifications and personalized feedback form links
🔒 Secure Authentication: JWT-based authentication for form access
🤖 AI-Powered Analysis: OpenAI integration for feedback summarization and analysis
📦 Vector Database: Supabase integration for efficient feedback storage and retrieval
📈 Data Export: Export feedback data to CSV for further analysis
🛡️ Security Features: Rate limiting, input validation, and API key protection

Tech Stack

Backend: Node.js + Express
Frontend: Alpine.js + Tailwind CSS
Database: Supabase (PostgreSQL + Vector extensions)
AI: OpenAI API (GPT-3.5 + text-embedding-3-small)
Email: Resend (Production) / Mailpit (Development)
Security: Helmet, Express Validator, Rate Limiting

Prerequisites

Node.js (v14 or higher)
npm or yarn
Supabase account
OpenAI API key
Resend API key (for production)
Mailpit (for local development)

Setup

Clone the repository

git clone https://github.com/Zeb88/prometheus-nps.git
cd prometheus-nps

Install dependencies

Environment variables Create a .env file in the root directory:

PORT=3002
NODE_ENV=development
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
OPENAI_API_KEY=your_openai_api_key
RESEND_API_KEY=your_resend_api_key
JWT_SECRET=your_jwt_secret
ADMIN_API_KEY=your_admin_api_key

Database Setup Run the following SQL in your Supabase database:

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS moddatetime SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS vector SCHEMA extensions;

-- Create the feedback table with timestamp management and vector support
CREATE TABLE feedback (
  id uuid default uuid_generate_v4() primary key,
  inserted_at timestamptz DEFAULT timezone('utc'::text, now()) NOT NULL,
  updated_at timestamptz DEFAULT timezone('utc'::text, now()) NOT NULL,
  name text NOT NULL,
  email text NOT NULL,
  nps_score smallint NOT NULL,
  feedback text NOT NULL,
  embedding vector(768)
);

-- Create trigger for automatic updated_at timestamp
CREATE TRIGGER handle_updated_at
  BEFORE UPDATE ON feedback
  FOR EACH ROW
  EXECUTE PROCEDURE moddatetime(updated_at);

Start the development server

Usage

Collecting Feedback

Generate Form Link
- Access the admin interface
- Enter customer name and email
- Generate and send personalized feedback form link
Submit Feedback
- Customer receives email with unique form link
- Fills out NPS score (0-10) and feedback
- Submission stored in database with vector embedding

Analyzing Results

View Summary
- Access /summary endpoint
- View current NPS score
- Read AI-generated feedback summary
- Download complete feedback data as CSV

API Endpoints

POST /api/feedback - Submit feedback
GET /api/summary - Get NPS score and AI analysis
POST /api/generate-send-form-link - Generate and send personalized form link
POST /api/verify-token - Verify form access token
GET /api/download-csv - Download feedback data as CSV

Security

API endpoints protected with API key authentication
Rate limiting on form submissions and API requests
Input validation and sanitization
Secure headers with Helmet
JWT-based form access

Development

For local development:

Install Mailpit for email testing
Set NODE_ENV=development
Run npm run dev
Access Mailpit interface at http://localhost:8025

Production

For production deployment:

Set NODE_ENV=production
Configure Resend API key
Set secure JWT and Admin API keys
Run npm start

License

MIT License - see LICENSE file for details

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a new Pull Request

API Documentation

The API documentation is available through Swagger UI at /api-docs. This interactive documentation includes:

Detailed endpoint descriptions
Request/response schemas
Authentication requirements
Try-it-out functionality

Access the documentation at http://localhost:3002/api-docs when running locally.

Docker Setup

You can run the application using Docker and Docker Compose:

Build and start the containers
```
docker compose up --build
```
Access the services
- Application: http://localhost:3002
- Mailpit UI: http://localhost:8025
Stop the containers

Development with Docker

The application code is mounted as a volume, so changes will trigger automatic reload
Emails sent by the application can be viewed in Mailpit UI
Node modules are stored in a named volume for better performance

Production Deployment with Docker

Create a production Docker Compose file:

cp docker-compose.yml docker-compose.prod.yml

Modify the production configuration:

# docker-compose.prod.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3002:3002"
    environment:
      - NODE_ENV=production
      - PORT=3002
      # Add your production environment variables
    command: ["npm", "start"]

Deploy using production configuration:

docker compose -f docker-compose.prod.yml up -d

Project Structure

prometheus-nps/
├── public/
│   └── app.js
├── templates/
│   ├── layouts/
│   │   └── base.html
│   ├── partials/
│   │   ├── nav.html
│   │   └── footer.html
│   ├── index.html
│   ├── form.html
│   ├── summary.html
│   └── docs.html
├── .dockerignore
├── .env.example
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── package.json
├── README.md
└── server.js

Directory Overview

public/: Static assets and client-side JavaScript
- app.js: Main client-side application logic
templates/: HTML templates and components
- layouts/: Base template layouts
  - base.html: Main layout template with common structure
- partials/: Reusable template components
  - nav.html: Navigation bar component
  - footer.html: Footer component
- index.html: Marketing/landing page
- form.html: NPS feedback form
- summary.html: Feedback analysis dashboard
- docs.html: API documentation page
server.js: Main application server
docker-compose.yml: Docker Compose configuration
Dockerfile: Docker container configuration
.env.example: Example environment variables