pangolin/docs/repo-map.md

Repo map

A quick map of where things live, so you can go straight to the right file. Path aliases (from tsconfig*.json):

Alias	Resolves to	Use from
@server/*	server/*	anywhere (server and UI, for shared types)
@app/*, @/*	src/*	UI
@test/*, @cli/*	test/*, cli/*	tests, CLI
#private/*	server/private/*	only inside server/private/
#dynamic/*	server/private/* (enterprise/saas) or server/* (oss)	outside server/private/ when you need the private implementation on paid builds
#open/*, #closed/*	server/*, server/private/*	internal to the esbuild #dynamic switcher; don't use

Top level

server/          Express API server (TypeScript, bundled with esbuild.mjs)
src/             Next.js dashboard (App Router)
messages/        i18n JSON. Only en-US.json is edited by hand; Crowdin generates the others
config/          config.yml (+ privateConfig.yml on enterprise), example configs
cli/             pangctl CLI
install/         installer (Go)
docs/            Developer docs for agents and contributors (this folder)
test/            Shared test helpers
scripts/         Build/test scripts (run-tests.mjs)
esbuild.mjs      Server bundler; holds the #private guard and the #dynamic switcher
drizzle.*.ts     Drizzle configs (drizzle.config.ts is generated by set:pg / set:sqlite)

Generated and gitignored, switched by npm scripts: server/build.ts (npm run set:oss|enterprise|saas), tsconfig.json (copied from tsconfig.{oss,enterprise,saas}.json), server/db/index.ts, drizzle.config.ts, server/setup/migrations.ts (npm run set:sqlite|pg).

server/

server/
  index.ts                 Entry. Boots config, migrations, and all servers below
  apiServer.ts             External API (dashboard + user API). Routes: #dynamic/routers/external
  internalServer.ts        Internal API (Next server-side fetches, badger). Routes: #dynamic/routers/internal
  integrationApiServer.ts  Integration API (API keys, OpenAPI docs). Routes: #dynamic/routers/integration
  aiGatewayServer.ts       AI gateway
  nextServer.ts            Serves the Next app
  openApi.ts               OpenAPITags enum + registry
  build.ts                 GENERATED: `build` = "oss" | "enterprise" | "saas"
  auth/                    actions.ts (ActionsEnum), sessions/, password, totp, canUserAccess*.ts
  middlewares/             verify*Access.ts, verifyUserHasAction, verifyLimits, logActionAudit (stub)
    integration/           verifyApiKey*.ts counterparts for the integration API
  routers/                 One folder per entity (see below) + router files:
    external.ts            Dashboard/user routes (session auth)
    internal.ts            Internal routes
    integration.ts         API-key routes (needs public-/private-resource aliases)
    hybrid.ts              Hybrid/remote node routes
  private/                 ENTERPRISE/SAAS ONLY (see docs/enterprise-private-code.md)
    routers/{external,internal,integration,hybrid}.ts   Import the public routers and add private routes
    routers/<entity>/      Private-only handlers
    lib/                   Private implementations of #dynamic modules, config, redis, stripe, billing
    lib/readConfigFile.ts  privateConfigSchema (private config values)
    lib/config.ts          `privateConfig` singleton
    middlewares/           Real logActionAudit etc.
  lib/
    config.ts              `config` singleton: config.getRawConfig()
    readConfigFile.ts      Public config zod schema
    crypto.ts              encrypt/decrypt (AES, keyed by server.secret)
    blueprints/            Blueprint schema (types.ts) + apply (publicResources.ts, privateResources.ts) + export
    traefik/               Traefik dynamic config generation for public resources
    billing/tierMatrix.ts  TierFeature -> tiers; used by server and UI paywalls
    response.ts            `response()` envelope helper
    validators.ts, schemas.ts  Shared zod validators
    deleteResource.ts, deleteSiteResource.ts, deleteOrg.ts   Cascading delete helpers
    rebuildClientAssociations.ts   Recomputes client <-> site resource access
  db/
    index.ts               GENERATED: re-exports ./pg or ./sqlite + `driver`
    pg/schema/{schema,privateSchema}.ts       Postgres tables
    sqlite/schema/{schema,privateSchema}.ts   SQLite tables (must mirror pg)
  setup/                   Startup tasks + migrations (scriptsPg/, scriptsSqlite/). Don't edit unless asked
  emails/                  React email templates
  routers/newt/            Messages to/from Newt (site connector) over websockets
  routers/olm/             Messages to/from Olm (client connector)
  routers/gerbil/          Exit node (WireGuard) coordination
  routers/badger/          Traefik auth plugin endpoints (verifySession)
  routers/traefik/         Traefik HTTP config provider
  routers/ws/              Websocket server (private/routers/ws for enterprise)

Entity routers (server/routers/<entity>/)

Each folder has index.ts (re-exports), one file per operation (createX.ts, getX.ts, listXs.ts, updateX.ts, deleteX.ts), and often types.ts / validation.ts. See docs/crud-endpoints.md.

Main ones: org, site, resource (public resources), siteResource (private resources), target (public resource targets), policy (resource policies), client, user, role, domain, idp, apiKeys, accessToken, blueprints, labels, redirect, aiProvider, aiBudget, virtualApiKey, auditLogs, certificates.

src/ (dashboard)

src/
  app/
    layout.tsx, navigation.tsx   Root layout; sidebar nav items (orgNavSections etc.)
    [orgId]/settings/            All org settings pages (one folder per section)
      layout.tsx                 Sidebar shell
      general/                   Org settings: layout.tsx (tabs) + page.tsx, security/, logs/, auth-page/
      resources/public/          Public resources: page.tsx (list), create/, [niceId]/<tab>/
      resources/private/         Private (site) resources: page.tsx, create/, [niceId]/<tab>/
      sites/, clients/, access/, domains/, api-keys/, blueprints/, ai-providers/, ...
      (private)/                 Route group for enterprise-only pages (billing, idp, license, policies, remote-exit-nodes)
    admin/                       Server admin pages
    auth/                        Login, signup, 2FA, resource auth pages
  components/
    ui/                          shadcn primitives (button, form, input, select, tabs, ...)
    Credenza.tsx                 Responsive modal (dialog on desktop, drawer on mobile). Use for every modal
    DismissableBanner.tsx        Help/info banner (wrapped by *Banner.tsx components)
    HorizontalTabs.tsx           Route-based tabs used in [id]/layout.tsx files
    Settings.tsx                 SettingsContainer / SettingsSection / ... layout primitives
    SettingsSectionTitle.tsx     Page title + description
    PaidFeaturesAlert.tsx        Paywall notice for tiered features
    ConfirmDeleteDialog.tsx      Type-the-name-to-delete Credenza
  contexts/ + providers/ + hooks/  Context per entity: OrgProvider/useOrgContext,
                                   ResourceProvider/useResourceContext,
                                   SiteResourceProvider/useSiteResourceContext, useEnvContext, usePaidStatus, ...
  lib/
    api/                         index.ts: createApiClient (client), `internal` (server components), formatAxiosError; cookies.ts: authCookieHeader
    pullEnv.ts                   Builds the Env object (flags etc.) from process.env for the UI

Fetching data

• Server components / layouts: internal.get<AxiosResponse<T>>(path, await authCookieHeader()), with internal from @app/lib/api and authCookieHeader from @app/lib/api/cookies. Use getCachedOrg / getCachedOrgUser from @app/lib/api/* for the org.
• Client components: const api = createApiClient(useEnvContext());, then api.get/put/post/delete. Errors go to toast({ variant: "destructive", description: formatAxiosError(e, t("...")) }).
• Response types are imported straight from the server router, e.g. import { GetResourceResponse } from "@server/routers/resource".