PolicyJar

PolicyJar is a multi-tenant CRM, inbound call router, and browser softphone platform built with Next.js, Supabase, and Telnyx.

This repo contains:

• the web app and dashboard
• API routes for telephony, reporting, RTB, billing, and admin flows
• Supabase migrations
• automated tests and browser-based E2E labs

License And Name

The code in this repository is open source under Apache-2.0.

The PolicyJar name and branding are reserved separately. If you redistribute, host, rebrand, or commercialize a fork or derivative, you must use your own product name and branding unless you have written permission to use PolicyJar.

See TRADEMARKS.md for the naming rules.

What You Need

Before you start, make sure you have:

• Node.js 20+
• npm 10+
• a Supabase project
• a Telnyx account for voice features

Optional integrations:

• Stripe for billing flows
• Ringba for RTB flows
• Resend for invite emails

Quick Start

1. Install dependencies.

npm ci

2. Copy the example environment file.

Copy-Item .env.example .env.local

3. Open .env.local and replace the placeholder values with your own credentials.

4. Read docs/ENVIRONMENT.md for what each variable does.

5. Start the app.

npm run dev

6. Open http://localhost:3000.

Environment Setup

The canonical starter file is .env.example.

For local work:

• put real local credentials in .env.local
• use docs/ENVIRONMENT.md as the field-by-field reference
• leave optional QA and live-smoke values blank until you need them

Important files:

• .env.example: starter template for new users
• .env.local: local developer values
• .env.qa-check: optional live-environment smoke-test values

Do not commit .env.local, .env.qa-check, or any other credential-bearing file.

First Working Setup

The fastest path to a working local instance is:

1. Create a Supabase project and paste its URL, anon key, service-role key, and Postgres URL into .env.local.
2. Add your Telnyx API key, credential connection ID, Call Control app ID, webhook public key, and phone number.
3. Run the app with npm run dev.
4. If you need browser softphone behavior, also fill in the client-visible SIP fields in .env.local.

Useful Commands

npm test
npm run test:coverage
npm run test:e2e
npm run build
npm run test:go-live
npm run test:rtb:live

What they do:

• npm test: full Vitest suite
• npm run test:coverage: strict backend coverage gate
• npm run test:e2e: Playwright browser tests
• npm run build: production build verification
• npm run test:go-live: live-environment readiness smoke checks
• npm run test:rtb:live: live Ringba RTB smoke check

Project Layout

• src/app: Next.js routes and pages
• src/components: UI and telephony components
• src/hooks: client lifecycle hooks, including Telnyx and presence
• src/lib: shared business logic
• src/tests: Vitest suites
• e2e: Playwright tests
• supabase/migrations: schema history

Security Notes

• This repo includes .gitleaks.toml for secret scanning.
• CI runs a secret scan before tests.
• Rotate real credentials immediately if they were ever committed, even if you later rewrite history.
• Treat local bundles, old clones, forks, and stale branches as potentially sensitive until they are cleaned or deleted.

Contributing

A starter contributor guide lives in CONTRIBUTING.md.