Repository blueprint suggestions — Deep Dive

The Suggested blueprint flow recommends a catalog blueprint for a GitHub repository before the project is created. It is intentionally lightweight: the API reads repository signals from GitHub, maps those signals to one of the existing catalog blueprint ids, and returns a normal BlueprintDto for the create dialog to apply. It does not call a model; generation remains the separate Generate tab.

For the API contract see the reference; for the user flow see the experience guide.

End-to-end flow

1. The dialog has a repository. CreateFromGitHubDialog keeps the active repository in d.sourceRepository and passes it into the shared BlueprintPanel, whose tab strip starts the GitHub flow on suggested (apps/web/src/pages/ProjectGalleryPage.tsx:676, apps/web/src/components/BlueprintPicker.tsx:371).
2. The client calls the new endpoint. SuggestedBlueprintPanel calls apiClient.suggestBlueprint(normalizedRepo) only when the tab is active and the repo string is non-empty (apps/web/src/components/BlueprintPicker.tsx:301, :305). The client method posts { "repository": "owner/repo" } to /blueprints/suggest (apps/web/src/api/client.ts:186).
3. The endpoint validates shape and identity. POST /api/blueprints/suggest rejects blank repository with 400, resolves the authenticated caller, and passes caller.User to the suggestion service (apps/Agentweaver.Api/Endpoints/BlueprintEndpoints.cs:53, :59, :63).
4. The service parses GitHub coordinates. TryParseOwnerRepo accepts owner/repo, a GitHub URL, and a .git suffix, then normalizes to owner and repo strings (apps/Agentweaver.Api/Blueprints/GitHubRepoBlueprintSuggestionService.cs:17, :116).
5. GitHub metadata reads are anonymous in the current registration. The service queries its credential boundary, but EntraOnlyGitHubCredentialBoundary returns no ambient access token. Repository selection does not automatically grant this heuristic service a Repo App credential (EntraOnlyGitHubCredentialBoundary.cs:38-39, Program.cs:265-271).
6. Repository signals are collected. The service reads repository metadata, languages, and root contents (GitHubRepoBlueprintSuggestionService.cs:51, :58, :62). BuildSignals exposes description, up to five topics, top languages, up to eight root files, and whether issues are enabled (GitHubRepoBlueprintSuggestionService.cs:132).
7. Signals are mapped to catalog blueprint ids. PickBlueprint scores text from name, description, topics, languages, and root file names. AI/LLM signals map to blueprint-ai-agent-engineering; docs/content-only signals map to blueprint-content-authoring; product/design-only signals map to blueprint-product-management; codebase signals or any non-Markdown language map to blueprint-software-development (GitHubRepoBlueprintSuggestionService.cs:149, :163, :167, :171, :175).
8. Catalog lookup is safe. If the mapped id is missing, the service falls back to blueprint-software-development, then the first available catalog blueprint (GitHubRepoBlueprintSuggestionService.cs:70). If GitHub analysis fails or no templates exist, the response sets fallback: true and confidence 0 (GitHubRepoBlueprintSuggestionService.cs:89, :93). The UI renders a warning plus View all templates →, which switches to the shared Templates tab rather than blocking project creation (BlueprintPicker.tsx:323, :371).

Shared dialog and personal repository source

The suggestion panel is now one tab inside the shared Blueprint panel used by both new-project dialogs. Blank projects use Generated | Templates; GitHub projects use Suggested | Templates | Generate. The Templates tab is the same StarterTemplatesSection in both flows, and every compact View all templates → control routes to setSelectedTab('templates') (apps/web/src/components/BlueprintPicker.tsx:209, :222, :371; apps/web/src/pages/ProjectGalleryPage.tsx:405, :676).

Repository discovery uses caller-authorized metadata selections and a short-lived, single-use selection code for project creation (GitHubRepositorySelectionEndpoints.cs:12-89). The retired /api/github/accounts and /api/github/repos picker is not the current contract. Suggestion accepts repository coordinates for metadata analysis; creation consumes the capability-bound selection code.

Why this is separate from generation

Suggestion chooses from catalog blueprints and returns quickly from GitHub metadata. Generation uses a natural-language description and may produce an inline blueprint plus generated workflow YAML. Keeping the tabs separate makes the user choice clear: Suggested means "best matching starter template for this repo," Templates means manual catalog choice, and Generate means bespoke blueprint from a prompt (apps/web/src/pages/ProjectGalleryPage.tsx:676, apps/web/src/components/BlueprintPicker.tsx:236, :279).

