Repository navigation
Development Setup
How to set up a machine to work on this repo: the tools you need, how the workspaces fit together, the build order that every cdk command depends on, how to run each part (package tests, deploy app, web frontend, Storybook, end-to-end tests, desktop app), and the checks to run before a commit. For what the repo ships and how it is released see Releasing; for the system itself see Architecture.
- Node.js 20 or newer (
enginesin the package). CI and the reference machine run Node 22 LTS. - The AWS CLI and the AWS CDK CLI, for anything that deploys.
aws-cdk-lib2.263 or newer andconstructs10.x are peer dependencies of the package; see Requirements. - AWS profiles: one profile per account. Deploys export
AWS_PROFILEfor the hub account before runningcdkthere, and switch to a workload account's profile for that account's target and connector stacks. - The frontend is Angular 20; Storybook and Playwright come with its
npm install. Playwright also needsnpx playwright install chromiumonce per machine.
| Path | What it is |
|---|---|
packages/infra-client/ |
The product: stacks, constructs, Lambda code, Jest suites, pack scripts. Compiled to dist/, Lambdas prebundled into assets/
|
frontend/ |
The Angular web app; its build output is copied into the package's assets/web at pack time |
desktop/ |
The Electron client; not in the npm package |
infra/ |
FNTIO's own deployment: config/project.ts, bin/app.ts, PipelineStack, TestbedStack, the import CLI, the ops runbooks |
samples/ |
Consumer-voice CDK apps importing the package |
The repo root is an npm workspace over packages/* and infra. Install at the root only. npm install inside infra/ tries to fetch the private, unpublished @fntio/infra-client from the registry and fails with E404; the root install links it from packages/. frontend/ and desktop/ are separate installs (npm ci / npm install in their own directory).
npm ci # repo root: packages/* and infra
npm test # package (stacks + lambdas) and deploy app
npm --prefix frontend run build # BEFORE any cdk command
npm run build # package dist/, if infra/ or samples/ complain about missing types- Every
cdkcommand synthesizes the whole app, and synth throws "Web assets not found" withoutfrontend/dist. Build the frontend first, always. -
infra/andsamples/resolve the package's types from its compileddist/;npm run buildat the root rebuilds it (cdk synth does so automatically). - Lambda bundles are prebuilt into
packages/infra-client/assets/byscripts/bundle-lambdas.mjs;cdk.jsonruns it before every synth andnpm testruns it viapretest. Nothing to do by hand. - The first deploy needs
cdk bootstrapin the hub region and in us-east-1 (WebCertStack always deploys there). Commands in Install, test, deploy.
cd packages/infra-client && npx tsc --noEmit && npm testJest is transpile-only (tsconfig.jest.json) and bounded to half the cores and 2 GB per worker, so tsc --noEmit is the type check. The suite includes lib/__tests__/cdk-nag.test.ts, which synthesizes every hub stack plus a target-account stack and fails on any unsuppressed AwsSolutions finding; it skips itself when the frontend build or Lambda bundles are missing. Deliberate trade-offs are suppressed in that test with a reason.
cd infra && npx tsc --noEmit && npm testCovers the deploy wiring and the import CLI. Run it whenever infra/ changed.
cd frontend
npm install
npm start # ng serve → http://localhost:4200, hot reloadSign-in is the app's own /login page against the real Cognito pool; there is deliberately no local auth bypass. public/config.json is dev-only (WebStack generates its own) and holds the pool and client ids plus the feature flags (passkey, mfa, network, devShares, federation, plugins); keep it matching the deployment you develop against. API calls go to /api/* through proxy.conf.mjs; DEV_API_URL overrides the target, and DEV_API_URL=http://localhost:3000 points at a local npm run dev Express instance. Unit tests: npm test (Karma/Jasmine). Details: Develop.
cd frontend
npm run storybook -- --no-open # always port 6008 (angular.json's storybook target)Every story renders the real component class, never a hand-copied template. Page stories render the shipped page component with faked services. A long-running Storybook dev server must be restarted to pick up global CSS or angular.json changes. Sidebar structure and the tokens legend rules: Storybook.
frontend/e2e/ drives the deployment E2E_BASE_URL points at in a real browser: sign-in, every route, key flows, deep links and screenshot baselines. E2E_BASE_URL is required because the suite signs in and mutates real data. Setup once per machine: invite a dedicated e2e admin (and optionally a non-admin) through the app, cp .env.e2e.example .env.e2e and fill it in (untracked, never commit it), npx playwright install chromium.
npm run e2e # full suite (headless)
npm run e2e:ui # Playwright UI mode — watch/debug tests
npm run e2e:update # re-approve screenshot baselines after an intended redesign
npm run e2e:report # open the last HTML reportBaselines are platform-specific (rendered on macOS). Re-approve them deliberately, never blind. Full notes: E2E (Playwright).
cd desktop
npm install
npm startPoint the first tab at a deployed site, or at http://localhost:4200 with ng serve running (localhost is the one http exception). Two gotchas: macOS Gatekeeper deletes the unsigned dev Electron binary (reinstall, clear quarantine, ad-hoc sign; steps in macOS: "Electron … contains malware"), and a shell with ELECTRON_RUN_AS_NODE=1 (VS Code's extension host) must launch with env -u ELECTRON_RUN_AS_NODE npm start. After a frontend deploy, quit via tray → Quit and remove credentials and relaunch; a plain reload can serve the old bundle. The main-process files (main.js, credentials-writer.js, tailnet.js, tray.js, preload.js, ...) are listed under Files.
cd packages/infra-client && npx tsc --noEmit && npm test # always
cd infra && npx tsc --noEmit && npm test # if infra/ changed
cd frontend && npx tsc --noEmit && npm run build # if frontend changed (build when templates/styles changed)
node --check desktop/*.js # if desktop changed- Commits go straight to
main, and pushingmaindeploys FNTIO's hub stacks (see Releasing). - Large or risky changes (a new service, auth or grants logic, anything touching vending or cross-account trust) get a code review before they are committed.
- New API services get a Jest suite mirroring the existing pattern (
__tests__/<name>Service.test.tswith mocked AWS clients, plus route coverage inapp.test.tsvia supertest). New routes or key user flows get an e2e spec infrontend/e2e/; shared frontendutil/code gets a spec. - A PR that touches frontend UI passes the Storybook sync check first: every routed page has a
Pages/story rendering the real component, story args match real call sites, and no page markup is hand-copied.
packages/infra-client/openapi.yaml is the portal's HTTP API contract and ships in the tarball. The route inventory is drift-tested against the mounted routes (openapi.test.ts), so any API route change must update openapi.yaml or the test fails.
The same test pins the spec's info.version to package.json, so a version bump must bump both. Response shapes are maintained by hand alongside the code; see HTTP API.
Source: wiki/ in FNTIO/aws-infrastructure-client, mirrored by the Wiki workflow. Edit the files there; changes made on this site are overwritten by the next sync.
Start here
Use
How it works
Operate
Contribute