lorentz
1c5ec0f947
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>
88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# 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.
|