Fallback behavior

A parse failure, unavailable metadata, recoverable transport failure, or empty catalog can return fallback: true, confidence 0, a rationale, and a template when available. The UI exposes the Templates tab instead of blocking creation. Caller cancellation propagates; it is not converted into a successful fallback response (GitHubRepoBlueprintSuggestionService.cs:89-115).

Source

Concern	File
Suggested endpoint route and 400 blank-repository validation	apps/Agentweaver.Api/Endpoints/BlueprintEndpoints.cs:53
Suggest request/response wire fields	apps/Agentweaver.Api/Blueprints/BlueprintDtos.cs:111
GitHub repo parsing, signal collection, catalog mapping, fallback	apps/Agentweaver.Api/Blueprints/GitHubRepoBlueprintSuggestionService.cs:17
DI registration	apps/Agentweaver.Api/Program.cs:603
Web client method	apps/web/src/api/client.ts:186
Frontend response type	apps/web/src/api/types.ts:219
Suggested tab rendering and fallback UI	apps/web/src/components/BlueprintPicker.tsx:279
Shared Blueprint panel, tab strip, and Templates routing	apps/web/src/components/BlueprintPicker.tsx:371
Create-from-GitHub tab wiring	apps/web/src/pages/ProjectGalleryPage.tsx:676
Capability-bound repository selections	apps/Agentweaver.Api/Endpoints/GitHubRepositorySelectionEndpoints.cs

See also

• Repository blueprint suggestions — Reference
• Repository blueprint suggestions — Experience
• Project generation model settings
• Projects experience
• API reference

Diagram details and constraints

Element	Contract
title	Repository suggestions are heuristic
takeaway	Anonymous metadata feeds deterministic matching; suggestions never invoke a model.
group-title-0	INPUT + CURRENT CREDENTIAL BOUNDARY
group-title-1	METADATA · MATCHING · OUTCOMES
Blueprint picker: Suggested	Blueprint picker: Suggested
Blueprint picker: Suggested	Repository string or GitHub URL
Blueprint picker: Suggested	Generate is a separate tab and model path
Blueprint picker: Suggested	BlueprintPicker.tsx:487-517
GitHub metadata requests	GitHub metadata requests
GitHub metadata requests	Repository · languages · root contents
GitHub metadata requests	No bearer when boundary returns null
GitHub metadata requests	SuggestionService.cs:55-68
Suggestion service	Suggestion service
Suggestion service	Parse owner / repository
Suggestion service	Invalid input returns fallback response
Suggestion service	SuggestionService.cs:40-48
Deterministic catalog matching	Deterministic catalog matching
Deterministic catalog matching	Signals + ordered heuristic rules
Deterministic catalog matching	No model invocation or repository clone
Deterministic catalog matching	SuggestionService.cs:70-84
Ambient credential boundary	Ambient credential boundary
Ambient credential boundary	Current registration returns null
Ambient credential boundary	Not a forwarded caller GitHub token
Ambient credential boundary	EntraOnlyGitHubCredentialBoundary
Suggested blueprint response	Suggested blueprint response
Suggested blueprint response	Blueprint + rationale + confidence
Suggested blueprint response	Signals explain the recommendation
Suggested blueprint response	SuggestionService.cs:78-88
Recoverable failure	Recoverable failure
Recoverable failure	Unavailable metadata / transport
Recoverable failure	Fallback response offers Templates option
Recoverable failure	SuggestionService.cs:90-108
Caller cancellation	Caller cancellation
Caller cancellation	Propagate OperationCanceledException
Caller cancellation	Not converted into fallback suggestions
Caller cancellation	SuggestionService.cs:90-94
Blueprint picker: Suggested	suggest
Suggestion service	resolve
Ambient credential boundary	null token
GitHub metadata requests	signals
Deterministic catalog matching	recommend
Suggestion service	invalid
GitHub metadata requests	cancel
scope	Cancellation propagates; recoverable failures fall back. Current ambient token source is explicitly null.
groups	INPUT + CURRENT CREDENTIAL BOUNDARY; METADATA · MATCHING · OUTCOMES