lorentz 1c5ec0f947 docs(analyzer): phase 8 — operator runbook

docs/wulf-pulse-ticket-analyzer-runbook.md covers cost monitoring
queries, the $2 cost ceiling, IT Glue alias workflow, failure triage
(failed jobs vs needs_human_review), and manual ops (queue from psql,
force re-run, inspect model_traces). Calls out the manual migration
step for existing DBs and lists the unimplemented surfaces (no auto
retries, no viewed_at, no email_sent_at) so operators don't trip on
them. Linked from README.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-29 11:05:46 -04:00

3.6 KiB

Raw Blame History

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.

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.

3.6 KiB Raw Blame History