Shielda — Production Architecture Document

Version: 2.0.0 Last Updated: 2026-04-03 Status: Production-Ready

---

Platform Overview

Shielda is an AI Security Engineer — an autonomous application security platform that discovers, scans, triages, and remediates vulnerabilities across your entire software estate. It combines 21 security scanning tools with 6 AI agents to provide continuous security coverage.

Core Value Proposition

Capability Description Autonomous Scanning Deploy an agent → it discovers services, generates security contracts, runs scanners, and triages findings — all without human intervention AI-Powered Triage 6 AI agents (Scout, Guardian, Verifier, Patch, Counselor, Auditor) provide context-aware analysis, eliminating false positives Security Contracts Machine-readable contracts define what each service IS from a security perspective — the AI uses these for informed triage Multi-Tenant SaaS Each customer gets an isolated subdomain (e.g., acme.shielda.io) with auto-provisioned DNS, TLS, CDN, and storage External Report Import Import findings from 18 external tools (Snyk, SonarQube, AWS Security Hub, etc.) with auto-detection

---

Architecture Overview

---

Tech Stack

Control Plane

Layer Technology Version Framework Next.js (App Router) 15.5.14 UI React + Tailwind CSS 19.1.0 Language TypeScript (strict + noUncheckedIndexedAccess) 5.x ORM Drizzle ORM 0.44.2 Database PostgreSQL 16 Validation Zod v4 Auth Auth0 SDK v4 Testing Vitest latest Error Tracking Sentry latest Payments Stripe latest

Go Agent

Layer Technology Version Language Go 1.25.0 CLI Cobra latest Container Docker SDK latest RPC gRPC + protobuf v1 Logging Zap latest Release GoReleaser latest

Infrastructure

Component Technology DNS AWS Route53 TLS AWS ACM CDN AWS CloudFront Storage AWS S3 Provisioning AWS SDK v3 / Terraform Container Orchestration Kubernetes (Helm chart) / ECS Fargate / Cloud Run / Azure ACI CI/CD GitHub Actions

---

Database Schema (81 Tables)

Core Tables

Table Purpose Key Indexes organizations Multi-tenant orgs with plan, billing, settings Primary users Auth0 users linked to orgs (orgid, email) agents Registered scan agents with heartbeat tracking (orgid) services Discovered services per agent (orgid) contracts Security Contracts (JSON) per service (orgid, serviceid) findings Normalized findings with fingerprint dedup (orgid, severity) verdicts AI triage results with rootCauseCategory (orgid)

AI & Scanning Tables

Table Purpose counselorsessions / counselormessages Chat session history scans / scantasks / scantoolresults Scan execution tracking aisafetyevents Prompt injection detection events aimodels / aiguardrails / aiagents AI governance custominstructions 5-level instruction hierarchy toolbundles Per-org bundle activation state

Business Tables

Table Purpose billingplans / subscriptions / invoices Stripe billing promocodes / promoredemptions / creditledger Promotions & credits teaminvites Team member invitations affiliates / affiliatereferrals Affiliate program featureflagoverrides Per-org feature flag customization tenantprovisions / provisioningevents Auto-provisioning pipeline reportimports / reportimportfindings External report imports importsourcecredentials / importsources External scanner connections webhooks / webhookdeliveries Outbound webhook subscriptions notifications In-app notification inbox auditlog Full audit trail

---

Security Architecture

Authentication

Mechanism Used For Details Auth0 SDK v4 Dashboard users HttpOnly, Secure, SameSite=Lax cookies. 8h absolute timeout, 30min idle, rolling refresh HMAC-SHA256 tokens Go agents Timing-safe comparison, legacy SHA-256 upgrade path CRONSECRET Cron endpoints Shared secret for scheduled job authentication Stripe signatures Webhooks stripe-signature header verification

Security Headers (all routes)

Header Value Content-Security-Policy strict-dynamic in production, nonce-based Strict-Transport-Security max-age=31536000; includeSubDomains; preload X-Frame-Options DENY X-Content-Type-Options nosniff Referrer-Policy strict-origin-when-cross-origin Permissions-Policy camera=(), microphone=(), geolocation=() Cross-Origin-Opener-Policy same-origin

Rate Limiting (multi-tier)

Tier Limit Scope Global 120 req/min Per IP Expensive endpoints 20 req/min Per IP Per-org (plan-based) Starter: 200, Pro: 1000, Business: 5000 req/min Per org Per-agent 30 req/min Per agent token

Encryption

Data Method Integration tokens (GitHub, Slack, etc.) AES-256-GCM at rest Webhook secrets AES-256-GCM at rest Agent tokens HMAC-SHA256 (one-way hash) Report import credentials AES-256-GCM at rest Data in transit TLS 1.2+ (HSTS enforced)

Multi-Tenancy

Subdomain routing: acme.shielda.io → middleware extracts slug → x-shielda-tenant header Org-scoped queries: Every DB query filters by orgId RLS: PostgreSQL Row-Level Security for defense-in-depth Isolated storage: Per-tenant S3 buckets via provisioning pipeline

---

AI Agents

Agent Model Purpose Guardian claude-opus-latest Generates/updates Security Contracts per service Verifier claude-opus-latest Context-aware triage: Signal → Verdict with importance/exploitability Scout claude-opus-latest Attack path analysis, blast radius estimation Patch claude-opus-latest Code fix generation + safe PoC (for VERIFIEDCRITICAL only) Counselor claude-opus-latest Interactive security chat with session management Auditor claude-opus-latest AI agent security auditing (permissions, prompt injection, data exfil)

All AI agents use BYOK (Bring Your Own Key) — customers provide their own Anthropic/OpenAI API keys. No customer code or data flows through Shielda's LLM keys.