Skip to content
ConceptForDeveloperWith or without Foxden Admin

Repository layout ​

This page shows you where each part of Foxden lives in the repository, so you can find the code behind what you want to change.

The repository holds every app, the code they share, the foxden command line and this site. Each app is its own project with its own dependencies and lockfile; the shared code reaches each app through a symbolic link.

At the top ​

FolderWhat it holds
products/One folder per app.
packages/Code and images the apps share.
tools/The foxden command line and the component showroom.
docs/portal/This site. See Write a docs page.
scripts/Install, check and demo scripts for working on the code.
demo/The local demo's compose file and its fictional seed data.
.github/Issue templates and the checks that run on a pull request.

The apps: products/ ​

FolderAppNotes
products/admin/apps/authFoxden AdminThe console, sign-in, the AI and MCP gateways.
products/crmFennec
products/arcticArcticUses pnpm. bot-service/ is the notetaker that joins meetings; stt/ is the speech-to-text service (Python).
products/corsacCorsaclib/seal/ holds the sealing and verification of signed PDFs.
products/pampasPampaspackages/core is its form engine (schema, logic, limits); packages/react renders a form. Each has its own lockfile.
products/communicationsCulpeo
products/capeCape
products/libraryLibrary

Most apps are Next.js apps written in TypeScript, and each folder follows a similar shape:

  • a package.json with dev and test scripts (and typecheck in every app but Arctic), and db:migrate for its database;
  • a Dockerfile, and the compose file foxden installs on a server (docker-compose.deploy.yml; Arctic's is docker-compose.yml and Corsac's is compose.prod.yaml);
  • deploy/ with the app's backup and restore scripts;
  • its database migrations, and an example environment file that names every setting the app reads;
  • mcp-contract.json, the committed list of the app's agent tools. A test fails when the tools change and the file does not, and Agent tools is generated from it;
  • packages/shared and packages/brand: symbolic links to the shared code below.

Inside the code, the apps use their own ids in some places: Fennec is fennec (folder crm), Arctic is recall, Culpeo is communications, and Admin is management.

Shared code: packages/ ​

FolderWhat it is
packages/sharedThe code every app uses, written once. It has its own lockfile.
packages/brandThe component library every app's screens are built from: React components on fx-* classes and the kit stylesheets. llms.txt lists every component.
packages/rendererThe HTML-to-PDF service (headless Chromium).
packages/updaterThe updater container every app's stack runs, in POSIX shell.
packages/postgresThe suite's Postgres 17 image, with pgvector added.

The main folders of packages/shared/src:

FolderWhat it decides
auth/Signing in through Admin, sessions, grants and enforcement of the access feed.
access/Levels, sharing levels, Library's space rights, the settings layout, and the words screens use for all of them (copy.ts).
contracts/What apps and Admin say to each other: the feeds, the workspace and people profiles, events, activity, file filing.
mcp/The MCP server core, the record of agent calls, and OAuth for assistants.
storage/productObjectStore, and the signed connection to Library's file store.
jobs/The one job queue: outbox, worker and retry schedule.
integrations/Google and Microsoft: which scopes each feature asks for, and the API clients.
http/Security headers, rate limits, health answers.
email/Building and sending every email.
render/The client every app uses to print a PDF with the renderer.
env/The settings keys apps share, and the links between apps derived from the box key.

See The parts of Foxden for how these fit together at run time.

The command line: tools/foxden ​

foxden installs and runs Foxden on a server. It is written in TypeScript for Bun.

  • src/commands/ holds one file (or folder) per command.
  • manifests/ holds one YAML file per app: its compose files, sizes, address, health check, backup and every settings key with how it is filled. The generated Settings and Server sizes pages read them.
  • src/control/ and control/ are the control service that Admin's console calls.
  • scripts/check.sh is the command line's own check: typecheck, then tests with a floor on test coverage.

tools/den-showroom shows every component of packages/brand as each app wears it.

Scripts: scripts/ ​

ScriptWhat it does
scripts/bootstrap.shInstalls an app's dependencies together with packages/shared.
scripts/verify.shRuns typecheck and unit tests for what you changed.
scripts/_products.shThe table both read: each row's folders, how to install it and how to check it. The pull request checks read it too.
scripts/demo.shRuns the whole suite on your computer with demo data.
scripts/backup-restore.shThe backup and restore flow that the deploy/ scripts of Admin, Fennec, Corsac, Pampas and Culpeo run.

See Set up a development machine to use them.

Foxden is open source under Apache-2.0.