LeakGuard AI — Autonomous Revenue Intelligence Platform

Production source for leaksshield.com — a multi-tenant B2B SaaS platform that detects revenue leaks and identifies growth opportunities for SaaS businesses, fully autonomously, by running a three-agent crew over the customer's Stripe data.

🌐 Live: https://leaksshield.com 🛒 Stripe Marketplace App: one-click install from Stripe Dashboard 👤 Built by: Nico Schöneburg (nico-ai.de · LinkedIn) — Solo Founder, Leak Shield Technologies LLC

This is the architecture-only showcase build. The full production tree is 2077 files / 44 MB; this public build is the engineering skeleton (~620 files, ~15 MB) — every router, service, model, migration, test, and infrastructure file is here, but the curated knowledge base, generated customer reports, internal strategy docs, and prospect-intelligence data are not. See SHOWCASE.md for the exact differences.

What it does

LeakGuard AI is a fully autonomous, multi-agent B2B SaaS platform that detects revenue leaks, identifies growth opportunities, and generates actionable reports — without human intervention.

Three AI agents (Leak Detector, Opportunity Scout, Validator) analyse Stripe billing data across ~10 revenue-leak categories and produce prioritised findings with quantified dollar impact. The platform ships as a Stripe Marketplace App (one-click install, zero signup) and as a standalone web product at leaksshield.com.

Tech stack

