hoppscotch/hoppscotch
Open-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia
12 hidden assumptions · 5-stage pipeline · 10 components
Like any codebase, this fullstack makes assumptions it never checks — most are routine. The ones worth your attention are below.
Multi-platform API development ecosystem providing web, desktop, CLI, and agent tools
The system follows a client-server architecture where multiple client applications (web, desktop, CLI, agent) interact with a centralized NestJS backend through GraphQL/REST APIs. User requests flow from clients through shared business logic that handles authentication, environment variable substitution, and request preparation, then execute via platform-specific networking layers (browser fetch, Tauri HTTP, Rust relay), with results synchronized back through the backend to maintain consistency across all connected clients.
Under the hood, the system uses 3 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.
A 10-component fullstack. 1187 files analyzed. Data flows through 5 distinct pipeline stages.
Hidden Assumptions
Most of what this code assumes is routine. These 3 are the ones most likely to cause trouble here. The rest are minor; they're under "Show everything".
configService.get('WHITELISTED_ORIGINS').split(',') could produce empty strings or whitespace values as valid origins, allowing CORS bypass attacks or breaking origin validation
Fallback crypto.randomBytes(16).toString('hex') only provides 128-bit entropy which may be insufficient, or custom SESSION_SECRET could be weak, leading to session hijacking
If desktop DESKTOP_IO_IMPLS differs behaviorally from WEB_IO_IMPLS (different error handling, return types, async patterns), code using the kernel will work on one platform but fail silently or crash on the other
Show everything (9 more)
Environment variable expansion will complete within ENV_MAX_EXPAND_LIMIT (10) iterations
If this fails: Complex variable chains or circular references beyond 10 levels silently truncate expansion, returning partially resolved strings with unexpanded <<variable>> patterns instead of detecting the loop
packages/hoppscotch-data/src/environment/index.ts:parseBodyEnvVariablesE
Platform services initialize in the exact sequence: auth, settings sync, collections sync, history sync, environments sync, analytics
If this fails: If collections sync requires auth tokens or environments sync needs settings loaded, changing initialization order or adding services between existing ones could break dependent services that expect prerequisites
packages/hoppscotch-common/src/helpers/app/index.ts:initializeApp
All object values are either strings or safely passable as-is - no nested objects, arrays, or complex structures need template parsing
If this fails: Objects with nested structures containing template strings (like headers: {authorization: {bearer: '<<token>>'}} or arrays with string elements) skip template replacement, leaving unexpanded variables
packages/hoppscotch-common/src/helpers/auth/index.ts:replaceTemplateStringsInObjectValues
Collection _ref_id values remain unique across all collections and concurrent operations
If this fails: generateUniqueRefId('coll') could produce duplicate IDs if called simultaneously or if the generation algorithm isn't truly unique, causing collection conflicts, sync issues, or data overwrites
packages/hoppscotch-data/src/collection/index.ts:makeCollection
JSON payloads up to 100MB can be safely processed in memory without causing OOM or blocking the event loop
If this fails: Large uploads could exhaust heap memory on constrained deployments or block the Node.js event loop during JSON parsing, causing timeouts for other requests or server crashes
packages/hoppscotch-backend/src/main.ts:bootstrap
Application initialization only needs to happen once and platform services remain stable after first initialization
If this fails: If services crash, disconnect, or need reinitialization (network failures, auth token expiry), the initialized=true flag prevents recovery, leaving the app in a broken state with no sync or authentication
packages/hoppscotch-common/src/helpers/app/index.ts:initializeApp
window.__KERNEL_MODE__ is set correctly during application bootstrap and never changes during runtime
If this fails: If __KERNEL_MODE__ is undefined, unset, or changes after initialization (browser extensions, hot reloading), kernel operations fallback to 'web' mode which may use wrong APIs, break desktop features, or cause permission errors
packages/hoppscotch-kernel/src/index.ts:getKernelMode
HOPP_SUPPORTED_PREDEFINED_VARIABLES.getValue() functions always return valid string values and never throw exceptions
If this fails: If a predefined variable's getValue() throws an error, returns null/undefined, or returns non-string types, the template replacement crashes instead of gracefully falling back to the original <<variable>> pattern
packages/hoppscotch-data/src/environment/index.ts:parseBodyEnvVariablesE
MIME type detection and file hashing operations can handle all possible file types and sizes in the webapp directory
If this fails: Binary files, very large assets, or files with unusual extensions could cause MIME detection to fail, blake3 hashing to consume excessive memory, or ZIP compression to timeout, breaking bundle creation
packages/hoppscotch-desktop/crates/webapp-bundler/src/main.rs:BundleBuilder
Open the standalone hidden-assumptions report for hoppscotch →
How Data Flows Through the System
The system follows a client-server architecture where multiple client applications (web, desktop, CLI, agent) interact with a centralized NestJS backend through GraphQL/REST APIs. User requests flow from clients through shared business logic that handles authentication, environment variable substitution, and request preparation, then execute via platform-specific networking layers (browser fetch, Tauri HTTP, Rust relay), with results synchronized back through the backend to maintain consistency across all connected clients.
- Request preparation — Client applications use replaceTemplateStringsInObjectValues to resolve <<variable>> placeholders in request URLs, headers, and bodies using combined environment variables, request variables, and predefined variables [HoppCollection → RequestWithMetadata]
- Authentication and authorization — The backend validates user sessions, checks team membership permissions, and ensures access rights to collections and environments through NestJS guards and GraphQL resolvers [Team] (config: WHITELISTED_ORIGINS, SESSION_SECRET)
- Network execution — Requests execute through platform-specific implementations: browser fetch API for web clients, Tauri's HTTP client for desktop, or Rust relay crate for agent/CLI with full HTTP feature support [RequestWithMetadata → ResponseWithMetadata]
- Response processing and testing — The js-sandbox package executes post-request test scripts in a controlled environment, validating response data against user-defined assertions and collecting test results [ResponseWithMetadata]
- Data synchronization — Changes to collections, environments, and settings propagate through the backend's GraphQL subscriptions to keep all connected clients synchronized in real-time (config: DATABASE_URL)
Data Models
The data structures that flow between stages — the contracts that hold the system together.
packages/hoppscotch-data/src/collection/index.tsversioned entity with v: number, name: string, requests: HoppRESTRequest[], folders: HoppCollection[], variables: CollectionVariable[], _ref_id: string
Created from file/API import, stored in local/remote storage, executed by request runner, synchronized across clients
packages/hoppscotch-data/src/environment/index.tsversioned entity with v: number, name: string, variables: EnvironmentVariable[] where each variable has key: string, currentValue: string, secret: boolean
Defined by user, stored with collection metadata, used during template parsing to replace <<variable>> placeholders in requests
packages/hoppscotch-backend/src/team/team.model.tsGraphQL object with id: string, name: string, members: TeamMember[] where TeamMember has membershipID: string, userUid: string, role: TeamAccessRole enum
Created through backend API, managed via GraphQL mutations, controls access to shared collections and environments
packages/hoppscotch-cli/src/types/errors.tsunion type with code: HoppErrorCode and contextual data like path: string, command: string, or data: any based on error type
Generated during CLI operations, propagated through error handlers, formatted for user display with context-specific information
packages/hoppscotch-relay/src/interop.rsRust struct containing HTTP request details with method, URL, headers, body, and execution metadata for network operations
Constructed from user input in clients, serialized for relay transmission, executed by Rust networking layer, returns ResponseWithMetadata
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
PostgreSQL database storing teams, users, shared collections, environments, and collaboration data accessed through Prisma ORM
Platform-specific persistence layer storing user preferences, cached collections, and offline data with different implementations for web localStorage and desktop file system
Express session middleware storing user authentication state and temporary request context with configurable cookie names for proxy compatibility
Feedback Loops
- Real-time synchronization (polling, balancing) — Trigger: Data changes in backend database. Action: GraphQL subscriptions push updates to all connected clients, triggering local state updates and UI refreshes. Exit: Client disconnection or app shutdown.
- Environment variable expansion (recursive, balancing) — Trigger: Template strings containing <<variable>> patterns in request data. Action: parseBodyEnvVariablesE recursively expands variables up to ENV_MAX_EXPAND_LIMIT depth, replacing patterns with actual values. Exit: No more patterns found or maximum expansion depth reached.
- Collection schema migration (self-correction, balancing) — Trigger: Loading collections with older schema versions. Action: HoppCollection.createVersionedEntity automatically migrates data through version transformation functions. Exit: Data reaches current schema version (v11).
Delays
- Application initialization (warmup) — Platform services (auth, sync, analytics) initialize sequentially before app becomes fully functional
- Bundle creation (compilation) — Desktop application startup waits for web assets to be bundled into ZIP format with manifest generation and file hashing
- Request delay (rate-limit, ~configurable via --delay flag) — CLI tool waits between consecutive requests within a collection to avoid overwhelming target servers
Control Points
- WHITELISTED_ORIGINS (env-var) — Controls: CORS policy determining which frontend domains can access the backend API in production mode
- DATABASE_URL (env-var) — Controls: PostgreSQL connection string for data persistence and team collaboration features
- Kernel Mode (runtime-toggle) — Controls: Platform-specific API implementations - web uses browser APIs, desktop uses Tauri/Rust implementations. Default: web or desktop
- Collection Schema Version (architecture-switch) — Controls: Data model version for collections, currently at v11 with automatic migration from older versions. Default: 11
Technology Stack
Backend application framework providing dependency injection, GraphQL API generation, and middleware management for the centralized server
Frontend framework for the proxy agent application and shared UI components used across web interfaces
Desktop application framework wrapping web content in native OS windows with Rust backend for system integration and networking
CLI framework handling command parsing, argument validation, and help generation for the command-line testing tool
Primary database for persistent storage of teams, users, collections, and collaboration data accessed through Prisma ORM
API layer providing type-safe queries, mutations, and real-time subscriptions for data synchronization between clients and backend
Systems programming language used for high-performance HTTP request execution in the relay library and desktop networking layer
Code editor providing syntax highlighting, folding, and editing features for GraphQL queries and request bodies
Key Components
- NestFactory (orchestrator) — Bootstraps the NestJS backend application with CORS, session management, validation pipes, and Swagger documentation setup
packages/hoppscotch-backend/src/main.ts - test command (executor) — Commander.js command that orchestrates collection loading, environment variable resolution, request execution, and test result reporting
packages/hoppscotch-cli/src/index.ts - createApp (factory) — Initializes Vue.js application for the proxy agent with HoppUI plugin registration and CSS theme loading
packages/hoppscotch-agent/src/main.ts - initializeApp (orchestrator) — Coordinates startup of all platform services including authentication, settings sync, collections sync, history sync, environments sync, and analytics
packages/hoppscotch-common/src/helpers/app/index.ts - replaceTemplateStringsInObjectValues (processor) — Processes request objects to replace <<variable>> template strings with actual values from combined environment variables and request variables
packages/hoppscotch-common/src/helpers/auth/index.ts - HoppCollection.createVersionedEntity (factory) — Creates versioned collection entities using verzod library, handling schema migrations between 11 different collection format versions
packages/hoppscotch-data/src/collection/index.ts - parseBodyEnvVariablesE (processor) — Recursively expands environment variables in request bodies using regex pattern matching with loop detection and predefined variable support
packages/hoppscotch-data/src/environment/index.ts - initKernel (factory) — Initializes platform-specific kernel implementations providing unified APIs for I/O, relay, storage, and logging across web and desktop modes
packages/hoppscotch-kernel/src/index.ts - run_request_task (executor) — Executes HTTP requests using Rust networking stack with advanced features like custom headers, body handling, and response processing
packages/hoppscotch-relay/src/relay.rs - BundleBuilder (processor) — Creates ZIP bundles from web application directories with manifest generation, file hashing, and MIME type detection for desktop app distribution
packages/hoppscotch-desktop/crates/webapp-bundler/src/main.rs
Package Structure
NestJS backend providing GraphQL/REST APIs, team management, authentication, and data persistence for all Hoppscotch clients
Command-line interface for automated API testing, collection running, and CI/CD integration with JUnit reporting
Tauri-based desktop application with system tray, bundled web content serving, and native OS integration
Vue.js proxy agent application running locally to bypass CORS restrictions and enable direct API testing from browsers
Shared business logic library containing authentication, environment management, request processing, and sync services used by all client applications
Versioned data models and schemas for collections, environments, and requests with migration logic between schema versions
Platform abstraction layer providing unified APIs for I/O, storage, and networking across web, desktop, and CLI environments
Rust library for executing HTTP requests with advanced networking features, used by desktop and agent applications
Web application for self-hosted deployments with team collaboration and workspace management features
Administrative dashboard for self-hosted instances to manage users, teams, and system configuration
Secure JavaScript execution environment for pre-request scripts and test runners with controlled module access
CodeMirror language extension providing GraphQL syntax highlighting, folding, and editor support
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Fullstack Repositories
Frequently Asked Questions
What is hoppscotch used for?
Multi-platform API development ecosystem providing web, desktop, CLI, and agent tools hoppscotch/hoppscotch is a 10-component fullstack written in TypeScript. Data flows through 5 distinct pipeline stages. The codebase contains 1187 files.
How is hoppscotch architected?
hoppscotch is organized into 4 architecture layers: Client Applications, Shared Business Logic, Data Layer, Platform Abstractions. Data flows through 5 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through hoppscotch?
Data moves through 5 stages: Request preparation → Authentication and authorization → Network execution → Response processing and testing → Data synchronization. The system follows a client-server architecture where multiple client applications (web, desktop, CLI, agent) interact with a centralized NestJS backend through GraphQL/REST APIs. User requests flow from clients through shared business logic that handles authentication, environment variable substitution, and request preparation, then execute via platform-specific networking layers (browser fetch, Tauri HTTP, Rust relay), with results synchronized back through the backend to maintain consistency across all connected clients. This pipeline design reflects a complex multi-stage processing system.
What technologies does hoppscotch use?
The core stack includes NestJS (Backend application framework providing dependency injection, GraphQL API generation, and middleware management for the centralized server), Vue.js (Frontend framework for the proxy agent application and shared UI components used across web interfaces), Tauri (Desktop application framework wrapping web content in native OS windows with Rust backend for system integration and networking), Commander.js (CLI framework handling command parsing, argument validation, and help generation for the command-line testing tool), PostgreSQL (Primary database for persistent storage of teams, users, collections, and collaboration data accessed through Prisma ORM), GraphQL (API layer providing type-safe queries, mutations, and real-time subscriptions for data synchronization between clients and backend), and 2 more. A focused set of dependencies that keeps the build manageable.
What system dynamics does hoppscotch have?
hoppscotch exhibits 3 data pools (Backend Database, Local Storage), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle polling and recursive. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does hoppscotch use?
4 design patterns detected: Versioned Entity Pattern, Platform Abstraction, Template String Processing, Monorepo with Shared State.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.