# Optional app integration

Canonical: https://auggy.dev/docs/engineering-patterns
Status: Preview
Package: auggy 0.5.0

Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.

## Start with the agent path

> **Note: Optional, not the default scaffold**
>
> Most **Auggy** projects do not need routes or generated clients. Start with tools. Add this surface only when existing software genuinely needs a deterministic HTTP entry point beside the agent.

Software calls a route when the operation is known. The agent calls a tool when conversation or investigation must determine the operation. Both call one domain function.

> **Note: These are patterns, not built-ins**
>
> Your application still owns infrastructure, authorization records, and domain policy. Use an augment when a route and tool would otherwise duplicate those rules.

## Three compact patterns

### Manage feature flags

- **Software path:** An admin console calls PATCH /flags/:key with an explicit rollout percentage, audience, and change reason.
- **Agent path:** During an incident, an engineer asks **Auggy** to compare telemetry and propose reducing new-checkout for a region. The model gathers confirmation before calling the tool.
- **Shared operation:** `updateFeatureFlag()` verifies the flag, environment, rollout bounds, audience, authorization, change window, and audit metadata before writing.
- **Why Auggy:** The admin UI and incident workflow use the same rollout policy.

### Provision preview environments

- **Software path:** A **GitHub** webhook calls POST /environments when a pull request receives the preview label.
- **Agent path:** An engineer asks for PR 1842 with sanitized production data, a specific region, and a QA notification. The model turns those constraints into typed input.
- **Shared operation:** `provisionEnvironment()` selects approved infrastructure, applies data policy, records owner and pull request, sets expiration, and submits one idempotent provisioning job.
- **Why Auggy:** Conversation gathers options without creating a second provisioning system.

### Run a data backfill

- **Software path:** An operations dashboard calls POST /backfills after a dry run has identified the job type, tenant scope, affected rows, and rollback plan.
- **Agent path:** An engineer asks **Auggy** to find customers missing invoice totals, estimate impact, and prepare the smallest safe backfill for approval.
- **Shared operation:** `createBackfill()` accepts a reviewed plan, validates the registered job definition, tenant scope, dry-run evidence, concurrency ceiling, approval, idempotency, and rollback metadata.
- **Why Auggy:** Investigation stays flexible; admission stays inside the registered job system.

## Implementation shape

**Route and tool faces**

```
PATCH /flags/:key        + update_feature_flag
  -> updateFeatureFlag()

POST /environments        + provision_preview_environment
  -> provisionEnvironment()

POST /backfills           + prepare_backfill
  -> createBackfill()
```

The plus sign does not mean both paths execute. Routes bypass inference; tools run through the model and tool gates. Each still declares its own auth and rate limits.

## Choose the right depth

| Situation | Recommended shape |
| --- | --- |
| Known operation from CI, UI, or webhook | Call the route directly. |
| Missing fields or ambiguous intent | Let the model gather context, then call a typed tool. |
| Read-only investigation | Use narrow read tools; do not expose the write operation yet. |
| Consequential write | Require application authorization or approval in the shared domain operation. |
| No software caller yet | Start with a tool; add a route when software needs the capability. |

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Webhooks](https://auggy.dev/docs/webhooks/markdown)
- [defineRoute](https://auggy.dev/docs/define-route/markdown)