|
| 1 | +# AI Agent Guidance for the FDC3 Repository |
| 2 | + |
| 3 | +This document provides guidance for AI coding agents working on the FDC3 monorepo. It describes the repository structure, key relationships between modules, build and test conventions, and common pitfalls. |
| 4 | + |
| 5 | +For agent-specific configuration, see: |
| 6 | + |
| 7 | +- **Amazon Q**: [`.amazonq/rules/fdc3.md`](.amazonq/rules/fdc3.md) |
| 8 | +- **Kiro**: [`.kiro/steering.md`](.kiro/steering.md) |
| 9 | +- **GitLab Duo**: [`.gitlab/agents.md`](.gitlab/agents.md) |
| 10 | + |
| 11 | +## Repository Overview |
| 12 | + |
| 13 | +FDC3 is an open standard for financial desktop interoperability. This repository is an **npm workspaces monorepo** containing the standard's TypeScript type definitions, JSON schemas, reference implementations, test suites, documentation website, and developer tooling. |
| 14 | + |
| 15 | +The root `package.json` defines the workspace list and the build order is implicit in the dependency graph (see below). |
| 16 | + |
| 17 | +## Module Map and Dependency Graph |
| 18 | + |
| 19 | +``` |
| 20 | +Build order (left to right): |
| 21 | +
|
| 22 | +fdc3-context ──┐ |
| 23 | + ├─► fdc3-standard ──┬─► fdc3-agent-proxy ──┬─► fdc3-get-agent ──► fdc3 ──► fdc3-commonjs |
| 24 | +fdc3-schema ───┘ │ │ |
| 25 | + └─► fdc3-web-impl ──────┘ |
| 26 | + └─► demo, fdc3-workbench, fdc3-conformance |
| 27 | +``` |
| 28 | + |
| 29 | +| Module | Path | npm Package | Role | |
| 30 | +|--------|------|-------------|------| |
| 31 | +| `fdc3-context` | `packages/fdc3-context` | `@finos/fdc3-context` | JSON schemas for FDC3 context types → generates `ContextTypes.ts` | |
| 32 | +| `fdc3-schema` | `packages/fdc3-schema` | `@finos/fdc3-schema` | DACP and bridging protocol JSON schemas → generates `BrowserTypes.ts` and `BridgingTypes.ts` | |
| 33 | +| `fdc3-standard` | `packages/fdc3-standard` | `@finos/fdc3-standard` | TypeScript interfaces for the FDC3 API (e.g. `DesktopAgent`, `Channel`, `ContextMetadata`) | |
| 34 | +| `fdc3-agent-proxy` | `packages/fdc3-agent-proxy` | `@finos/fdc3-agent-proxy` | Client-side proxy implementing the FDC3 DACP (Desktop Agent Communication Protocol) | |
| 35 | +| `fdc3-get-agent` | `packages/fdc3-get-agent` | `@finos/fdc3-get-agent` | `getAgent()` and `fdc3Ready()` — web connection protocol implementation | |
| 36 | +| `fdc3-web-impl` | `toolbox/fdc3-for-web/fdc3-web-impl` | `@finos/fdc3-web-impl` | Server-side (Desktop Agent side) DACP implementation | |
| 37 | +| `fdc3` | `packages/fdc3` | `@finos/fdc3` | Roll-up package: the main entry point for apps using FDC3 | |
| 38 | +| `fdc3-commonjs` | `packages/fdc3-commonjs` | `@finos/fdc3-commonjs` | CommonJS backwards-compatibility roll-up | |
| 39 | +| `testing` | `packages/testing` | `@finos/testing` | Shared Cucumber step definitions and test utilities (not published) | |
| 40 | +| `demo` | `toolbox/fdc3-for-web/demo` | — | Reference Desktop Agent implementation | |
| 41 | +| `fdc3-workbench` | `toolbox/fdc3-workbench` | — | Interactive FDC3 testing tool | |
| 42 | +| `fdc3-conformance` | `toolbox/fdc3-conformance` | — | Conformance test suite definitions | |
| 43 | + |
| 44 | +## Critical Relationships |
| 45 | + |
| 46 | +### 1. Schema → Generated Types → Standard Interfaces |
| 47 | + |
| 48 | +This is the most important relationship to understand. Changes flow in one direction: |
| 49 | + |
| 50 | +``` |
| 51 | +JSON Schema files Generated TypeScript Hand-written interfaces |
| 52 | +───────────────── ──────────────────── ─────────────────────── |
| 53 | +packages/fdc3-schema/ packages/fdc3-schema/ packages/fdc3-standard/ |
| 54 | + schemas/api/*.schema.json ──► generated/api/BrowserTypes.ts src/api/*.ts |
| 55 | + schemas/bridging/*.json ──► generated/bridging/BridgingTypes.ts |
| 56 | +packages/fdc3-context/ |
| 57 | + schemas/context/*.json ──► packages/fdc3-context/ |
| 58 | + generated/ContextTypes.ts |
| 59 | +``` |
| 60 | + |
| 61 | +**Key rules:** |
| 62 | +- `BrowserTypes.ts` and `BridgingTypes.ts` are **generated** — never edit them directly. |
| 63 | +- The JSON schemas in `fdc3-schema` define the wire protocol (DACP) message shapes. |
| 64 | +- The TypeScript interfaces in `fdc3-standard` define the **public API** that apps code against. |
| 65 | +- These two must be kept in sync **manually**. When you add a field to a schema, the corresponding `fdc3-standard` interface must be updated, and vice versa. |
| 66 | +- Schema generation uses `quicktype` via `s2tQuicktypeUtil.cjs`. Run `npm run build` in `fdc3-schema` to regenerate. |
| 67 | +- The central schema file `packages/fdc3-schema/schemas/api/api.schema.json` contains shared type definitions (e.g. `ContextMetadata`, `AppIdentifier`) referenced by individual message schemas. |
| 68 | + |
| 69 | +### 2. Standard Interfaces → Proxy (Client) and Web-Impl (Server) |
| 70 | + |
| 71 | +``` |
| 72 | +fdc3-standard (interfaces) |
| 73 | + │ |
| 74 | + ├──► fdc3-agent-proxy (client-side implementation) |
| 75 | + │ Implements Channel, DesktopAgent etc. |
| 76 | + │ Sends DACP request messages, receives response/event messages |
| 77 | + │ |
| 78 | + └──► fdc3-web-impl (server-side implementation) |
| 79 | + Receives DACP request messages, sends response/event messages |
| 80 | + Handlers: BroadcastHandler, IntentHandler, OpenHandler |
| 81 | +``` |
| 82 | + |
| 83 | +When adding a new API method or modifying message payloads, you typically need to touch: |
| 84 | +1. The JSON schema (wire format) |
| 85 | +2. The `fdc3-standard` interface (public API) |
| 86 | +3. The `fdc3-agent-proxy` implementation (client sends/receives) |
| 87 | +4. The `fdc3-web-impl` handler (server receives/sends) |
| 88 | +5. Tests in both proxy and web-impl |
| 89 | +6. Documentation in `website/docs/api/` |
| 90 | + |
| 91 | +### 3. API Documentation ↔ Standard Interfaces |
| 92 | + |
| 93 | +The website documentation in `website/docs/api/ref/` mirrors the `fdc3-standard` interfaces: |
| 94 | + |
| 95 | +| Interface file | Documentation file | |
| 96 | +|---|---| |
| 97 | +| `src/api/DesktopAgent.ts` | `website/docs/api/ref/DesktopAgent.md` | |
| 98 | +| `src/api/Channel.ts` | `website/docs/api/ref/Channel.md` | |
| 99 | +| `src/api/Types.ts` | `website/docs/api/ref/Types.md` | |
| 100 | +| `src/api/ContextMetadata.ts` | `website/docs/api/ref/Metadata.md` | |
| 101 | +| `src/api/Errors.ts` | `website/docs/api/ref/Errors.md` | |
| 102 | +| `src/api/Events.ts` | `website/docs/api/ref/Events.md` | |
| 103 | +| `src/api/PrivateChannel.ts` | `website/docs/api/ref/PrivateChannel.md` | |
| 104 | + |
| 105 | +The DACP wire protocol is documented in `website/docs/api/specs/desktopAgentCommunicationProtocol.md`. |
| 106 | + |
| 107 | +## Build and Test |
| 108 | + |
| 109 | +### Building |
| 110 | + |
| 111 | +```bash |
| 112 | +npm install # from repo root |
| 113 | +npm run build # builds all workspaces in dependency order |
| 114 | +``` |
| 115 | + |
| 116 | +To build a single module, `cd` into it and run `npm run build`. But remember: if you changed a dependency (e.g. `fdc3-schema`), you must rebuild it first. |
| 117 | + |
| 118 | +### Testing |
| 119 | + |
| 120 | +```bash |
| 121 | +npm run test # runs all workspace tests |
| 122 | +``` |
| 123 | + |
| 124 | +Or test individual modules: |
| 125 | + |
| 126 | +```bash |
| 127 | +cd packages/fdc3-agent-proxy && npm test |
| 128 | +cd toolbox/fdc3-for-web/fdc3-web-impl && npm test |
| 129 | +``` |
| 130 | + |
| 131 | +**Test framework:** Both `fdc3-agent-proxy` and `fdc3-web-impl` use **Cucumber/Gherkin** via `quickpickle` + `vitest`. Test files are `.feature` files in `test/features/`, with step definitions in `test/step-definitions/`. |
| 132 | + |
| 133 | +The `packages/testing` module provides shared generic step definitions (e.g. `I call "{obj}" with "methodName"`) and the `matchData` utility for asserting on message contents. |
| 134 | + |
| 135 | +**Coverage policy:** Contributions to `fdc3-agent-proxy`, `fdc3-get-agent`, `fdc3-standard`, and `fdc3-web-impl` must maintain or improve test coverage. Coverage is reported in PR comments. |
| 136 | + |
| 137 | +### Test Gotchas |
| 138 | + |
| 139 | +- **UUID counter in tests:** The test `ServerContext` uses a sequential UUID generator (`uuid0`, `uuid1`, ...). Adding new `sc.createUUID()` calls in handler code shifts all subsequent UUID values in existing tests. If tests fail after your change with UUID mismatches, update the expected values. |
| 140 | +- **Feature file structure:** Each `.feature` file has a `Background` section that sets up the test world. Steps reference objects by name using `{curly-brace}` syntax (e.g. `{api}`, `{result}`, `{channel1}`). |
| 141 | +- **`matchData` function:** Used in step definitions to assert on nested object properties using dot-notation paths (e.g. `payload.context.type`). |
| 142 | + |
| 143 | +## Code Style and Conventions |
| 144 | + |
| 145 | +- **Formatting:** Prettier with config in root `package.json` — 120 char line width, single quotes, trailing commas (es5), 2-space indent. |
| 146 | +- **TypeScript:** Strict mode. `NodeNext` module resolution. Target `ESNext`. All modules use `"type": "module"` (ESM). |
| 147 | +- **Imports:** Use `.js` extensions in import paths (required for ESM with NodeNext resolution), e.g. `import { Foo } from './Foo.js'`. |
| 148 | +- **License headers:** All source files must include the Apache 2.0 SPDX header. |
| 149 | +- **Linting:** ESLint with Prettier integration. Run `npm run lint` in individual packages. |
| 150 | +- **Pre-commit:** Husky runs `prettier --write` via `lint-staged` on all staged files. |
| 151 | + |
| 152 | +## Common Change Patterns |
| 153 | + |
| 154 | +### Adding a new field to an existing DACP message |
| 155 | + |
| 156 | +1. Update the relevant `.schema.json` file(s) in `packages/fdc3-schema/schemas/api/` |
| 157 | +2. If the field uses a shared type, update `api.schema.json` |
| 158 | +3. Rebuild `fdc3-schema` (`cd packages/fdc3-schema && npm run build`) to regenerate `BrowserTypes.ts` |
| 159 | +4. Update the corresponding `fdc3-standard` TypeScript interface if the field is part of the public API |
| 160 | +5. Update `fdc3-agent-proxy` to send/receive the new field |
| 161 | +6. Update `fdc3-web-impl` handler to process the new field |
| 162 | +7. Add tests in both `fdc3-agent-proxy` and `fdc3-web-impl` |
| 163 | +8. Update documentation in `website/docs/api/` |
| 164 | +9. Add a CHANGELOG entry under `[Unreleased]` |
| 165 | + |
| 166 | +### Adding a new API method |
| 167 | + |
| 168 | +1. Add the method signature to the relevant interface in `fdc3-standard` (e.g. `Channel.ts`, `DesktopAgent.ts`) |
| 169 | +2. If it requires new DACP messages, create request/response schema files and reference them from `api.schema.json` |
| 170 | +3. Implement in `fdc3-agent-proxy` (client side) |
| 171 | +4. Implement in `fdc3-web-impl` (server side handler) |
| 172 | +5. Add Cucumber scenarios in both test suites |
| 173 | +6. Document in `website/docs/api/ref/` and update `website/docs/api/specs/desktopAgentCommunicationProtocol.md` |
| 174 | +7. Export from `fdc3-standard/src/index.ts` if it's a new type |
| 175 | +8. Add CHANGELOG entry |
| 176 | + |
| 177 | +### Modifying context types |
| 178 | + |
| 179 | +Context type schemas live in `packages/fdc3-context/schemas/context/`. Changes regenerate `ContextTypes.ts`. These are independent of the DACP protocol schemas. |
| 180 | + |
| 181 | +## Version Management |
| 182 | + |
| 183 | +All workspace packages share the same version number (currently `2.2.2`). Use `syncpack` to keep versions consistent: |
| 184 | + |
| 185 | +```bash |
| 186 | +npm version <new-version> --workspaces |
| 187 | +npm run syncpack |
| 188 | +``` |
| 189 | + |
| 190 | +## Files You Should Always Update |
| 191 | + |
| 192 | +When making non-trivial changes: |
| 193 | + |
| 194 | +- **`CHANGELOG.md`** — Add entries under `[Unreleased]` in the appropriate section (`Added`, `Changed`, `Deprecated`, `Fixed`). |
| 195 | +- **`website/docs/`** — Keep documentation in sync with API and schema changes. |
| 196 | +- **Tests** — Maintain or improve coverage. Both Cucumber feature files and step definitions may need updates. |
| 197 | + |
| 198 | +## What NOT to Edit |
| 199 | + |
| 200 | +- `packages/fdc3-schema/generated/` — These files are generated. Edit the `.schema.json` sources instead. |
| 201 | +- `packages/fdc3-context/generated/` — Same: edit the context schemas. |
| 202 | +- `website/versioned_docs/` and `website/versioned_sidebars/` — These are snapshots of documentation from previous FDC3 releases. Only edit `website/docs/` for current work. Do not edit these unless a correction is specifically requested. |
| 203 | +- `website/static/schemas/` — Snapshots of JSON schemas from previous FDC3 releases. Do not edit unless a correction is specifically requested. |
| 204 | +- `packages/fdc3/` and `packages/fdc3-commonjs/` — These are roll-up packages with only `import`/`export` statements. Don't add logic here. |
0 commit comments