Folder structure
postman-app has 40+ top-level directories. This page explains every one of them, grouped by purpose.
Use Cmd+T (macOS) or Ctrl+T (VS Code) to jump to any file by name. Use the Folder index for a quick-reference table.
Core Nx architecture layers
These are the "new world" — the modular Nx packages that all new development must go into.
apps/
The Electron renderer entry point. Currently contains one app: apps/black — the main Postman desktop app.
This bootstraps the React tree, initializes MobX root stores, sets up the dock engine, and hands control to the router.
Rule: apps/ can import from any layer below it. It is the top of the dependency tree.
views/
URL-addressable pages — screens the router navigates to. Each view is a React component tree that orchestrates which ui-features to render.
views/
├── workspace-overview/ ← The main workspace page
├── workspace-issues/ ← Issues tab
├── all-workspaces/ ← Workspace directory
├── byok-settings/ ← Bring-your-own-key settings
├── mcp-servers-settings-ui/ ← MCP server config UI
└── ... (12 packages total)
Think of views as tab bars. They handle routing, tab visibility (based on permissions), and loading states. The actual tab content lives in ui-features/.
Rule: Can import from ui-features, data, platform-ui, platform-libs, libs. Cannot import other views.
ui-features/
Self-contained async feature modules. This is where most new development happens.
Each ui-feature is lazy-loaded (not in the initial bundle), owns its own data fetching, state management, and UI. It is a vertical slice of functionality.
ui-features/
├── collections-sidebar/ ← The collections tree, drag-drop, search
├── ai-chat/ ← AI assistant UI
├── command-palette-ui/ ← Cmd+K palette
├── datasets-sidebar/ ← Datasets panel
├── api-builder-workbench/ ← API Builder tab
├── workspace-overview-tab/ ← Overview tab content (inside workspace-overview view)
├── workspace-settings-tab/ ← Settings tab content
└── ... (~45 packages total)
Rule: Can import from data, platform-ui, platform-libs, libs, and other ui-features (carefully, to avoid cycles). Cannot import views or apps.
data/
The service and state layer. Zero UI code in here.
Contains MobX stores, React Query hooks, and API clients. Both views and ui-features read from data/ — the data layer has no knowledge of what UI renders it.
data/
├── workspace-data/ ← Workspace info, members, permissions store
├── collection-data/ ← Collections tree store
├── current-user/ ← Logged-in user store
├── collaboration-service/← Real-time collaboration
├── cloud-agent/ ← Cloud agent integration
├── environment-data/ ← Environments store
└── ... (~40 packages total)
Rule: Can import from platform-libs and libs only. No UI imports whatsoever.
platform-libs/
Horizontal infrastructure services used by everything — not feature-specific, not UI-specific.
platform-libs/
├── i18n-sdk/ ← Translations (wraps i18next)
├── analytics-service/ ← Segment + Amplitude event tracking
├── gateway-service/ ← Authenticated API client (Bifrost proxy)
├── storage-sdk/ ← Local persistence
├── websocket-proxy/ ← WebSocket connection management
├── realtime-pubsub/ ← Real-time event subscriptions
├── sidebar/ ← Sidebar dock engine
└── ... (~30 packages total)
Rule: Can import from libs only. Cannot import from any UI layer or data/.
platform-ui/
The Postman Aether design system — typed, themed React components.
platform-ui/
├── aether-components/ ← Typed wrappers for @postman/aether components
├── aether-design-tokens/← CSS variables and theme definitions
├── aether-icons/ ← Icon library
├── aether-tooling/ ← Dev tools for Aether
└── platform-ui-kit/ ← Additional shared UI primitives
All ui-features import from @postman-app/aether-components, not directly from @postman/aether. This allows the team to control versions and add type safety centrally.
Rule: Can import from platform-libs and libs only.
libs/ and libs-ui/
Pure reusable libraries with zero Postman-specific dependencies. These are the foundation of everything.
Could theoretically be published to npm — no app-specific code allowed.
libs/
├── data-structures/ ← Generic data structure utilities
├── fetch-with-retry/ ← Generic retry-on-failure fetch wrapper
├── collaboration-errors/← Error types for collaboration
├── dock-constants/ ← Constants for the dock engine
└── ... (~30 packages total)
Rule: Can only import external npm packages. No imports from other app layers.
Source code (Electron processes)
src/main/
The Electron main process — runs in Node.js, not in the browser.
Handles everything the renderer cannot do: native file system access, window management, native menus, auto-updater, and IPC channel registration.
When the renderer needs to read a local file, it sends an IPC message that src/main/ handles via a registered channel. The renderer never imports Node.js APIs (like fs) directly.
Has its own yarn.lock — run cd src/main && yarn when modifying its dependencies.
src/renderer/ ⚠️ Legacy monolith
The original Postman renderer. ~15,700 files, mostly JavaScript, no TypeScript strictness, no enforced module boundaries.
Never add new code here. This directory is being progressively migrated to Nx packages. See Migration strategy.
src/renderer/
├── collaboration/ ← Workspace, team features (migrating)
├── collections-sidebar/← Old sidebar (being replaced by ui-features/)
├── billing/ ← Payment and billing flows
├── iam/ ← Identity and access management
├── datasets/ ← Dataset UI (migrating)
├── runtime-repl/ ← Request runner (migrating)
├── onboarding/ ← App shell and manifests
└── ... (76 top-level directories)
src/postman-agent/
The Postman agent — a separate Node.js process for the Postman CLI and automated collection runs. Has its own yarn.lock. Communicates with the renderer via IPC.
src/service-worker/
The service worker for the web (browser) version of Postman. Handles offline caching. Lives in src/ because it shares browser context with the renderer.
src/visualizer-sandbox/
An isolated iframe sandbox for safely running user-provided visualizer scripts (from Postman test scripts). Isolation prevents scripts from accessing the main app.
Build and configuration
config/
Central configuration hub for the build system.
config/
├── webpack/ ← Webpack bundler configs
├── rspack/ ← Rspack (faster Webpack alternative) configs
├── eslint/ ← ESLint rule configurations
├── environments/ ← Environment-specific variables
├── alias.js ← Import alias definitions (@@renderer, @postman-app/*)
├── teams.json ← Team code ownership mapping
└── version.json ← Current app version (productVersion, uiVersion)
starship/
Electron build target configurations per environment. Each JSON file defines the app name, icons, build directory, and URL protocol for one environment.
starship/
├── dev.json ← PostmanDev (local development)
├── stage.json ← PostmanStage (staging)
├── prod.json ← Postman (production)
├── beta.json ← PostmanBeta
├── canary.json ← PostmanCanary
├── enterprise/ ← Enterprise builds
└── local.json ← Local overrides
"Starship" is an internal codename — the name gives no hint about what these files do. A future rename to electron-targets/ is recommended.
tools/
Custom Nx generators and developer tooling.
tools/
├── generator/ ← Custom Nx generators
│ ├── library ← Scaffold a new Nx lib
│ ├── mark-lib-coupled ← Tag a package as monolith-coupled
│ └── mark-lib-decoupled ← Tag a package as fully decoupled
├── eslint-rules/ ← Custom ESLint rules
├── react-migration-suite/ ← Tools for React class → hooks migration
└── milestone-runner/ ← CI milestone automation
scripts/
CI and automation scripts organized by purpose — circular dependency checking, code quality checks, CSP validation, enterprise release scripts, ephemeral test management.
resources/
Static assets for Electron packaging — app icons for all platform/environment/size combinations (macOS, Windows, Linux), and Credits.rtf for macOS.
Testing
tests/ (legacy) and tests-v2/ (current)
The repo currently has both tests/ (older infrastructure) and tests-v2/ (Playwright-based, the future). New E2E tests should go in tests-v2/. The migration is ongoing.
tests-v2/uses Playwright with Allure reporting — this is the target state- Unit and integration tests live co-located with the packages they test
i18n and types
locales/
Translation files consumed by platform-libs/i18n-sdk. Currently supports English (en-US/) and Japanese (ja/). All user-facing strings must go through i18n — no hardcoded English strings in UI components.
global-types/ and types/
TypeScript type declarations for assets (image imports, CSS modules, SVG files) and global type definitions shared across the codebase.
Legacy and unclear boundaries ⚠️
These directories exist at the repo root for historical reasons. Their placement is not ideal.
| Directory | What it is | Better home |
|---|---|---|
packages/ | Squad-organized packages (collaboration/, runtime/, etc.) | Merge into views/, ui-features/, data/ with squad namespacing |
module-framework/ | Internal module loading system | Should be in platform-libs/ |
postman/ | Core Postman data model globals | Should be in platform-libs/ or src/ |
postman-module-cli/ | CLI tool for module management | Should be in tools/ |
plugins/ | Pre-bundled plugin registry | Single JSON file — should be in config/ |
npm/ | Legacy build scripts | Should be merged into scripts/ |
See Architecture recommendations for the full improvement plan.