apex

apex is a production-grade internal developer platform monorepo.

Repository Layout

• api/: Python package for the platform API.
• cli/: Python package for the apex CLI.
• mcp/: Python package for local-first MCP server used by developer AI agents (supports future remote hosting).
• packages/contracts/: Shared request/response contracts for API and CLI.
• infra/local/: Local Docker stack for dependencies (OPA, Postgres, OTel collector).
• docs/: Cross-cutting architecture, auth, integrations, and operational guides.

Tooling

• Python package/environment management: uv
• Build backend: hatchling

Getting Started

1. Install uv if needed.
2. From repo root, sync workspace dependencies:
   • uv sync
3. Run package commands using workspace packages:
   • API: uv run --package apex-api python -m apex_api.main
   • CLI: uv run --package apex-cli apex --help

API and CLI Foundation

• API framework: FastAPI
• CLI framework: Typer
• Auth: JumpCloud OIDC Device Flow (apex login)
• Authorization: OPA policy decision API
• Audit logs: Postgres/SQL-backed immutable audit trail
• Observability: OpenTelemetry-compatible traces + structured logs + metrics endpoint
• Notifications: Slack notifier module

JumpCloud App Model

• You can use one shared JumpCloud OIDC app for both CLI token issuance and API token verification.
• You may optionally use two separate apps (apex-cli and apex-api) for stricter isolation, separate audiences, and independent policy lifecycle.
• In this implementation, both patterns work; ensure the API verification settings (issuer, audience, jwks) match the token issued to CLI.
• Detailed setup guide: JUMPCLOUD_SETUP.md

CLI Usage

• Login and persist session tokens:
  • uv run --package apex-cli apex login
  • also updates local MCP token cache at ~/.config/apex/mcp-access-token.json
• Run MCP server (stdio):
  • uv run --package apex-mcp apex-mcp
• Run MCP server (HTTP):
  • APEX_MCP_TRANSPORT=http uv run --package apex-mcp apex-mcp
• Discover commands quickly:
  • uv run --package apex-cli apex and uv run --package apex-cli apex ci print contextual help without requiring --help.
• Trigger a CI build with runtime params:
  • uv run --package apex-cli apex ci build <jenkins/job/full-name> --param key=value --param env=dev
  • Add --rebuild <build_ref> to re-run a previous build and reuse its parameters.
  • Explicit --param values take precedence over reused build parameters.
• List recent CI builds for a job:
  • uv run --package apex-cli apex ci builds <jenkins/job/full-name> --limit 20
• Discover CI jobs with filters:
  • uv run --package apex-cli apex ci jobs --query nightly --folder team/backend --buildable-only --limit 50
  • Add --recursive to include nested folders (default is non-recursive for faster responses).
• Fetch CI logs:
  • uv run --package apex-cli apex ci logs <jenkins-job-name> --build <build_ref>
  • Add --follow (or -f) to stream logs progressively until the build is complete.
• Output format options:
  • --output human|json|yaml
  • For ci commands, --output and --debug are accepted both globally and on subcommands.
  • Examples: apex --output json ci jobs, apex ci jobs --output json, apex --debug ci jobs, apex ci jobs --debug.

Local Development Stack

1. Copy environment template:
   • cp .env.example .env
2. Start local dependencies:
   • make up
   • (equivalent direct command: docker compose -f infra/local/docker-compose.yml up -d)
3. Run API and CLI commands.
4. See all available development commands:
   • make help

Notes

• Apex is designed as a serious internal platform implementation: policy-enforced operations, auditable changes, and automation-ready interfaces.
• Add service-specific docs inside each package as features are implemented.
• Keep documentation synchronized across AGENTS.md, docs/README.md + docs/*, root README.md, and impacted package READMEs.
• For FastAPI changes, keep generated OpenAPI docs production-grade: explicit app metadata, route summaries/descriptions/tags, documented parameters with constraints/examples, explicit request/response schemas, and endpoint responses coverage for expected outcomes.
• Keep API status semantics clear and consistent (4xx client, 5xx server/upstream, 502 integration failures).
• Keep CLI default errors concise and actionable; use --debug for full traceback diagnostics.

Documentation Index

• Docs hub: docs/README.md
• Architecture overview: docs/architecture.md
• Authentication and authorization: docs/authentication.md
• Integration reference: docs/integrations.md
• Day-to-day workflow: docs/operational-flow.md
• Detailed JumpCloud setup: JUMPCLOUD_SETUP.md
• MCP package guide: mcp/README.md