# Buddy CRM — Start Here

If you're reading this, you probably need to understand, maintain, or fix Buddy CRM. This page tells you what the platform is, how to access it, and where to go next.

---

## What is Buddy CRM?

Buddy CRM is Now NZ's standalone Sales CRM, extracted from the internal Buddy platform. It provides AI-powered lead research, lead management, opportunity tracking, quoting, email & calendar integration with Outlook, audience sync with Mailchimp, reporting, and admin dashboards — all behind Microsoft SSO.

**Production URL:** see `ALLOWED_ORIGINS` in the Buddy CRM Netlify site env vars (the deployed URL is intentionally not committed to source).
**GitHub:** [github.com/nownz-marc/buddy-crm](https://github.com/nownz-marc/buddy-crm) (private, `main` auto-deploys).

> The single source of truth for what's shipped, what's open, and what's parked is **`docs/handover-2026-05-06.md`**. Read that before you do anything substantial.

---

## Source Code Backups

The codebase is on GitHub (private). The original Buddy platform is also backed up weekly to SharePoint — that backup includes Buddy CRM as a sibling project:

**[Buddy — SharePoint Backup](https://nownz.sharepoint.com/:f:/s/Tools/IgCJmDrcuGh5Q4cFoyy7dnVEAdL2H95BDPF2Pi-xFQjCyrM?e=CpyqwP)**

The very latest version lives on the developer's local machine and on GitHub.

---

## Key Platforms

### 1. Netlify — Hosting & Serverless Functions

| | |
|---|---|
| **What it does for Buddy CRM** | Hosts all HTML pages and runs the Netlify Functions that power the backend. Stores all environment variables (API keys, secrets). Auto-deploys from `main` branch on GitHub push. |
| **Login URL** | https://app.netlify.com |
| **Credentials** | Please contact Marketing for details about Account Access and Passwords sheet |
| **When you'd need it** | Rolling back a bad deploy, checking function logs, updating an API key, redeploying |
| **Status page** | https://www.netlifystatus.com/ |

### 2. Supabase — Database

| | |
|---|---|
| **What it does for Buddy CRM** | Stores all CRM data — leads, opportunities, quotes, salespeople, pricebook, feature flags, email/meeting history, etc. The Supabase project is **shared** with the original Buddy app. |
| **Login URL** | https://supabase.com/dashboard |
| **Credentials** | Please contact Marketing for details about Account Access and Passwords sheet |
| **When you'd need it** | Toggling a feature flag off in an emergency, checking data, applying a SQL migration, restarting the project if it's paused |
| **Status page** | https://status.supabase.com/ |

### 3. Microsoft Azure (Entra ID) — Authentication / SSO

| | |
|---|---|
| **What it does for Buddy CRM** | Handles all user authentication (Microsoft work account SSO) and provides Microsoft Graph API access for the Outlook email + calendar integrations. |
| **Login URL** | https://portal.azure.com |
| **Credentials** | Please see Max or the Platform team |
| **When you'd need it** | If SSO breaks, if redirect URLs need updating after a domain change, or if Outlook OAuth scopes need to change (e.g. upgrading `Calendars.Read` → `Calendars.ReadWrite`) |
| **Status page** | https://status.office.com/ |

### 4. Google Cloud — AI (Gemini API)

| | |
|---|---|
| **What it does for Buddy CRM** | Powers Sales Buddy lead research and the photo→lead OCR via Gemini 2.5 Flash. |
| **Login URL** | https://console.cloud.google.com |
| **Credentials** | Please contact Marketing for details about Account Access and Passwords sheet |
| **When you'd need it** | If AI features stop working (likely an expired or revoked API key) |
| **Status page** | https://status.cloud.google.com/ |

### 5. Mailchimp — Audience & Campaign Integration

| | |
|---|---|
| **What it does for Buddy CRM** | Audience Buddy pulls campaign and audience data from Mailchimp for sync against Salesforce. |
| **Login URL** | https://mailchimp.com |
| **Credentials** | Please contact Marketing for details about Account Access and Passwords sheet |
| **When you'd need it** | If Mailchimp sync fails |
| **Status page** | https://status.mailchimp.com/ |

### 6. Gmail — Skill-Queue Notifications

| | |
|---|---|
| **What it does for Buddy CRM** | Sends transactional email notifications when Skill Queue tasks complete or fail. Uses Gmail SMTP via nodemailer. |
| **Login URL** | https://mail.google.com |
| **Credentials** | App Password stored in Netlify env vars (`GMAIL_USER`, `GMAIL_APP_PASSWORD`) |
| **When you'd need it** | If task completion/failure email notifications stop arriving |
| **Status page** | https://www.google.com/appsstatus/dashboard/ |

---

## Quick Reference: What Lives Where

| What | Where it lives |
|------|---------------|
| HTML pages (CSS/JS) | Netlify (served from the repo root) |
| API backend (Netlify Functions) | Netlify Functions |
| API keys and secrets | Netlify env vars |
| Auto-deploy trigger | GitHub `main` push (Netlify-GitHub integration) |
| All CRM data | Supabase (shared project) |
| User login / SSO | Microsoft Entra ID (managed by Max / Platform team) |
| AI features | Google Gemini API |
| Email send + receive | Microsoft Graph API |
| Outlook refresh tokens | Supabase `user_graph_tokens` (AES-256-GCM encrypted via `EMAIL_TOKEN_KEY`) |
| Meeting & email auto-logging | Supabase `email_messages`, `meeting_events`, plus their review queues |
| Mailchimp audience data | Mailchimp |
| Skill queue notifications | Gmail SMTP |
| Mobile PWA | Repo `mobile/` directory, served at `/mobile/*` |
| Service credentials | Account Access and Passwords sheet (contact Marketing) |
| Source code backup | GitHub + [SharePoint](https://nownz.sharepoint.com/:f:/s/Tools/IgCJmDrcuGh5Q4cFoyy7dnVEAdL2H95BDPF2Pi-xFQjCyrM?e=CpyqwP) (weekly) |

---

## Something is broken — where do I start?

1. **Check the status pages** above — is a platform having an incident?
2. **Check Netlify function logs** — Netlify → Functions → click the failing function
3. **Read the incident playbooks** — `docs/incident-playbooks.md` has scenario-by-scenario instructions
4. **Need to roll back?** — Netlify → Deploys → find the last working deploy → "Publish deploy" (instant)
5. **Need to toggle a feature off?** — Supabase → SQL Editor → `UPDATE feature_flags SET enabled = false WHERE key = 'feature_name';`

---

## Want to understand the codebase?

Read these in order:

1. **`docs/handover-2026-05-06.md`** — current state of every workstream (always read this first)
2. **`docs/architecture-overview.md`** — system diagram, file structure, auth flow, Outlook sync
3. **`docs/database-schema.md`** — all CRM tables and RPC functions
4. **`docs/environment-variables.md`** — every env var, what it does, criticality
5. **`docs/deployment-runbook.md`** — how to deploy, rollback, set up a new environment

---

## Need to manage access or onboard someone?

See **`docs/access-and-accounts.md`** — covers admin access for each platform, onboarding, and credential rotation.