Architecture

Backend

opSentry runs on FastAPI (Python) with PostgreSQL for persistence.

Core modules:

• app/main.py — routing, auth middleware, rate limiting, plan gating
• app/translator.py — deterministic changelog extraction and orchestration
• app/ai.py — GPT-4o-mini enrichment via OpenAI
• app/db.py — raw SQL via psycopg (no ORM)
• app/auth.py — API key resolution and plan lookup
• app/rate_limit.py — per-key sliding window enforcement
• app/ingest_api.py — AI ingest pipeline with partner auto-matching
• app/alerts_api.py — alert CRUD and lifecycle endpoints
• app/partners_api.py — partner map upload, normalization, CRUD
• app/team_api.py — workspace membership management
• app/apps_api.py — app credential management

Frontend

Next.js (App Router) with React and TypeScript. State is managed with React hooks only — no Redux, no Zustand. Data fetching uses native fetch().

Database

PostgreSQL (raw SQL via psycopg2 — no ORM). Tables span the core domains: users, workspaces, sessions, alerts, apps, the partner map (partner_uploads, partner_mappings), partner onboarding, integration config (GitHub / Jira / HubSpot / Slack / Postman), billing, and the legacy translator log.

Alert lifecycle model

Alerts have no explicit status column. Status is derived:

• resolved_at = null → Active
• resolved_at = timestamp → Resolved

AI layer

The AI layer uses GPT-4o-mini and is completely additive. Every endpoint that uses AI has a deterministic fallback — if AI is unavailable, the system still returns valid structured output. Nothing depends on AI being available.

Design principles

1. Deterministic first, AI second
2. No silent behavior — every alert has an explicit state
3. Partner matching by scope intersection, not name string matching
4. Plan-based feature gating — AI features scale by tier (Free / Pro / Enterprise)