# Pulse

Internal PSA management dashboard for Wulf Consulting. Pulse syncs Autotask data
into Postgres and layers dashboards, ticket workflow automation, and analytics
across a number of MSP tooling integrations (Microsoft 365, Datto RMM, Veeam,
Auvik, Addigy, IT Glue, Mimecast, SentinelOne, Duo, Zoom, QuickBooks Online,
Zabbix, and more).

## Stack

- Next.js 16 (App Router) + React 19, TypeScript
- PostgreSQL 16 via `pg` (no ORM); Redis for caching
- Better Auth — magic link, TOTP 2FA, Microsoft OAuth
- Tailwind 4 + shadcn/ui, recharts, sonner, lucide
- Anthropic SDK for AI triage and analysis features
- node-cron scheduler embedded in the app process
- Docker Compose for local and prod (Traefik-fronted)

## Quick start

Prerequisites: Docker + Docker Compose, or Node 20+ and a local Postgres/Redis.

```bash
cp .env.example .env.local   # if present, otherwise see docker-compose.yml
docker compose up -d         # Postgres applies migrations/ on first init
npm install
npm run dev                  # http://localhost:3100
```

The first user to authenticate is bootstrapped as `super-admin` from
`DEFAULT_ADMIN_EMAIL`.

## Scripts

| Command | What it does |
|---|---|
| `npm run dev` | Next.js dev server on port 3100 |
| `npm run build` | Production build (turbopack) |
| `npm start` | Run the built app |
| `npm run lint` | ESLint |
| `npx tsc --noEmit --pretty` | Type check (the project's only automated check — there is no test suite or CI) |

## Project layout

```
app/                    Next.js App Router — pages and app/api/**/route.ts handlers
components/             Feature components; components/ui/ is shadcn primitives
lib/services/           Integration clients, sync services, scheduler
lib/types/              Shared TypeScript types per domain
lib/auth*.ts            Better Auth config and helpers
migrations/             Numbered SQL migrations applied on Postgres init
scripts/                One-off ops/diagnostic scripts (not tests)
docs/                   Deep-dive guides per integration and feature
```

## Configuration

All credentials come from environment variables. The major groups:

- **Database / cache**: `POSTGRES_HOST/PORT/DB/USER/PASSWORD` (or `DATABASE_URL`), `REDIS_URL`
- **Auth**: `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `MICROSOFT_CLIENT_ID/SECRET/TENANT_ID`, `DEFAULT_ADMIN_EMAIL`
- **Autotask**: `AUTOTASK_API_URL`, `AUTOTASK_USERNAME`, `AUTOTASK_SECRET`, `AUTOTASK_API_INTEGRATION_CODE`, `AUTOTASK_WEBHOOK_SECRET`
- **Microsoft 365 Graph (app)**: `MSGRAPH_CLIENT_ID/SECRET/TENANT_ID`
- **Other integrations**: `DATTO_RMM_*`, `VEEAM_VSPC_*`, `AUVIK_*`, `ADDIGY_*`, `ITGLUE_*`, `MIMECAST_*`, `S1_*`, `DUO_*`, `ZOOM_*`, `QBO_*`, `ZABBIX_*`, `SALESBLDR_*`
- **AI**: `ANTHROPIC_API_KEY`

See `AUTOTASK_API_GUIDE.md` and `ADDIGY_API_GUIDE.md` for credential setup.
`docs/` has per-integration guides for the rest.

## Documentation

- **`CLAUDE.md`** — repo orientation for AI coding sessions; also a useful overview for new contributors
- **`AUTOTASK_API_GUIDE.md`**, **`ADDIGY_API_GUIDE.md`** — credential setup
- **`POSTGRES_SYNC_SETUP.md`** — database initialization
- **`DOCKER_README.md`** — Docker workflow
- **`PULSE_DATABASE_SKILL.md`** — diagnostic SQL queries
- **`docs/wulf-pulse-ticket-analyzer-runbook.md`** — AI ticket analyzer operator runbook (cost monitoring, IT Glue alias map, failure triage)
- **`docs/`** — sync behavior, webhook setup, workflow editor, per-integration guides

## Deployment

Production runs via `docker compose up -d` behind Traefik. The app is reachable
at `pulse.wulfconsulting.cloud`. There is no CI/CD pipeline — deploys are manual
(rebuild image, recreate containers).

## License

Internal use only.