lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

feat: Veeam RPO analysis, comparison, ticket analysis + company teams table

Browse source 
- Add Veeam RPO analysis page (/veeam-analysis) and comparison page (/veeam-comparison)
- Add API routes: /api/veeam/rpo-analyze, rpo-comparison, rpo-offline-log, ticket-analysis
- Add veeam-rpo-service.ts enhancements (RPO logic, offline detection, comparison)
- Add veeam-analysis-state.ts and rmm-device-resolver.ts services
- Add migrations 065-068: company_teams, veeam_rpo_offline_log, rpo_comparison_tables, veeam_ticket_analysis
- Add backup-status page updates and nav links for new Veeam pages
- Add scripts: deactivate-cis-for-inactive-companies, workstation category updates
- Add docs: mimecast-api-guide, veeam-backup-alerting-recommendation, workstation-backup-overview, ticket-analyzer-prompt
- Minor: webhook-service, entity-sync, entity-mapper, sync-helpers, sync.ts, middleware.ts updates
This commit is contained in:
lorentz 2026-04-29 09:16:46 -04:00
parent 07067bef19
commit ea3471d38d
36 changed files with 5604 additions and 217 deletions
Download patch file Download diff file Expand all files Collapse all files

226
README.md
View file

@ -1,193 +1,87 @@
# Autotask API Integration Dashboard
# Pulse
A modern Next.js application for interacting with the Autotask PSA REST API, built with React, TypeScript, shadcn/ui, and Tailwind CSS.
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).
## Features
## Stack
- **Dashboard Overview** - View tickets, tasks, and company information
- **Ticket Management** - List, filter, and manage support tickets
- **Task Tracking** - Monitor and update project tasks
- **Company Selector** - Filter data by company
- **Resource Management** - Filter by assigned resources
- **Modern UI** - Beautiful interface built with shadcn/ui components
- **Dark Mode Support** - Automatic dark/light theme
- **Real-time Updates** - Fetch latest data from Autotask API
- **Secure Authentication** - API credentials stored in environment variables
- 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)
## Tech Stack
## Quick start
- **Framework**: Next.js 15 with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS v4
- **UI Components**: shadcn/ui
- **Icons**: Lucide React
- **Date Handling**: date-fns
- **API Integration**: Native fetch with custom client
Prerequisites: Docker + Docker Compose, or Node 20+ and a local Postgres/Redis.
## Prerequisites
Before you begin, ensure you have:
1. Node.js 18+ installed
2. Autotask API credentials:
- API Username (format: `apiuser@YOURDOMAIN.COM`)
- API Secret/Password
- API Integration Code
- API Base URL (e.g., `https://webservices1.autotask.net/atservicesrest/v1.0`)
## Installation
1. Clone the repository and navigate to the app directory:
```bash
cd /Users/lorentz/projects/PSA-Utils/autotask-app
```
2. Install dependencies:
```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
```
3. Create a `.env.local` file in the root directory:
```env
# Autotask API Configuration
AUTOTASK_API_URL=https://webservices1.autotask.net/atservicesrest/v1.0
AUTOTASK_USERNAME=your-api-username@yourdomain.com
AUTOTASK_SECRET=your-api-password
AUTOTASK_API_INTEGRATION_CODE=your-tracking-code
```
The first user to authenticate is bootstrapped as `super-admin` from
`DEFAULT_ADMIN_EMAIL`.
4. Run the development server:
```bash
npm run dev
```
## Scripts
5. Open [http://localhost:3000](http://localhost:3000) in your browser
| 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 Structure
## Project layout
```
autotask-app/
├── app/
│ ├── api/ # API route handlers
│ │ ├── tickets/ # Ticket endpoints
│ │ ├── tasks/ # Task endpoints
│ │ ├── companies/ # Company endpoints
│ │ ├── resources/ # Resource endpoints
│ │ └── picklists/ # Picklist endpoints
│ └── page.tsx # Main dashboard page
├── components/
│ ├── tickets/ # Ticket-related components
│ ├── tasks/ # Task-related components
│ ├── companies/ # Company-related components
│ └── ui/ # shadcn/ui components
├── lib/
│ ├── services/ # API client and services
│ │ ├── autotask-client.ts
│ │ └── autotask-factory.ts
│ ├── types/ # TypeScript type definitions
│ │ └── autotask.ts
│ └── hooks/ # Custom React hooks
│ └── use-api.ts
└── public/ # Static assets
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
```
## API Endpoints
## Configuration
The application provides the following API routes:
All credentials come from environment variables. The major groups:
- `GET /api/tickets` - Fetch tickets (with optional filters)
- `POST /api/tickets` - Create a new ticket
- `GET /api/tasks` - Fetch tasks (with optional filters)
- `POST /api/tasks` - Create a new task
- `GET /api/companies` - Fetch all active companies
- `GET /api/resources` - Fetch resources/users
- `GET /api/picklists` - Fetch picklist values for dropdowns
- **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`
## Key Features Implementation
See `AUTOTASK_API_GUIDE.md` and `ADDIGY_API_GUIDE.md` for credential setup.
`docs/` has per-integration guides for the rest.
### Rate Limiting
The API client includes built-in rate limiting (10 requests/second) to comply with Autotask API limits.
## Documentation
### Error Handling
Comprehensive error handling with user-friendly error messages and retry capabilities.
- **`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/`** — sync behavior, webhook setup, workflow editor, per-integration guides
### Type Safety
Full TypeScript support with detailed type definitions for all Autotask entities.
## Deployment
### Responsive Design
Mobile-friendly interface that works on all device sizes.
## Development
### Adding New Features
1. **New API Endpoints**: Add route handlers in `app/api/`
2. **New Components**: Create components in `components/`
3. **New Entity Types**: Update types in `lib/types/autotask.ts`
4. **New API Methods**: Extend `lib/services/autotask-client.ts`
### Testing
Run the development server and test with your Autotask sandbox environment:
```bash
npm run dev
```
### Building for Production
```bash
npm run build
npm start
```
## Security Considerations
- Never commit `.env.local` or any file containing API credentials
- Use environment variables for all sensitive configuration
- Implement proper authentication for production deployment
- Consider adding user authentication layer
- Use HTTPS in production
## Common Issues & Solutions
### API Connection Issues
- Verify your API credentials are correct
- Check the API URL matches your Autotask zone
- Ensure your API user has appropriate permissions
### Rate Limiting
- The client automatically handles rate limiting
- If you encounter 429 errors, the client will retry
### CORS Issues
- API routes act as a proxy to avoid CORS issues
- All Autotask API calls go through Next.js API routes
## Future Enhancements
- [ ] Add Redis caching for improved performance
- [ ] Implement real-time updates with WebSockets
- [ ] Add attachment upload functionality
- [ ] Create ticket/task editing forms
- [ ] Add user authentication and session management
- [ ] Implement advanced search and filtering
- [ ] Add data export functionality
- [ ] Create dashboard widgets and analytics
## Contributing
Feel free to submit issues and enhancement requests!
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
This project is for internal use. Please refer to your organization's policies.
## Support
For issues related to:
- **Autotask API**: Consult the [Autotask REST API Documentation](https://ww1.autotask.net/help/DeveloperHelp/Content/APIs/REST/REST_API_Home.htm)
- **Application Issues**: Create an issue in this repository
---
Built with ❤️ using Next.js, React, and shadcn/ui
Internal use only.