Introduction & Concepts
Relevant source files
The following files were used as context for generating this wiki page:
Hoop is an open-source layer 7 gateway designed to sit between users (engineers, AI agents, service accounts) and production infrastructure, including databases, Kubernetes clusters, servers, and APIs. The system operates at the wire protocol level to enforce security policies such as PII masking, command blocking via guardrails, and session recording without requiring agents on endpoints or code changes to the target infrastructure.
Sources: README.md:1-20, README.md:94-110
The project is currently undergoing a frontend migration from a legacy ClojureScript Single Page Application (SPA) to a modern React-based architecture. This "React Shell" approach allows for incremental migration of pages while maintaining a unified global layout and shared authentication state.
Sources: webapp_v2/CONTEXT_MIGRATION.md:6-14
System Architecture
The Hoop environment consists of three primary components: the Gateway, which handles protocol parsing and policy enforcement; the Frontend (React Shell and legacy ClojureScript); and Agents, which facilitate connections within the infrastructure.
The Hoop Gateway
The gateway is the core engine that intercepts queries and commands. It natively parses protocols such as PostgreSQL, MySQL, MSSQL, MongoDB, SSH, and Kubernetes. By parsing these at the wire level, it can apply security logic like masking sensitive data in responses and blocking destructive DDL (e.g., DROP TABLE) before they reach the backend.
Sources: README.md:94-110, gateway/README.md:10-15
Data Flow & Policy Enforcement
When a request is initiated by a user or an AI agent, it passes through the gateway where multiple layers of governance are applied.
This diagram illustrates the inline control flow where the gateway acts as a decision point for data masking, command blocking, and approval workflows.
Sources: README.md:94-110
Frontend Migration Strategy
The frontend architecture uses a React Shell (webapp_v2) to wrap the legacy ClojureScript application (webapp). This allows the team to migrate features incrementally while the legacy bundle continues to render unmigrated routes.
Integration Mechanism
The two applications share state through localStorage, specifically using a jwt-token for authentication and a react-shell flag to signal the ClojureScript app to skip rendering its own navigation elements.
Sources: webapp_v2/CONTEXT_MIGRATION.md:27-46
| Mechanism | Description |
|---|---|
localStorage.react-shell = true | Signals CLJS to hide its own sidebar/header to avoid double-rendering. |
window.hoopSetRoute(path) | Syncs React Router changes to the CLJS Pushy router. |
window.hoopRemount() | Triggers a Reagent re-render without refetching user data. |
localStorage.jwt-token | Shared JWT token used by both apps for authenticated API calls. |
Sources: webapp_v2/CONTEXT_MIGRATION.md:38-46
Tech Stack Comparison
The project bridge connects a functional programming stack with a modern JavaScript ecosystem.
Sources: webapp/README.md:7-20, webapp_v2/README.md:5-15, webapp_v2/CONTEXT_MIGRATION.md:16-20
The architecture facilitates a transition from Re-frame/Hiccup to Zustand/JSX components.
Core Concepts
1. Guardrails
Guardrails are prevention-based security rules defined at the protocol layer. They identify and block dangerous operations (like rm -rf or DELETE without a WHERE clause) before they execute. This provides a security layer that is "prevention, not detection."
Sources: README.md:126-130
2. Live Data Masking
Unlike standard Data Loss Prevention (DLP) which catches leaks after they occur, Hoop uses ML-powered classification to mask PII, PHI, and credentials in real-time as data leaves the gateway. This happens with <5ms latency and does not require manual schema mapping.
Sources: README.md:120-125
3. AI Agent Governance
Hoop provides specific semantics for AI coding agents (e.g., Claude Code, Cursor). Agents can read masked data but require human approval for write operations. Every agent action is risk-scored and indexed for audit. The "User MCP server" feature allows agents to inherit the human user's OIDC permissions.
Sources: README.md:135-155
4. Resource Roles (Connections)
Resources are the infrastructure targets (databases, servers) connected to Hoop. Access is governed via "Resource Roles," which define the specific permissions, guardrails, and masking rules applied to a connection.
Sources: webapp_v2/src/pages/Roles/Configure/TerminalAccessTab.jsx:15-25, webapp_v2/COMPONENTS.md:144-155
Component & State Management (React)
In the new React architecture, state is managed via Zustand stores, and UI primitives are strictly wrapped to ensure consistent design.
Global Stores
| Store | Responsibility |
|---|---|
useAuthStore | Manages JWT token lifecycle and logout. |
useUserStore | Handles current user data, admin status, and license info. |
useUIStore | Manages sidebar state and global UI flags. |
useAgentStore | Handles CRUD operations for Hoop Agents. |
Sources: webapp_v2/CONTEXT_MIGRATION.md:95-103, webapp_v2/COMPONENTS.md:215-225
Reusable UI Patterns
The webapp_v2 environment enforces a "We own every component" strategy where Mantine primitives are wrapped in src/components/.
// Example of a shared component pattern for loading states
import useMinDelay from '@/hooks/useMinDelay'
import PageLoader from '@/components/PageLoader'
const showLoader = useMinDelay(loading, 500)
if (showLoader) return <PageLoader />
Sources: webapp_v2/COMPONENTS.md:5-25, webapp_v2/COMPONENTS.md:205-212
Summary
Hoop functions as a security-first layer 7 gateway that unifies access control for both humans and AI agents. By integrating a React-based shell with a legacy ClojureScript core, the project maintains operational continuity while modernizing its frontend. The core value lies in its ability to parse wire protocols inline to enforce guardrails and data masking before sensitive information ever leaves the production environment.
Sources: README.md:1-25, webapp_v2/CONTEXT_MIGRATION.md:6-25