Setup & Installation Guide

Before configuring any environment variables, create a free account at each service below. You will collect API keys and credentials during each account's setup — keep a notepad open to store them as you go.

Supabase provides the PostgreSQL database that stores all leads, organizations, and settings. You need two separate connection strings — one for runtime queries and one for running migrations.

1. 1Go to supabase.com → click 'New project'. Give it a name (e.g. servin-tech), choose the region closest to your users, and set a strong database password. Save this password — you will need it in the connection strings.
2. 2Wait for the project to finish provisioning (about 30 seconds), then open Settings → Database in the left sidebar.
3. 3Scroll to 'Connection string'. Select the URI tab. Switch mode to Transaction — copy the full string. Replace [YOUR-PASSWORD] with your database password. This is your DATABASE_URL.

   postgresql://postgres.xxxx:[PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres

4. 4Switch mode to Session — copy this string as well and replace [YOUR-PASSWORD]. This is your DIRECT_URL (used for migrations only).

   postgresql://postgres.xxxx:[PASSWORD]@aws-0-us-east-1.pooler.supabase.com:5432/postgres

5. 5Go to Settings → API. Copy the 'Project URL' → this is SUPABASE_URL. Copy the 'anon public' key → this is SUPABASE_ANON_KEY.
   💡

   Never use the service_role key in the browser — it bypasses all row-level security.

6. 6After setting all environment variables and deploying, run the database migration to create all tables:

   pnpm db:migrate:deploy

Clerk handles user sign-up, sign-in, and organization (business account) management. Each contractor signs up and gets their own isolated organization.

1. 1Go to clerk.com → Create application. Name it (e.g. Servin Tech AI Solutions). Under 'How will your users sign in?' enable Email address and Google. Click Create application.
2. 2In the left sidebar go to Configure → Organizations. Toggle Organizations ON. This enables multi-tenant business accounts.
   💡

   Organizations is required — the entire app is built around Clerk orgs. Do not skip this.

3. 3Go to API Keys. Copy the Publishable key → NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY. Copy the Secret key → CLERK_SECRET_KEY.
4. 4Go to Webhooks → Add Endpoint. Set the URL to your production domain:

   https://servintechsolutions.com/api/webhooks/clerk

5. 5Under 'Subscribe to events' select: user.created, organization.created, organizationMembership.created, organizationMembership.deleted. Click Create.
6. 6On the webhook detail page click 'Signing Secret' → copy the value → CLERK_WEBHOOK_SECRET.
   ⚠️

   If this secret is wrong, all Clerk webhooks will be rejected with 400 errors and new accounts won't be provisioned in your database.

Twilio provides the phone numbers that customers call and text. Individual numbers are provisioned automatically per contractor during their onboarding — you do not need to buy numbers manually.

1. 1Go to console.twilio.com → create a free account. Verify your email and phone number.
2. 2On the Console Dashboard, find your Account SID and Auth Token (click the eye icon to reveal). Copy them:

   TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_AUTH_TOKEN=your_auth_token_here

3. 3For testing: go to Develop → Testing → Test Credentials. Copy the test Account SID and test Auth Token → TWILIO_TEST_ACCOUNT_SID and TWILIO_TEST_AUTH_TOKEN.
   💡

   Test credentials let you simulate calls and texts without being charged. Real credentials are used in production.

4. 4After deploying, go to Phone Numbers → Manage → Active Numbers → click your AI number. Set the voice webhook to:

   https://servintechsolutions.com/api/webhooks/twilio/voice

5. 5Set the SMS webhook to:

   https://servintechsolutions.com/api/webhooks/twilio/sms

6. 6Both webhook methods should be HTTP POST. Click Save configuration.
   ⚠️

   Twilio validates a signature on every webhook. If TWILIO_AUTH_TOKEN doesn't match, all calls and texts will be rejected with 401.

OpenAI powers the bilingual AI receptionist. Voice calls use the GPT-4o Realtime API. Text (SMS) conversations use GPT-4o and GPT-4o-mini.

1. 1Go to platform.openai.com → sign in → click your profile (top right) → API Keys → Create new secret key. Name it (e.g. servin-tech-prod) and copy immediately — it is only shown once.

   OPENAI_API_KEY=sk-proj-...

2. 2Verify your API tier. Go to Settings → Limits. Voice calls require gpt-4o-realtime-preview, which needs Tier 1 or higher.
   💡

   Tier 1 is reached after $5 in API spend and a 7-day account age. If your account is brand new, add $5 in credit first.

3. 3Go to Settings → Billing → Add payment method to ensure your account stays active. Without billing set up, API calls will fail once the free credit expires.
4. 4Optionally set a monthly spending limit under Settings → Limits → Set monthly budget to prevent unexpected charges.

Stripe handles all subscription billing. Contractors pay monthly via Stripe Checkout. The app supports three plans: Starter ($149), Professional ($299), and Agency ($499).

1. 1Go to dashboard.stripe.com → Developers → API keys. Copy the Publishable key and Secret key. Use test keys during setup and live keys for production:

   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
   STRIPE_SECRET_KEY=sk_live_...

2. 2Go to Product catalog → + Add product. Create three products with recurring monthly pricing:
3. 3Product 1: Name = Starter, Price = $149.00 USD, Billing = Recurring, Interval = Monthly. Save and copy the Price ID (starts with price_) → STRIPE_PRICE_STARTER.
4. 4Product 2: Name = Professional, Price = $299.00 USD. Copy Price ID → STRIPE_PRICE_PROFESSIONAL.
5. 5Product 3: Name = Agency, Price = $499.00 USD. Copy Price ID → STRIPE_PRICE_AGENCY.

   STRIPE_PRICE_STARTER=price_...
   STRIPE_PRICE_PROFESSIONAL=price_...
   STRIPE_PRICE_AGENCY=price_...

