# GitHub Native Engineer

Standalone web app, API, MCP surfaces, and PlanetScale Postgres data plane for Ara's
GitHub/GitLab-native issue engineer: it connects GitHub or GitLab.com, watches
issues, and runs autonomous sessions that open pull requests or merge requests.
Hono + Bun backend (`backend/src`), React + Vite frontend (`frontend/src`),
WorkOS AuthKit identity, and isolated cloud sandboxes.

The committed interactive runtime is Pi Brain with Ara Hands. Inference enters
through `api.ara.so /app/inference/v2`, is admitted against the workspace credit
balance, and reaches provider models through Vercel AI Gateway. Sandboxes and
local Devices receive run-scoped capabilities, never provider credentials.
There is no second agent runtime or silent fallback.

## The agent seam

The INTERNAL admin CLI (`backend/src/admin-api-cli.ts`, `bun run admin help`) is
a thin HTTP client over the authenticated operator API. It reaches the `/app`
and `/v3` planes plus privileged `/internal/sudo` operations with one operator
key, can act as a user through `X-Act-As`, and never connects directly to the
production database. End users have no admin CLI; they drive the product from
the web app and the public `/v3` API and `/mcp/ara` surfaces.

## Route planes

- `/app`: first-party web BFF, WorkOS AuthKit access tokens only, org-scoped at
  `/app/organizations/:orgId/*`; owns session chat stream, fat run detail,
  display/terminal tickets, workspace fs/exec, PR UI actions, settings, billing,
  onboarding, connector setup, and web aggregation.
- `/v3`: public REST API contract, scoped `ara_` API keys, service users, and
  later PAT-style auth; owns stable org resources, sessions, secrets, knowledge,
  automations, repositories, governance, usage, attachments, PR reviews, and
  external MCP-server config.
- `/mcp/ara`: unified Ara MCP transport over Streamable HTTP. Scoped API-key or
  OAuth principals receive public session, knowledge, automation, and plugin
  tools plus the scoped `/v3` bridge; short-lived live-run principals receive
  eligible organization tools plus their active run's internal toolbelt.

`docs/22-devin-style-api-mcp-route-map.md` is the current route source of truth.

## Run and test

```bash
bun install            # install deps
bun run dev            # web (:3001) + API (:4001) together
bun test               # run *.test.ts via bun
bun run admin help     # full internal admin command list (also --help, -h)
```

## Admin authentication

The admin CLI reads `ADMIN_API_URL` (defaults to `https://api.ara.so`) and one
`ARA_OPERATOR_KEY`, supplied directly, cached by `admin login`, or injected by
`bun run admin:infisical`. It requires no production database credentials.

The `/app` API authenticates browser callers with a WorkOS AuthKit access token
and scopes org data under `/app/organizations/:orgId/*`; public REST and MCP
callers use scoped `ara_` API keys on `/v3` and `/mcp/ara`. Webhooks use HMAC;
the scheduler tick uses a bearer secret.

## Map

- docs/00-foundations.md - normative architecture: one Workspace configuration
  scope, dynamically attached Resources, one Device/Hands path, scoped Capabilities
- README.md - layout, local dev, current surfaces, deploy
- AGENTS.md - invariants and conventions every change must follow
- docs/22-devin-style-api-mcp-route-map.md - current `/app`, `/v3`, and unified
  `/mcp/ara` route map