--- url: https://docs.codefox.ai/contribute/repository-tour.md --- # 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](/contribute/write-docs). | | `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.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](/reference/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/` | 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](/how-it-works/big-picture) 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](/reference/settings/) and [Server sizes](/reference/sizing) 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/` | 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](/contribute/development-setup) to use them. ## Related * [Make a change and open a pull request](/contribute/make-a-change)