Telora Backend

A FastAPI backend for Telora - an innovative Shopify app that uses voice AI to collect customer feedback through automated phone calls.

Features

• Shopify OAuth Integration: Complete OAuth flow for Shopify app installation
• Webhook Handling: Processes Shopify webhooks for orders, customers, and app events
• Supabase Integration: PostgreSQL database with Supabase for data management
• Voice AI Ready: Infrastructure prepared for voice AI feedback collection

Quick Start

Prerequisites

• Python 3.9+
• Shopify Partner Account
• Supabase Account

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd telora-backend

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Environment Configuration

   cp env.example .env

   Update .env with your actual credentials (see Configuration section below).

5. Run the application

   uvicorn app.main:app --reload

The API will be available at http://localhost:8000

Configuration

Shopify App Setup

1. Create a new app in your Shopify Partner dashboard
2. Set App URL: https://your-domain.com
3. Set Redirect URL: https://your-domain.com/auth/shopify/callback
4. Configure scopes: read_products,read_orders,read_customers,write_orders

Supabase Setup

1. Create a new project in Supabase
2. Get your credentials from Settings > API
3. Database URL format: postgresql://postgres:[email protected]:5432/postgres

Environment Variables

Update your .env file with the following:

# Shopify Configuration
SHOPIFY_API_KEY=your_app_api_key
SHOPIFY_API_SECRET=your_app_secret_key
SHOPIFY_APP_URL=https://your-deployed-domain.com

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_anon_key
SUPABASE_SERVICE_KEY=your_service_role_key
DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres

# Security
SECRET_KEY=your_random_secret_key

API Endpoints

Authentication

• GET /auth/shopify/install?shop={shop_domain} - Generate Shopify install URL
• GET /auth/shopify/callback - Handle OAuth callback
• GET /auth/shopify/store/{shop_domain} - Get store information
• DELETE /auth/shopify/store/{shop_domain} - Uninstall store

Webhooks

• POST /webhooks/shopify/orders-create - New order webhook
• POST /webhooks/shopify/orders-updated - Order update webhook
• POST /webhooks/shopify/customers-create - New customer webhook
• POST /webhooks/shopify/app-uninstalled - App uninstall webhook

Health Check

• GET / - API root
• GET /health - Health check endpoint

Usage Example

Install the app on a Shopify store

curl "http://localhost:8000/auth/shopify/install?shop=example-store.myshopify.com"

This returns an installation URL that you can use to install the app on a Shopify store.

Database Schema

ShopifyStore Table

Column	Type	Description
id	Integer	Primary key
shop_domain	String	Store domain (unique)
shop_name	String	Store name
access_token	Text	OAuth access token
scope	String	Granted permissions
is_active	Boolean	Store status
created_at	DateTime	Creation timestamp
updated_at	DateTime	Last update timestamp
email	String	Store email
phone	String	Store phone
country	String	Store country
currency	String	Store currency
timezone	String	Store timezone

Deployment

Using Heroku

1. Create a new Heroku app
2. Set environment variables in Heroku dashboard
3. Deploy using Git or GitHub integration

Using Railway

1. Connect your GitHub repository
2. Set environment variables
3. Deploy automatically

Using Docker

FROM python:3.9

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Next Steps

This backend provides the foundation for your Shopify app. To complete the Telora app, you'll need to:

1. Implement Voice AI Service: Integrate with services like Twilio, OpenAI, or similar
2. Add Customer Models: Create database models for customer feedback data
3. Build Frontend: Create a React/Next.js frontend for the Shopify app interface
4. Add Analytics: Implement feedback analytics and reporting
5. Implement Calling Logic: Add the voice AI calling functionality

Development

Running Tests

pytest

Code Formatting

black app/
isort app/

Type Checking

mypy app/

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

[Add your license here]

Support

For questions and support, please create an issue or contact the development team.