Client-Repo Conventions
How to structure the repository of an APEX-powered platform. These conventions come from running multiple venture builds on APEX; following them keeps your integration reviewable, your credentials safe, and your platform aligned with the engine as it evolves.
What belongs in your repo — and what does not
Apply the Engine/Client Split to the repository itself:
| In your repo | Not in your repo |
|---|---|
| Domain agents, prompts, and pipeline definitions | Retrieval/search infrastructure |
| Your users, identity, and access model | Document rendering or PDF engines |
| Workflow, stage gates, dashboards | Claim-verification logic |
| Your API + backend-for-frontend that calls APEX | Messaging-provider integrations |
| Thin, typed APEX client wrappers | Vendor LLM SDKs (use the platform's agent execution / LLM dispatch so cost metering stays unified) |
If you find yourself building a capability the product chapters already describe, stop and consume it instead.
The docs/apex-adr/ folder
Every APEX client platform carries a docs/apex-adr/ folder — the standing record of how this platform uses APEX:
- Architecture decision records for your integration choices (which products, which tenancy model, how users map to the tenant credential).
- A context diagram showing your platform against the APEX products it consumes.
- Your integration contract — tenant slug, enabled products, channels and sender identities, corpus ownership, environments.
Ask your platform contact for the reference template. This folder is what a new engineer — or an APEX support engineer — reads first.
Credentials and environments
- APEX credentials live server-side only, injected via environment (see suggested variable names in the Quickstart); never in source control, never in client bundles.
- One credential set per environment: test-class against Development, production-class against Production. Wire base URLs and the token URL from configuration, not constants.
- Rotation is a deploy-time concern you should rehearse: new key in, deploy, old key revoked — see Authentication.
Configuration over code
Models, channels, templates, and verification behaviour are tenant configuration held by Forge, not constants in your code. Consume them as runtime state: your application should tolerate entitlements appearing, changing, or disappearing between calls without a redeploy (Tenancy rules). Hardcoding a model name or channel list into your codebase is the most common way client platforms drift.
Contract pinning
- Vendor the OpenAPI specifications you consume (or pin their versions) and generate your client types from them.
- Add a CI check against each product's
GET /forge-contract.jsonso surface drift fails your build, not your production traffic. - Respect availability badges: Available surfaces are safe dependencies; Preview surfaces get an abstraction layer you can rework; Planned surfaces are built behind a flag against the pinned contract.
Runtime discipline
- First-class fail-closed states. "Tenant not configured" (
404) and "not entitled" (403) get real screens/messages, not generic error toasts. - Correlation middleware. Every outbound APEX call carries your
X-Correlation-ID; every inbound webhook is verified (X-Echo-Signature) and handled idempotently. - One retry policy. Centralise the retry rules in your APEX client wrapper; do not scatter ad-hoc retries through feature code.
- Cost ledger. Log per-call cost as responses arrive and reconcile per Usage & Cost.