| Layer | Technology | |-------|------------| | API | FastAPI + Uvicorn + Jinja2 SSR | | Multi-agent | CrewAI 1.9.3 — 3 agents (Leak Detector + Opportunity Scout + Validator) | | LLM routing | OpenRouter via LiteLLM — Claude Opus 4.6 / GPT-4.1 / Claude Sonnet 4 in prod, Llama 3.3 70B (free) in dev | | Database | PostgreSQL 15 + SQLAlchemy 2.0 + Alembic | | Analytics DB | ClickHouse | | Cache / rate-limit / scheduler | Redis 7 | | Payments | Stripe Checkout + Webhooks + Stripe Connect + Stripe Marketplace App (React, UI Extension SDK) | | Email | SMTP / SendGrid / Resend (pluggable backend) | | Monitoring | Prometheus + Alertmanager + Telegram alerts | | Error tracking | Sentry with custom event filtering | | Analytics | Plausible (self-hosted) + Microsoft Clarity (path-gated, consent-aware) | | Hosting | AWS Lightsail, Docker multi-stage, Nginx + TLS (Let's Encrypt) | | Frontend | Jinja2 SSR for dashboard, React + Stripe UI Extension SDK for the Marketplace app | | Tests | 191 tests under tests/ (unit + integration) |

Engineering decisions worth scrutinising

These are the calls a reviewer is most likely to ask about. Files are real and clickable.

1. Three-agent crew with strict role separation

core/product_crew.py orchestrates the pipeline: Leak Detector → Opportunity Scout → Validator. The Validator is the QA layer — it rejects findings that fall outside known categories, that lack a traceable formula linking metrics to impact dollars, or that score below a confidence threshold. This pattern (specialist agents + skeptical validator) keeps hallucinated findings out of customer-facing reports. Agent definitions live in config.yaml (config-driven; the backstories are redacted in this showcase build — see file header).

2. CrewAI event-bus self-healing

CrewAI 1.9.3 uses a module-level singleton crewai_event_bus with a ThreadPoolExecutor that, once shut down by an unhandled error, leaves every subsequent crew.kickoff() failing with "cannot schedule new futures after shutdown". The fix in core/product_crew.py (_ensure_crewai_event_bus()) detects the broken state and rebuilds the executor + async event loop in place. This is a real production patch born of a real incident.

3. faulthandler for forensic segfaults

main.py calls faulthandler.enable() before any other init. After a one-off libc segfault on 2026-04-25 03:18 took the API down with no actionable evidence beyond a kernel traps: line, this was added so any future native-extension crash leaves a Python stack in Docker's json-file driver. Comment in the code records the date and the reasoning.

4. Blue-green zero-downtime deploys

deploy.sh implements atomic upstream switching via Nginx + Docker Compose. Sub-features:

• Lock file (/tmp/leakguard-deploy.lock) prevents concurrent deploys, with stale-lock cleanup
• --maintenance-on / --maintenance-off flip the site to a coming-soon page via an atomic Nginx reload
• --clean rebuilds without Docker cache, --all rebuilds all services, --skip-backup skips the pre-deploy DB dump
• CACHEBUST + COMMIT_SHA verified post-build so the running container is provably the just-built artifact

5. Multi-tenant from day one

Tenant isolation in services/tenant_service.py; per-tenant rate limiting in middleware; subscription + tier enforcement in services/tier_gate.py and services/plans_service.py. Stripe Connect for billing flows to customer accounts. Anonymous-access logging + API-key auth coexist in middleware/unified_auth.py.

6. Stripe Marketplace App + standalone web product, same backend

stripe-app/ is a React + Stripe UI Extension SDK app that installs into the customer's Stripe Dashboard with one click. routers/stripe_app_api.py is the Marketplace-app backend. routers/_web_dashboard.py is the standalone web dashboard (Jinja2 SSR). Both share the analysis pipeline, billing, and tenant model — only the presentation layer differs.

7. Sentry with custom event filtering

main.py initialises Sentry in each Uvicorn worker fork (not just the master) and registers a before_send hook that drops:

• Events from unittest modules (test runs)
• asyncio.CancelledError (jobs killed during deploys)
• Bot 404s and shutdown-noise

This keeps the Sentry quota focused on real production errors rather than test exceptions, deploy-time cancellations, or scanner bots.

8. ClickHouse for analytical queries

The OLTP path runs on Postgres. Funnel and time-series analytics queries that would degrade Postgres under load are routed to ClickHouse — see clickhouse/ for the schema and ingestion.

9. Pluggable email backend

services/email_service.py abstracts SMTP / SendGrid / Resend / stub behind a single interface, picked via EMAIL_BACKEND env var. The PDF-invoice generator (services/invoices.py) and transactional sender share the same dispatcher.

10. Self-hosted analytics, consent-aware

Plausible for the operator-facing funnel (no third-party). Microsoft Clarity (heatmaps / session replay) for the public landing pages only — path-gated in routers/__init__.py so it never loads on /dashboard, /monitor, /admin, /api, /metrics, /health. Clarity's built-in consent mode auto-blocks cookies for EEA/UK/CH visitors.

Project structure

.
├── main.py                       # FastAPI entry point (Sentry, faulthandler, env validation, lifecycle)
├── config.yaml                   # Multi-agent config (backstories redacted in this showcase)
├── core/                         # Product Crew orchestration + Knowledge Base API + config loader
│   ├── product_crew.py
│   ├── knowledge.py
│   ├── config.py
│   └── data_connector.py
├── agents/                       # LLM cost-optimization wrapper + agent monitoring
├── routers/                      # FastAPI route handlers
│   ├── analyze.py                # /api/v1/analyze (run analysis)
│   ├── client_api.py             # /api/v1/me/* (authenticated client endpoints)
│   ├── stripe_app_api.py         # /api/v1/stripe-app/* (Marketplace app backend)
│   ├── stripe_webhook.py         # Stripe webhook receiver (signature verified)
│   ├── _web_dashboard.py         # Dashboard UI (Jinja2 SSR)
│   ├── _web_landing.py           # Public landing pages
│   ├── _web_help.py, _help_content.py, _seo_content.py
│   ├── admin.py, billing.py, clients.py, agents.py
│   ├── onboarding.py, inbound_email.py, resend_webhook.py
│   ├── health.py, monitor.py, scheduler.py, internal_reports.py
│   └── web.py
├── services/                     # Domain logic (35 files)
│   ├── stripe_data_service.py    # Stripe Connect data fetching
│   ├── stripe_enrichment.py      # Map findings to Stripe objects
│   ├── analysis_service.py, leak_findings.py
│   ├── tenant_service.py, plans_service.py, tier_gate.py
│   ├── email_service.py, fastmail_service.py
│   ├── alert_service.py, telegram_service.py
│   ├── prometheus_client.py, plausible_service.py
│   └── … and more
├── middleware/                   # auth, rate-limit, security headers, CORS
├── models/                       # SQLAlchemy ORM
├── jobs/                         # Scheduled background work
│   ├── recurring_analysis.py
│   ├── stripe_sync.py
│   ├── billing_cycle.py
│   └── pattern_aggregation.py
├── alembic/                      # 55 DB migrations
├── database/                     # DB engine / session setup
├── clickhouse/                   # Analytics DB schema + ingestion
├── monitoring/                   # Prometheus, Alertmanager wiring (data dirs gitignored)
├── stripe-app/                   # Stripe Marketplace App (React + UI Extension SDK)
├── templates/                    # Jinja2 SSR templates
├── static/                       # JS / CSS / images for dashboard + landing
├── tests/                        # 191 unit + integration tests
├── scripts/                      # Operational scripts
├── utils/                        # Cross-cutting utilities (env validation, prompt sanitizer, …)
├── Dockerfile                    # Multi-stage build
├── docker-compose.yml            # Local dev stack
├── docker-compose.prod.yml       # Production stack
├── nginx.conf                    # Reverse proxy + TLS + blue-green upstream
├── deploy.sh                     # Blue-green zero-downtime deploy
├── entrypoint.sh                 # Container entrypoint
├── alembic.ini, pytest.ini, ruff.toml, .coveragerc
├── Makefile, dev.sh, e2e_test.sh
└── .env.example                  # Required env vars (Postgres, Redis, Stripe, LLM, email, monitoring)

Build & run

# Configure
cp .env.example .env
# Then fill in at minimum: DB_PASSWORD, OPENROUTER_API_KEY, JWT_SECRET
# (Stripe / email / monitoring are optional unless you exercise those flows)

# Local development (with Docker)
docker compose up -d        # postgres + redis + clickhouse
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head        # apply migrations
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Run tests
pytest                       # 191 tests
ruff check . && ruff format --check

# Production deploy
./deploy.sh                  # blue-green API deploy
./deploy.sh --all            # rebuild all services
./deploy.sh --clean          # rebuild without Docker cache
./deploy.sh --maintenance-on # show coming-soon page

# Stripe Marketplace App development
cd stripe-app && npm install && stripe apps start

Built by

Nico Schöneburg — AI Developer & Founder @ Leak Shield Technologies LLC, Spokane Valley, WA. Reach me at nico-ai.de or LinkedIn.

License

Released under the PolyForm Noncommercial License 1.0.0 — a source-available license.

• ✅ Read, clone, run locally, study the code
• ✅ Noncommercial use by individuals, charities, education, public-sector
• ❌ No commercial use, including reshipping the multi-agent / billing / Stripe-marketplace / blue-green-deploy scaffolding inside a paid service or competing product

Commercial licensing of this code or the underlying product: [email protected].