Developer Documentation & Reference
The complete technical architecture: high-throughput telemetry ingestion, deterministic SHA-256 error fingerprinting, pgvector runbook retrieval, and sandboxed AI SRE agent hotfix dispatching.
System Architecture & Tenancy
PulseGuard is an enterprise multi-tenant, AI-native incident response platform. It unifies high-throughput telemetry ingestion, automated deterministic error clustering, pgvector runbook retrieval, and sandboxed GitHub pull request dispatching under strict tenant-level RBAC isolation.
Local & Production Setup
PulseGuard runs on any Docker-compatible infrastructure. Spin up PostgreSQL with pgvector and Redis using the standard configuration:
# 1. Boot up Docker containers (PostgreSQL + pgvector & Redis) docker-compose up -d # 2. Push database schema & generate Prisma client bunx prisma db push && bunx prisma generate # 3. Start Next.js development server bun run dev
Ingestion Endpoint Specification
Send single error telemetry objects or bulk batches to the public ingestion endpoint. Requests are validated via Zod schemas and checked against Redis rate-limit windows.
curl -X POST https://pulseguard-app-navy.vercel.app/api/telemetry/ingest \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"service": "checkout-api",
"level": "ERROR",
"message": "StripeClientException: PaymentIntent timeout",
"metadata": { "statusCode": 500, "region": "us-east-1" }
}'Deterministic Anomaly Clustering
To prevent alert fatigue, dynamic variables (UUIDs, timestamps, hex tokens, numeric IDs, IP addresses) are sanitized into canonical tokens before SHA-256 hashing.
SIG_DB_TIMEOUT_e4a8b1c9War Room Tools & Streaming Protocol
Inside each incident War Room, the autonomous SRE agent executes sandboxed tools to correlate telemetry, pull relevant source code, and propose targeted remediation diffs:
Queries recent ERROR/FATAL logs by service and sliding time window to isolate the crash stack trace.
Uses authenticated GitHub App tokens to fetch the exact breaking source code lines in the repository.
Generates an isolated diff patch and presents a cryptographic sign-off card to human engineers.
Document Ingestion & Matryoshka Embeddings
PDF and Markdown runbooks are chunked into 600-character segments with 60-character sliding overlap. Embeddings are sliced using Matryoshka Representation Learning (MRL) down to 736 dimensions to match database schema constraints without precision degradation.
INSERT INTO "DocumentChunk" ("id", "documentId", "chunkIndex", "content", "embedding", "createdAt")
VALUES (
gen_random_uuid(),
document_id,
chunk_index,
chunk_content,
chunk_vector::vector(736),
NOW()
);AES-256 Key Encryption & Model Catalogs
Organizations provide their own AI provider credentials. API keys are encrypted at rest using AES-256 symmetric envelope encryption with random initialization vectors (IV).
Key input → AES-256 cipher (Random IV + SHA-256 server secret) → Stored in PostgreSQL as iv_hex:cipher_hex. Only masked key tokens (AIza...4F10) are returned to client browsers.
Human-in-the-Loop Git Automation
The AI agent is physically incapable of merging or pushing code autonomously. When an authorized engineer reviews the diff and clicks "Approve & Open PR", Octokit executes an atomic 5-step git transaction:
1. getRef('heads/main') → Reads latest upstream commit SHA
2. createRef('refs/heads/hotfix/...') → Provisions isolated hotfix branch
3. getContent(filePath) → Extracts existing repository file blob SHA
4. createOrUpdateFileContents(...) → Commits patched file with signed attribution
5. pulls.create(...) → Dispatches GitHub Pull Request with full incident RCA
Distributed Redis Caching Layer
High-frequency telemetry and dashboard operations are cached in Redis to eliminate database bottlenecks:
60s Sliding IP Window
Atomic INCR + PEXPIRE counters protect public endpoints.
300s Fingerprint Cache
Bypasses database queries during million-log floods.
24h Provider Catalog
Ensures instant zero-lag organization settings rendering.