Files · Xero Reliability Suite for SMB Accounting Operations

# Xero Reliability Suite for SMB Accounting Operations
 
> Auto-generate Xero incident runbooks, wrap API calls with circuit breakers, rotate OAuth secrets, and get Slack alerts — all without an SRE.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
```
┌─────────────────────────────┐
│       Next.js App Router    │
│  ┌───────────────────────┐  │
│  │   /api/dashboard      │  │
│  │   /api/circuit-breaker│  │
│  │   /api/runbook        │  │
│  │   /api/secrets        │  │
│  └───────────┬───────────┘  │
└──────────────┼──────────────┘
               │
    ┌──────────┴──────────┐
    │   XeroReliabilitySuite  │
    │   (glue orchestrator)   │
    ├─────────────────────────┤
    │ ProtectedXeroClient     │
    │   └─ CircuitBreaker     │
    ├─────────────────────────┤
    │ XeroService             │
    │   └─ xero-node          │
    ├─────────────────────────┤
    │ RotationManager         │
    │   └─ @reaatech/         │
    │      secret-rotation-core│
    ├─────────────────────────┤
    │ Slack alerts            │
    │   └─ @slack/web-api     │
    ├─────────────────────────┤
    │ Runbook generation      │
    │   └─ @reaatech/         │
    │      agent-runbook-agent │
    │      agent-runbook-cli   │
    └─────────────────────────┘
```
 
## Setup
 
### Prerequisites
- Node.js >= 22
- pnpm 10.x
- A Xero API application (free tier available)
- A Slack workspace with a bot token
- An Anthropic API key (for runbook generation)
 
### Environment variables
Copy `.env.example` to `.env` and fill in the values:
 
```bash
cp .env.example .env
```
 
### Install
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev on localhost:3000
```
 
## API reference
 
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/api/circuit-breaker/status` | Return all breaker states |
| POST | `/api/circuit-breaker/reset` | Reset a named breaker |
| POST | `/api/runbook/generate` | Trigger runbook generation |
| GET | `/api/runbook/latest` | Return cached runbook |
| POST | `/api/secrets/rotate` | Trigger manual secret rotation |
| GET | `/api/secrets/status` | Return rotation status |
| POST | `/api/secrets/start` | Start auto-rotation |
| POST | `/api/secrets/stop` | Stop auto-rotation |
| GET | `/api/dashboard` | All dashboard data |
 
## CLI usage
The recipe also bundles `@reaatech/agent-runbook-cli` for headless runbook generation:
 
```bash
npx agent-runbook-generator generate /path/to/repo --output runbook.md
```
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
  api/                Route handlers (circuit-breaker, runbook, secrets, dashboard)
  dashboard/          Dashboard UI page
src/                  services, lib, adapters
  types.ts            Shared TypeScript interfaces
  config.ts           Zod-validated env config
  xero-client.ts      Xero API client wrapper (xero-node)
  circuit-breakers.ts Circuit breaker layer (@reaatech/circuit-breaker-agents)
  runbook-scan.ts     Runbook generation (@reaatech/agent-runbook-agent + -cli)
  analyzer.ts         Xero API call-site discovery (@reaatech/agent-runbook-analyzer)
  secrets-rotation.ts Secret rotation engine (@reaatech/secret-rotation-core)
  slack-alerts.ts     Slack notification helpers (@slack/web-api + @reaatech/agent-runbook-alerts)
  trigger-cron.ts     Scheduled rotation cron (@trigger.dev/sdk)
  glue.ts             XeroReliabilitySuite orchestrator
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## Packages used
 
### REAA (vendored)
- `@reaatech/agent-runbook-agent` — AI-powered code analysis and runbook generation
- `@reaatech/agent-runbook-alerts` — Alert definition extraction and generation
- `@reaatech/agent-runbook-analyzer` — Repository scanning for API endpoints
- `@reaatech/agent-runbook-cli` — CLI wrapper for the runbook ecosystem
- `@reaatech/circuit-breaker-agents` — Sliding-window circuit breaker with persistence
- `@reaatech/secret-rotation-core` — Zero-downtime secret rotation engine
 
### Third-party
- `xero-node` — Xero Accounting API client (OAuth 2.0)
- `@slack/web-api` — Slack Web API client
- `@trigger.dev/sdk` — Durable cron scheduling for secret rotation
- `zod` — Runtime schema validation
- `p-retry` — Retry with exponential backoff
- `dotenv` — Environment variable loading
 
## License
 
MIT — see [LICENSE](./LICENSE).