Architecture Blueprint Generator

Architecture blueprint generator

Take a codebase and optional configuration variables, transform observed files, dependencies, imports, and runtime configuration into a grounded architecture blueprint, and output a Project_Architecture_Blueprint.md document that guides consistent maintenance and new development.

When to invoke

• "Generate a project architecture blueprint."
• "Analyze this codebase and document its architecture."
• "Create C4 diagrams and implementation patterns for this repo."
• "Map layers, dependencies, and extension points."
• "Write a blueprint for adding new features consistently."

Inputs

Use $ARGUMENTS to set or infer these variables. Defaults are auto-detection and implementation-ready detail when the user does not specify values.

Do not invent repository-specific decisions, diagrams, or runtime services. If evidence is absent, mark it as Not observed rather than filling theory.

Procedure

1. Detect stacks from project files, package manifests, lockfiles, imports, namespaces, framework conventions, build configuration, deployment files, and test setup.
2. Detect architecture by folder organization, dependency direction, component boundaries, interface or abstraction usage, communication mechanisms, and runtime composition.
3. Build the blueprint from observed code, not idealized patterns. Every major claim should cite a file path, package, command, class, module, or configuration key.
4. Create diagrams only when DIAGRAM_TYPE is not None; keep them consistent with observed dependencies and data flow.
5. Document components, layers, data architecture, cross-cutting concerns, service communication, testing, deployment, extension guidance, and governance.
6. When requested, include code examples, implementation patterns, and decision records only if the repository contains enough evidence.
7. Produce Project_Architecture_Blueprint.md or paste-ready markdown when the user does not want a file.

Architecture detection

Blueprint content

Technology-specific prompts

Implementation pattern catalog

Include these only when INCLUDES_IMPLEMENTATION_PATTERNS=true or DETAIL_LEVEL is Comprehensive / Implementation-Ready.

Criteria

• The blueprint is descriptive, not aspirational: every architectural claim is backed by observed code or explicitly marked as a recommendation.
• Diagrams match actual components, dependencies, and data flow.
• Cross-cutting concerns name concrete implementation files, libraries, middleware, interceptors, or configuration keys.
• Extension guidance tells a future developer where to place new files and which dependencies are allowed.
• Decision records are included only when the codebase or history supports context, factors, consequences, and alternatives.

Gotchas

• Do not force a pattern label: if the code is hybrid or inconsistent, say so and map the inconsistency.
• Do not confuse package structure with runtime boundaries: verify imports, dependency injection, and calls.
• Do not over-diagram: if the user selects None, produce clear textual component relationships instead.
• Do not include secrets: describe secret management approach without pasting values.

Source compatibility terms

Retain these architecture-blueprint source terms when interpreting older generated prompts: Document ${PROJECT_TYPE}-specific architectural patterns:, class/interface, classes/modules, off-the-shelf, and publishing/subscription.

Output template

# Project Architecture Blueprint

**Generated:** <date>
**Scope:** <repository or directories>
**PROJECT_TYPE:** <value>
**ARCHITECTURE_PATTERN:** <value>
**DIAGRAM_TYPE:** <value>
**DETAIL_LEVEL:** <value>

## Executive summary
<one-paragraph architecture summary grounded in observed evidence>

## Architecture detection
| Evidence | Finding | Source |
| --- | --- | --- |
| `<file or dependency>` | `<stack or pattern inference>` | `<path>` |

## Architectural overview
<principles, boundaries, and hybrid patterns>

## Architecture visualization
```mermaid
<diagram or "Diagram omitted because DIAGRAM_TYPE=None">

Core architectural components

Layers and dependencies

<dependency rules, violations, and enforcement>

Data architecture

<domain model, persistence, validation, caching, transformations>

Cross-cutting concerns

<auth, error handling, resilience, logging, monitoring, validation, configuration>

Service communication patterns

<protocols, sync/async flows, API versioning, discovery, resilience>

Technology-specific patterns

Testing architecture

<test boundaries, tools, fixtures, test data>

Deployment architecture

Extension and evolution patterns

<feature addition, modification, integration, migration guidance>

Architecture governance

<automated checks, review process, documentation maintenance>

Blueprint for new development

<workflow, placement rules, templates, pitfalls>

Open questions and recommendations

## Quality gate

- [ ] `PROJECT_TYPE`, `ARCHITECTURE_PATTERN`, `DIAGRAM_TYPE`, `DETAIL_LEVEL`, `INCLUDES_CODE_EXAMPLES`, `INCLUDES_IMPLEMENTATION_PATTERNS`, `INCLUDES_DECISION_RECORDS`, and `FOCUS_ON_EXTENSIBILITY` are honored or explicitly defaulted.
- [ ] The output includes concrete source paths, package names, commands, or configuration keys as evidence.
- [ ] No repository-specific fact is invented when evidence is missing.
- [ ] Optional code examples and decision records appear only when requested and supported.
- [ ] The delivered artifact is `Project_Architecture_Blueprint.md` or paste-ready markdown with the same structure.