Tero Voice - AI Receptionist SaaS Project

📋 Product Overview

Tero Voice - AI Answering Service for Service Businesses

A marketing website for an AI receptionist service that helps service businesses (plumbers, dentists, carpenters, electricians, contractors) handle customer calls 24/7. The AI answers questions, schedules appointments, qualifies leads, and prevents missed calls.

Key Value Propositions

• Never miss customer calls again
• 24/7 AI receptionist that sounds human
• Automatic appointment scheduling
• Lead qualification before callbacks
• Call analytics and transcripts
• Easy setup with no complex integrations

Target Audience

Service businesses with high call volumes:

• Plumbers, Dentists, Carpenters, Electricians, Contractors, Multi-location providers

Business Model

SaaS subscription with three tiers:

• Small Business: $49/month
• Growing Business: $129/month
• Enterprise: Custom pricing

⚠️ CRITICAL ARCHITECTURE NOTE

Divergence Alert: The previous agent (Kiro) attempted to redesign the backend inference and optimization layer (likely pushing HuggingFace/Powers). The User's implementation (IBM failover / scaling) is superior and should be preferred.

• Do NOT blindly follow Kiro's specs if they contradict the user's established IBM architecture.
• Do NOT replace existing robust scaling logic with Kiro's "Powers" unless explicitly asked.
• Goal: Restore/Preserve the IBM failover and optimization logic.

🛠️ Technology Stack

Frontend

• Framework: React 18.2.0
• Build Tool: Vite 4.4.5
• Styling: Tailwind CSS 3.3.3
• Routing: React Router DOM 6.14.0
• Icons: Lucide React 0.263.1
• Language: JavaScript (JSX)

Backend

• Framework: Flask (Python)
• Database: PostgreSQL on IONOS (74.208.227.161:5432)
• Auth: JWT tokens with bcrypt password hashing
• Containerization: Podman

Development Commands

npm install        # Install dependencies
npm run dev        # Start dev server
npm run build      # Production build
npm run lint       # Run ESLint

📁 Project Structure

ai_website/
├── src/
│   ├── components/
│   │   ├── common/     # Header, Footer, Card
│   │   └── ui/         # Modal, Dropdown
│   ├── pages/          # Home, About, Products, NotFound
│   ├── services/       # API client (api.js)
│   └── styles/         # global.css
├── backend-setup/      # Flask API
├── .kiro/              # Kiro specs & steering (preserved)
├── .agent/             # Antigravity config (this)
└── docker-compose.yml  # Container orchestration

Routes

• /

  - Home page (hero, features, pricing)

• /about

  - About page

• /products

  - Products page

• *

  - 404 page

📊 Current Status

✅ PHASE 1 COMPLETE

• Backend API with 16 endpoints (auth, clients, calls, analytics)
• PostgreSQL database configured (Models verified)
• Persistence Layer:

  BillingService

  and

  UsageService

  now use SQLAlchemy (removed mock data)
• JWT authentication and user isolation
• Podman containerization (Barebones Mini efficiency setup)
• Complete documentation

🏗️ ARCHITECTURE (Current State)

• Type: "Barebones Mini with Muscle" (Efficient VPS)
• Logic: Python/Flask API + Local Ollama + Redis + Postgres
• Integration: n8n + Neo4j + Pieces (Local Muscle - Code Pending Discovery)
• Status: Backend services optimized for persistence; waiting for IBM/n8n restoration logic.

🔄 PHASE 2 IN PROGRESS

• React frontend with Vite
• Tailwind CSS styling
• UI/UX: Multi-layer Parallax Wave Background (Fixed/Scrolling)
• API client with Axios (

  src/services/api.js

  )
• Environment configuration (

  .env.local

  )

📋 Active Specs (in

.kiro/specs/

)

• member-portal-billing/

  - Billing integration (4% complete)

• paypal-mcp-integration/

  - PayPal integration (COMPLETE)

• single-page-hero-design/

  - Hero design (COMPLETE)

🎯 Quality Guidelines

• Comment all code! Always comment your code!
• Always use the latest version of any library or framework
• never override the user's code unless explicitly asked
• never overwrite code in the project .old and .archive folders -common sense is the best sense
• code examples are in the examples folder at 420du/content/code-examples

Before Code Generation

• Review the project context
• Look at the current date and time
• Review the project status
• check dependencies
• Review requirements for security implications
• Review the requirements for the feature you - are about to implement
• Review the architecture for the feature you - are about to implement
• Inspect the code for the feature you - are about to implement
• Create a plan for the feature you are about to implement
• Make a to do list for the feature you are about to implement
• Identify potential vulnerabilities
• Plan for error handling
• Consider edge cases

During Code Generation

• Follow ESLint standards
• Include error handling
• Add input validation
• Include security checks

After Code Generation

• Run

  npm run lint

• Check for security issues
• Verify functionality

Security Checklist

• XSS prevention (sanitize input)
• CSRF protection
• SQL injection prevention (use ORM)
• No hardcoded credentials
• Proper error handling (no stack traces exposed)

🔗 Key Files

src/services/api.js

.env.local

.kiro/specs/*/tasks.md

.kiro/steering/quality-assurance.md

docker-compose.yml

🚀 Quick Reference

Database

• Host:

  74.208.227.161:5432

• Database:

  ai_receptionist

• User:

  user

API

• Local:

  http://localhost:8000

• Endpoints documented in backend-setup

When to Escalate

• Security vulnerability found
• Architecture redesign needed
• Complex debugging required
• Performance issues

📌 Remember

1. All

   .kiro/

   files are preserved for Kiro compatibility
2. Use

   .agent/workflows/

   for Antigravity commands
3. Specs in

   .kiro/specs/

   are still the source of truth
4. Follow quality assurance guidelines for all code