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
| Folder | What 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/
| Folder | App | Notes |
|---|---|---|
products/admin/apps/auth | Foxden Admin | The console, sign-in, the AI and MCP gateways. |
products/crm | Fennec | |
products/arctic | Arctic | Uses pnpm. bot-service/ is the notetaker that joins meetings; stt/ is the speech-to-text service (Python). |
products/corsac | Corsac | lib/seal/ holds the sealing and verification of signed PDFs. |
products/pampas | Pampas | packages/core is its form engine (schema, logic, limits); packages/react renders a form. Each has its own lockfile. |
products/communications | Culpeo | |
products/cape | Cape | |
products/library | Library |
Most apps are Next.js apps written in TypeScript, and each folder follows a similar shape:
- a
package.jsonwithdevandtestscripts (andtypecheckin every app but Arctic), anddb:migratefor its database; - a
Dockerfile, and the compose filefoxdeninstalls on a server (docker-compose.deploy.yml; Arctic's isdocker-compose.ymland Corsac's iscompose.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/sharedandpackages/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/
| Folder | What it is |
|---|---|
packages/shared | The code every app uses, written once. It has its own lockfile. |
packages/brand | The component library every app's screens are built from: React components on fx-* classes and the kit stylesheets. llms.txt lists every component. |
packages/renderer | The HTML-to-PDF service (headless Chromium). |
packages/updater | The updater container every app's stack runs, in POSIX shell. |
packages/postgres | The suite's Postgres 17 image, with pgvector added. |
The main folders of packages/shared/src:
| Folder | What 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/andcontrol/are the control service that Admin's console calls.scripts/check.shis 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/
| Script | What it does |
|---|---|
scripts/bootstrap.sh | Installs an app's dependencies together with packages/shared. |
scripts/verify.sh | Runs typecheck and unit tests for what you changed. |
scripts/_products.sh | The 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.sh | Runs the whole suite on your computer with demo data. |
scripts/backup-restore.sh | The 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.