Brownfield Intake¶

Brownfield intake is the entry mode for pointing the org at an existing codebase. The operator supplies a source reference (a local path or a remote clone URL); the platform imports it into a persistent project workspace, builds a deterministic navigable structure map, runs an agent analysis pass that authors a codebase-analysis living document, and indexes both the codebase and the assessment into the knowledge substrate. It is the codebase counterpart to requirement intake: where requirement intake turns a stated need into work, brownfield intake turns an existing repository into a mapped, indexed, analysed base the org can extend.

The implementation lives under src/synthorg/engine/brownfield/ and src/synthorg/api/controllers/brownfield.py. See the brownfield intake design spec for the full architecture.

Concepts¶

Import submission: the request (project_id, source_ref, title, requested_by, default_branch).
Source resolver: classifies the source as a local path or a remote URL, enforces SSRF protection, and injects forge tokens from the connection catalogue. URLs with embedded credentials are rejected.
Structure map: a frozen, navigable model persisted one-to-one per project (modules, entry points, test suites, build files, dependencies), built by deterministic per-ecosystem scanners (Python, Node, Go, Rust ship, with a generic file-tree fallback). A content hash over structural facts powers idempotent re-import.
Codebase analysis: the living document the agent analysis pass authors, auto-indexed so agents retrieve their own understanding on later work.
query_structure_map: the agent-facing tool that lists a requested facet with an optional name filter.

Enablement¶

The controller is mounted unconditionally. The adapter wires at startup and is best-effort: it requires a work pipeline, a connected persistence backend, a project workspace service, and a knowledge service. If any is missing, the controller returns 503 on every request.

The relevant tunables are the per-operation rate-limit and concurrency settings in the api namespace (src/synthorg/settings/definitions/api.py):

Key	Type	Default	Purpose
`api.per_op_rate_limit_enabled`	bool	`true`	Master switch for per-operation sliding-window rate limits.
`api.per_op_rate_limit_overrides`	JSON	`{}`	Override the `brownfield.import` rate, e.g. `{"brownfield.import": [20, 60]}`.
`api.per_op_concurrency_enabled`	bool	`true`	Master switch for per-operation inflight concurrency caps.
`api.per_op_concurrency_overrides`	JSON	`{}`	Override the `brownfield.import` inflight cap, e.g. `{"brownfield.import": 2}`.

The default policy is 10 imports per 60 seconds per user, with a single concurrent import per user.

Endpoints¶

Method	Path	Purpose	Response
`POST`	`/api/v1/brownfield/import`	Submit an import and analysis run for an existing codebase.	`202 Accepted` with `{project_id, status: "accepted"}`

The import and analysis run asynchronously. Poll the project's task board and structure map for completion, and watch the brownfield.* structured log events for pipeline progress.

Worked example: import a repository¶

curl -s -X POST https://<host>/api/v1/brownfield/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "acme-payments-platform",
    "source_ref": "https://example.com/acme/payments-platform",
    "title": "ACME Payments Platform",
    "requested_by": "alice",
    "default_branch": "main"
  }'

Field	Required	Default	Description
`project_id`	yes	(required)	Target project to import into (must exist).
`source_ref`	yes	(required)	Remote clone URL (`https://` or `ssh://`) or local `file://` path.
`title`	no	`Imported codebase`	Title for the indexed knowledge source.
`requested_by`	no	`operator`	Identifier of the requester.
`default_branch`	no	`main`	Branch to provision and seed.

Re-import policy¶

No existing structure map: a fresh import runs.
Same source reference with an unchanged content hash: the import short-circuits (idempotent).
A different source reference onto an occupied project: rejected with 409 (BrownfieldWorkspaceNotEmptyError). Force-reset is a separate explicit operation.

Observability¶

Progress is observable through the brownfield.* structured log events, including brownfield.import.started, brownfield.workspace.seeded, brownfield.structure.scanned, brownfield.codebase.indexed, and brownfield.import.completed, plus warning-level keys for parse failures and pipeline errors after the initial acknowledgement.