Public documentation for governed AI labor
SDKs/Governance/Connectors
Arx / Docs / Repository layout

Documentation

Repository layout

Project-Agent-trust-merge / REPO_LAYOUT.md

Project-Agent-trust-merge repo-root REPO_LAYOUT.md

This is the directory map. Use it before moving files around — many top-level dirs are coupled to deploy targets, and renaming or restructuring them breaks the deploy.

Deployable surfaces

| Surface | What deploys | Where from | Triggered by | |---|---|---|---| | ARX SaaS API | arxsec-api/ (FastAPI backend) | Aptible | .github/workflows/aptible.yml on push to main | | Workforce console | arxsec-api/frontend/ (Next.js) | Aptible | same workflow | | Workforce modeler | workforce-modeler/ (FastAPI) | Aptible | same workflow | | Atlas (customer-private) | atlas/ (FastAPI + Helm chart) | Customer's K8s cluster | .github/workflows/atlas-release.yml on tag atlas/v*.*.* (cosign-signed image to GHCR; customer mirrors before deploy) | | Marketing site | Root-level *.html files | Vercel | vercel.json rewrites | | Python SDK | sdks/agentvault-py/ | PyPI | .github/workflows/publish-agentvault.yml on tag agentvault-v* | | Documentation site | docs/ | GitBook | docs/SUMMARY.md is the TOC |

Don't move files in any of those paths without updating the matching deploy config.

Top-level directory map

Application code (deploy-coupled)

  • arxsec-api/ — FastAPI backend + Next.js frontend.
  • app/api/v1/ — route modules
  • app/core/ — domain logic (audit chain, sandbox pool,

cohort provisioner, approval SLA, etc.)

  • app/connectors/ — security + workforce connector adapters
  • app/runtime/ — sandbox pool + executor
  • supabase/migrations/ — DB schema (timestamp-prefixed)
  • tests/ — pytest suite
  • frontend/src/app/(dashboard)/ — workforce console pages
  • atlas/ — customer-private CEO aide.
  • app/ — FastAPI service with 5 capability modules
  • charts/atlas/ — Helm chart (do not restructure)
  • tests/ — pytest suite
  • RELEASING.md — cosign release pipeline
  • workforce-modeler/ — standalone FastAPI for engagement-fee

forecasts + scenario comparison.

Library + tooling

  • sdks/agentvault-py/ — published Python SDK with @governed

decorator.

  • tools/arxctl/ — CLI with validate-manifests and

verify-chain subcommands. Standalone; no deploy coupling.

  • library/ — reusable policies, prompts, workflows.

Reference agents

  • reference-agents/ — one dir per agent. 50+ agents shipped.

Each conforms to MANIFEST_FRAMEWORK.md. See INDEX.md for the 84-cell × 3-shape coverage map.

  • reference-agents/_scaffolders/ — code generators that emit

agent dirs from spec dicts. See _scaffolders/README.md.

Documentation

  • docs/ — GitBook source. TOC lives in docs/SUMMARY.md.

Notable subdirs added in the 9-phase build:

  • docs/atlas/ — Atlas spec + auditable network policy
  • docs/credentials/ — per-agent credential vault integration guide
  • docs/deployment/ — 72-hour runbook
  • docs/pricing/ — value-based pricing model
  • docs/sdk/ — SDK quickstart + worked examples per shape

Sales / marketing

  • sales-assets/ — exec briefings, value memos, board-deck

generators.

  • partners/, outreach/ — partner + customer-facing material.
  • Root-level *.html files — Vercel-deployed marketing pages

(only the 8 in vercel.json are routed; the rest are design/Figma exports).

Other

  • .github/workflows/ — CI/CD.
  • examples/, poc/, benchmark/, load-tests/ — eval +

prototyping.

  • scripts/ — one-off operational scripts.

Where to put a new file

| You're adding... | Put it in... | |---|---| | A new backend route | arxsec-api/app/api/v1/<name>.py + register in arxsec-api/main.py | | A new domain module | arxsec-api/app/core/<name>.py | | A new connector adapter | arxsec-api/app/connectors/<name>.py | | A new dashboard page | arxsec-api/frontend/src/app/(dashboard)/<route>/page.tsx + nav entry in arxsec-api/frontend/src/components/sidebar.tsx | | A new Atlas capability | atlas/app/capabilities/<name>.py + dispatch in atlas/app/main.py | | A new reference agent | reference-agents/<function>-<level>-<shape>-<short-name>/ matching the canonical structure | | A new scaffolder | reference-agents/_scaffolders/_scaffold_<name>.py with ROOT = Path(__file__).resolve().parent.parent | | A new arxctl subcommand | tools/arxctl/<name>.py + register in tools/arxctl/__main__.py | | New documentation | docs/<topic>/<name>.md + entry in docs/SUMMARY.md | | A new migration | arxsec-api/supabase/migrations/<timestamp>_<name>.sql (keep timestamp ordering) |

Where NOT to put files

  • Don't add code at the repo root. Put it in the right top-level

dir.

  • Don't add another arxsec/ or lib/ at the repo root — those

legacy dirs predate this layout and shouldn't grow.

  • Don't add new HTML files at the repo root unless you also

update vercel.json to route them.

  • Don't add a parallel docs tree (docs-pages/, engineer-docs/,

getting-started/ already exist as legacy holdovers; new docs go in docs/ only).

Operational story

For the operational walkthrough — Atlas → manifest set → cohort instantiation → 72-hour deployment runbook — start at docs/deployment/72-hour-runbook.md.

For the trust artifacts a customer's CISO needs — Atlas trust posture, audit chain verification, per-agent credential attribution — start at docs/atlas/atlas-spec.md and docs/credentials/per-agent-auth-integration.md.

For pricing — docs/pricing/value-based-pricing.md.

For building agents on the framework — docs/sdk/README.md plus the three worked examples (research / production / coordination).