6. 6Go to Developers → Webhooks → + Add endpoint. Set the URL to:

   https://servintechsolutions.com/api/webhooks/stripe

7. 7Select events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted. Click Add endpoint. Copy the Signing secret → STRIPE_WEBHOOK_SECRET.
   ⚠️

   Make sure to add the webhook in the same mode (test or live) as your API keys. A live webhook secret won't work with test keys.

Resend sends instant email alerts to the owner and dispatcher whenever a new lead comes in, plus any other transactional emails.

1. 1Go to resend.com → sign up → API Keys → + Create API Key. Name it (e.g. servin-tech), set permission to Full access, click Add. Copy the key immediately:

   RESEND_API_KEY=re_...

2. 2Go to Domains → + Add Domain. Enter your sending domain (e.g. servintechsolutions.com). Resend will give you 3 DNS records to add in Google Domains (MX, TXT for SPF, TXT for DKIM).
3. 3Add those DNS records in Google Domains → DNS → Manage custom records. Once added, click Verify in Resend. Verification can take 5–30 minutes.
4. 4Once verified, set your from address:

   RESEND_FROM_EMAIL=support@servintechsolutions.com

5. 💡

   Until your domain is verified, emails will be sent from onboarding@resend.dev — fine for testing, but not suitable for production.

Inngest runs background tasks triggered by events: sending lead notification emails, running follow-up sequences, and generating monthly reports.

1. 1Go to app.inngest.com → sign up → create a new app named servin-tech.
2. 2Go to Manage → Event Keys → + Create event key. Name it and copy the value:

   INNGEST_EVENT_KEY=...

3. 3Go to Manage → Signing Keys → copy the signing key:

   INNGEST_SIGNING_KEY=signkey-prod-...

4. 4After deploying to Vercel, register your serve endpoint so Inngest can discover your functions. Go to your Inngest dashboard → Apps → + Sync app and enter:

   https://servintechsolutions.com/api/webhooks/inngest

5. 💡

   Inngest will automatically re-sync functions on each Vercel deployment if you configure the integration in the Vercel marketplace.

The voice server is a separate Node.js WebSocket service that handles real-time audio streaming between Twilio and the OpenAI Realtime API. It must be deployed separately from the Next.js app.

1. 1Install the Railway CLI globally:

   npm install -g @railway/cli

2. 2Log in to Railway from your terminal:

   railway login

3. 3From inside the voice-server folder, initialize and deploy:

   cd voice-server
   railway init
   railway up

4. 4Set the required environment variables on Railway:

   OPENAI_API_KEY=sk-proj-...
   INTERNAL_API_SECRET=<run: openssl rand -hex 32>
   NEXT_APP_URL=https://servintechsolutions.com

5. 5After deploy, Railway assigns a public URL. Copy it and set it on Vercel:

   VOICE_SERVER_URL=wss://your-service.up.railway.app

6. 6Verify the voice server is healthy:

   curl https://your-service.up.railway.app/health
   # Expected: {"status":"ok","service":"servin-tech-voice"}

   💡

   Railway automatically redeploys when you push to the connected GitHub branch.

Vercel hosts the Next.js web app — the customer-facing marketing site, the contractor dashboard, and all API routes.

1. 1Push your code to GitHub. Go to vercel.com → Add New Project → Import your GitHub repository.
2. 2In the project settings → Environment Variables, add all variables from .env.example. Required variables:

   DATABASE_URL
   DIRECT_URL
   SUPABASE_URL
   SUPABASE_ANON_KEY
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
   CLERK_SECRET_KEY
   CLERK_WEBHOOK_SECRET
   TWILIO_ACCOUNT_SID
   TWILIO_AUTH_TOKEN
   OPENAI_API_KEY
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
   STRIPE_SECRET_KEY
   STRIPE_PRICE_STARTER
   STRIPE_PRICE_PROFESSIONAL
   STRIPE_PRICE_AGENCY
   STRIPE_WEBHOOK_SECRET
   RESEND_API_KEY
   RESEND_FROM_EMAIL
   INNGEST_EVENT_KEY
   INNGEST_SIGNING_KEY
   INTERNAL_API_SECRET
   VOICE_SERVER_URL
   NEXT_PUBLIC_APP_URL

3. 3Click Deploy. Vercel will run pnpm install → prisma generate → next build automatically.
4. 4Once deployed, set your custom domain: Vercel → Settings → Domains → add servintechsolutions.com.
   💡

   Add an A record in Google Domains pointing @ to 76.76.21.21 to connect your domain to Vercel.

5. 5After the domain is live, update Clerk, Twilio, Stripe, and Inngest webhooks to use https://servintechsolutions.com (not the vercel.app URL).

With all services connected and deployed, do a full end-to-end test before sending real customers to the platform.

1. 1Sign up at servintechsolutions.com. Complete the 5-step onboarding: business name, AI greeting, phone number, notifications, test mode.
2. 2Go to /test in your dashboard. Send a simulated SMS conversation. Verify the lead appears with correct qualification data (job type, urgency, address).
3. 3Call your provisioned AI phone number from your real phone. The AI should answer, greet you in the correct language, and walk through the qualification questions.
4. 4Check the lead dashboard — the call should appear as a new lead with a full transcript and summary within seconds of hanging up.
5. 5Verify you receive the email notification at the owner's email address.
6. 6In /test, toggle Test Mode OFF. Your AI receptionist is now live and accepting real calls and texts.
   ⚠️

   Make sure Test Mode is OFF before directing real customers to the number. Test leads are flagged and isolated from your real pipeline.