ACQ CRM Repo Overview

Repo Overview

Acquira CRM is the internal operating layer for contacts, outreach, pipeline, inbox, calls, campaigns, and team collaboration.

This page condenses the teammate-facing parts of the repo README into an interactive guide. Use it when someone needs to understand what the CRM is, what is live today, how the repo is structured, and where the Codex command surface fits into the system.

Go to Commands Go to Docs Map

Hosting

crm.acquira.coLive on Vercel with invite-only Google sign-in for approved @acquira.com users.

Primary Data Layer

Supabase + PrismaContacts, opportunities, activities, templates, tasks, and reporting state are stored in Postgres through Prisma.

Current Status

The current high-level system posture taken from the README and repo docs.

Area	Current Status
Hosting	Live on crm.acquira.co via Vercel.
Database	Supabase Postgres accessed through Prisma.
Email	Gmail for 1:1 email and Resend for campaign or bulk email.
SMS	Twilio for 1:1 SMS and marketing SMS.
Calls	Twilio Voice for browser dialer, inbound handling, recording, Gemini summaries, and final-result logging.
Lead sync	Airtable realtime webhook notification plus scheduled daily fallback sync.
Call recording storage	Google Shared Drive for retained recordings and full transcripts.

Core Workspaces

The main operator-facing surfaces inside the CRM app.

Workspace	Description
Dashboard	Contact and call reporting with daily snapshot refresh plus manual refresh.
Contacts	Contact search, ownership, activity timeline, tasks, messaging, and pipeline fields.
Pipeline	Stage-based list or kanban workflow with filters, confidence, and next steps.
Calls	Browser dialer, caller-ID picker by state, and final call log view across agents.
Inbox	Shared email inbox with contact matching and full email activity logging.
SMS	Full inbound and outbound SMS messages linked to contacts.
Campaigns	Campaign creation, editing, recipients, and send controls.
Settings	Sync monitoring, templates, Saved Links, Signatures, team management, and configuration.

Integrations

The main integrated services and what they do in the live CRM.

Integration	Use
Google OAuth	User authentication.
Gmail API	Mailbox sync and 1:1 email sending.
Twilio	SMS, inbound and outbound calls, tokens, and webhooks.
Resend	Campaign and bulk email delivery.
Airtable	Contact sync and webhook updates.
Supabase	Postgres database host.
Vercel	App hosting and preview or production deployments.
Google Shared Drive	Long-term storage for recorded-call audio and transcript files.
Gemini	Recorded-call transcript and summary generation.

Airtable Sync Monitoring

How the live CRM now handles Airtable lead ingestion and where teammates should look first when sync behavior seems off.

Item	Description
Realtime path	Airtable sends signed webhook notifications to `/api/sync/webhook`, which trigger overlap-based incremental CRM syncs using `LAST_MODIFIED_TIME()`.
Fallback path	`/api/sync/auto/cron` runs the scheduled daily fallback sync if realtime delivery is missed.
Monitoring UI	Open Settings → Sync in the CRM to review webhook health, last Airtable notification time, expiration timing, and recent realtime logs.
Warning banner	The Sync tab surfaces a prominent warning if the webhook lookup fails, the webhook expires within 48 hours, the webhook looks stale, or realtime sync is not configured.
Current scope	Realtime coverage is tuned for Airtable creates and updates. Delete reconciliation is still a follow-up item.

Operator habit

If something seems off with new lead arrival, start in Settings → Sync before running manual sync commands. That view now shows whether the webhook is healthy, stale, or approaching expiration.

Local Setup and Environment

These are the basics a teammate needs before running the repo or CLI locally.

Run locally

npm install
cp .env.local.example .env.local
npm run db:generate
npm run dev

Environment groups

Database: DATABASE_URL, DIRECT_URL
Auth: NEXTAUTH_URL, AUTH_SECRET
Google: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
Airtable, Twilio, Gemini, Gmail Push, Drive uploads, and cron secrets

Codex Command Surface

Use the repo-local CRM commands when you want Codex to operate on CRM data from the terminal without browser automation.

Command	Description
`npm run crm:help`	Show available CRM commands and examples.
`npm run crm:nl -- "find Andi Cunanan"`	Interpret a natural-language CRM request.
`npm run crm:contact -- --query "Name"`	Search contacts by name, email, phone, or company.
`npm run crm:email -- --contact-id <contactId> --from-user-email contact@acquira.com --body "..."`	Save a 1:1 email draft in the Codex session workflow.
`npm run crm:sms -- --contact-id <contactId> --message "..." --route CUSTOMER_CARE --user-email <agent@acquira.com>`	Save a compliance-safe SMS draft in the Codex session workflow.
`npm run crm:send-draft -- --draft-id <draftId> --confirm-send`	Send a previously saved email or SMS draft after approval from the Codex session workflow.
`npm run crm:report -- --range week --json`	Print a dashboard-style CRM summary.
`npm run crm:task-count -- --user-email nathan@acquira.com --status OPEN --json`	Count tasks for a CRM user by status.

Important note

The CRM app no longer exposes a Drafts tab or Drafts APIs. Teammate setup and sharing guidance for the Codex/CLI workflow is covered in the separate interactive CLI Onboarding page.

Documentation Map

The main share-ready docs and where they fit.

Document	Description
crm-ui-walkthrough.html	Interactive end-to-end user guide for the Acquira team.
crm-system-documentation.html	Interactive full-system guide for runtime, integrations, pricing, and workflows.
cli-onboarding.html	Interactive teammate onboarding for the repo-native CLI.
agent-onboarding.html	Interactive onboarding for Codex use in this repo.
change-management-protocol.html	Interactive change-control rules for keeping code, docs, and workflows aligned.