# Generate Architecture Artifacts From Codebase

> Analyze requirements and codebase together, then always generate a complete architecture package with a primary Architecture and Design Document, diagrams, workflows, data model docs, open questions, image prompts, and playbook-applied output.

- Skill: `arn-nj/generate-architecture-artifacts-from-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arn-nj/generate-architecture-artifacts-from-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arn-nj/generate-architecture-artifacts-from-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: arn-nj (https://skillmd.com/u/arn-nj)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arn-nj/generate-architecture-artifacts-from-codebase

---


# Generate Architecture Artifacts From Codebase

## What This Skill Produces
- A primary Architecture and Design Document as the main output.
- Architecture options analysis with pros and cons when no established baseline architecture is found.
- Mermaid and PlantUML diagram source artifacts for architecture views.
- A business workflows document that captures workflow steps and business logic.
- A data models document covering entities, relationships, constraints, and flows.
- An open questions document for unresolved/ambiguous areas.
- Architecture image prompt pack.
- Architect Generic Playbook application document (requirements + codebase assessment).
- Supporting evidence, traceability, timeline, and state snapshots.

## Use When
- You need architecture artifacts from an existing codebase with or without formal BRD/API requirement docs.
- You want the same output structure every run for auditability.
- You want incremental updates when the codebase changes.

## Required Input
- Exactly one path: `codebaseRootFolder`.

The skill must auto-discover requirement signals from `codebaseRootFolder`, including:
- BRD-style docs, API specs, ADRs, wiki exports, and markdown notes.
- If requirement docs are missing, infer requirements from code and mark inferred items explicitly.

## Detail-First Generation Mechanism (Default)
Use `detailed-sequential` generation by default.

Process rules:
1. Generate one major document at a time, complete it, run quality checks, then move to the next document.
2. Do not create all documents in a shallow single pass.
3. Keep an internal generation queue and process in this order:
1. `architecture/Architecture_and_Design_Document.md`
2. `workflows/Business_Workflows_and_Logic.md`
3. `data-models/Data_Models_Document.md`
4. `playbook/Architect_Generic_Playbook_Applied.md`
5. `architecture/Architecture_Options_Pros_Cons.md` (conditional)
6. diagrams (`.mmd`, `.puml`)
7. `image-prompts/architecture-image-prompts.md`
4. After each file, run a file-level quality gate before continuing.

Minimum depth gate per narrative document:
1. Every section must include concrete details, not placeholders.
2. Each major section must cite at least one source/evidence reference.
3. Include explicit assumptions, risks, and unresolved questions where applicable.
4. Include examples/tables for key logic (scoring, flows, entity mappings) when available.
5. If details are missing, add focused `TBD` questions instead of generic text.

Document-family depth gates:
1. `architecture/Architecture_and_Design_Document.md`
- Must contain a complete end-to-end architecture narrative, not just headings.
- Must include explicit component boundaries, interfaces, data flow, deployment, NFRs, and decision rationale.
- Must include source links per major section.
2. `workflows/Business_Workflows_and_Logic.md`
- Must describe workflow steps, decision points, branching, and business rules in detail.
- Must include exceptions, alternate paths, and trigger conditions.
3. `data-models/Data_Models_Document.md`
- Must include entity definitions, relationships, cardinality, lifecycle, and ownership.
- Must include examples or tables for key entities and attributes.
4. `image-prompts/architecture-image-prompts.md`
- Must include one detailed prompt per required view, with scope, style, labels, and relationship constraints.
- Must reference the exact architecture artifact or section it visualizes.
5. `traceability/open-questions.md`
- Must group questions by artifact/decision area.
- Each question must include why it matters, source reference, and owner/follow-up hint.
6. `playbook/Architect_Generic_Playbook_Applied.md`
- Must map playbook sections to requirements and evidence with gap/remediation notes.
7. `architecture/Architecture_Options_Pros_Cons.md` (conditional)
- Must include at least three options with tradeoffs, risks, and recommendation.

## Output Contract
Create or update these artifacts under `generated-architecture-output/` inside `codebaseRootFolder`:
1. `architecture/Architecture_and_Design_Document.md`
2. `diagrams/mermaid/component-diagram.mmd`
3. `diagrams/mermaid/data-flow.mmd`
4. `diagrams/mermaid/deployment-diagram.mmd`
5. `diagrams/mermaid/er-database-schema.mmd`
6. `diagrams/plantuml/component-diagram.puml`
7. `diagrams/plantuml/data-flow.puml`
8. `diagrams/plantuml/deployment-diagram.puml`
9. `diagrams/plantuml/er-database-schema.puml`
10. `workflows/Business_Workflows_and_Logic.md`
11. `data-models/Data_Models_Document.md`
12. `traceability/open-questions.md`
13. `image-prompts/architecture-image-prompts.md`
14. `playbook/Architect_Generic_Playbook_Applied.md`
15. `evidence/evidence-index.md`
16. `evidence/source-facts.md`
17. `traceability/requirements-to-evidence-map.md`
18. `timeline/architecture-timeline.md`
19. `timeline/source-change-log.md`
20. `timeline/document-revision-log.md`
21. `.state/last-run-source-snapshot.json`
22. `.state/last-run-doc-checksums.json`

Conditional output (required when architecture baseline is not established):
1. `architecture/Architecture_Options_Pros_Cons.md`

Non-negotiable rule:
- These outputs are mandatory on every run. If evidence is incomplete, still generate each file with explicit `TBD` sections and questions.

Structure compatibility rule:
- Keep old output-structure files when they already exist.
- Update equivalent old-structure files alongside canonical outputs when deltas are detected.
- If an old-structure file has no equivalent in the current run, keep it unchanged and mark it `legacy-unmapped` in revision log.

## Procedure
1. Validate and prepare paths.
- Confirm `codebaseRootFolder` exists.
- Create `generated-architecture-output/` and required subfolders if missing.

2. Discover requirements and codebase shape.
- Discover requirement documents first (BRD, API spec, ADR, wiki/md docs), then code/config evidence.
- Enumerate source files, build files, runtime configs, infra files, and docs.
- Detect languages, frameworks, package managers, and deployment model.
- Identify module boundaries by directory structure and import/reference patterns.

3. Discover architecture signals.
- Extract API surface from OpenAPI specs, route definitions, controllers, handlers, and RPC contracts.
- Extract data model signals from schema files, ORM models, migrations, SQL, and repository code.
- Extract integration signals from HTTP clients, SDK usage, queues, events, and secrets/config references.
- Extract runtime and NFR signals from config (timeouts, retries, security headers, auth, scaling hints, logging, telemetry).

4. Build normalized evidence inventory.
- Record each discovered source with path, type, purpose, and confidence.
- Group evidence by architecture domain: context, component, data, integration, deployment, security, reliability.

5. Initialize update mode.
- If `.state/last-run-source-snapshot.json` exists, run incremental mode.
- Classify file changes as `added`, `updated`, `removed`, `unchanged`.
- Record change summary in `timeline/source-change-log.md`.
- Use `.state/last-run-doc-checksums.json` to detect changed documents (requirements/docs) and changed generated artifacts.
- Trigger targeted regeneration from document changes first, then code/config changes.

6. Generate architecture facts.
- Produce explicit fact cards with source references.
- Mark inferred facts clearly as assumptions.
- Flag conflicts or ambiguity when multiple code paths imply different behavior.

7. Generate architecture options when baseline is missing.
- If requirements and code evidence do not indicate a stable existing architecture baseline, create `architecture/Architecture_Options_Pros_Cons.md`.
- Include at least three architecture options.
- For each option include:
1. Option summary
2. Pros
3. Cons
4. Risks
5. Operational impact
6. Migration complexity
- Add recommended option and decision rationale.

8. Generate primary architecture and design document.
- Build `architecture/Architecture_and_Design_Document.md` first and treat it as the primary output.
- Minimum required sections:
1. system context
2. component architecture
3. data architecture and flow
4. integration architecture
5. deployment and operations
6. security and compliance
7. risks, assumptions, and decisions
- For unknown sections, add `TBD` and track questions in `traceability/open-questions.md`.

9. Generate workflows document.
- Create `workflows/Business_Workflows_and_Logic.md`.
- Include end-to-end workflow steps, decision points, business rules, exceptions, and dependency calls.

10. Generate data models document.
- Create `data-models/Data_Models_Document.md`.
- Include entities, attributes, keys, relationships, cardinality, lifecycle, and data lineage/flows.

11. Generate image prompts.
- Create `image-prompts/architecture-image-prompts.md`.
- Cover at least: context, component, deployment, data flow, and workflow views.
- Include style constraints, scope, labels, and relationships.

12. Generate diagram source artifacts.
- Generate Mermaid and PlantUML files for: component, data flow, deployment, and ER/database schema.
- Ensure diagram labels and node names match architecture docs.
- If a view cannot be fully derived, emit partial diagram plus explicit TODO notes in comments.

13. Apply Architect Generic Playbook.
- Create `playbook/Architect_Generic_Playbook_Applied.md`.
- Document how each playbook section is satisfied by requirements and by code evidence.
- Record gaps, deviations, and recommended remediations.

14. Generate traceability.
- Map major architecture claims to concrete code/config evidence in `traceability/requirements-to-evidence-map.md`.
- Capture unresolved questions and conflict notes in `traceability/open-questions.md`.

15. Maintain timeline artifacts.
- Append run summary and key architecture changes to `timeline/architecture-timeline.md`.
- Append per-document change entries to `timeline/document-revision-log.md`.
- Never delete prior timeline entries.
- Include preserved existing docs count and updated docs count in each run summary.

16. Persist state snapshots.
- Save current source snapshot to `.state/last-run-source-snapshot.json`.
- Save generated document checksums to `.state/last-run-doc-checksums.json`.

17. Quality checks.
- Completeness: all output artifacts exist.
- Traceability: all major claims include source references.
- Consistency: names and interfaces are consistent across outputs.
- Explainability: assumptions and unknowns are explicit.
- Diagram validity: Mermaid and PlantUML files must be syntactically valid and aligned with generated docs.
- Priority check: `architecture/Architecture_and_Design_Document.md` is generated first and references the other generated artifacts.
- Sequencing check: each major file passed file-level quality gate before the next file was generated.
- Depth check: generated narrative docs are detailed enough for design review (not outline-only text).

## Decision Points
- If architecture signals are weak: produce minimum baseline docs and raise targeted open questions.
- If no established architecture baseline exists: produce `architecture/Architecture_Options_Pros_Cons.md` before final architecture selection.
- If conflicting patterns exist: prefer executable runtime path over dead/legacy code and log rationale.
- If monorepo is large: prioritize active apps/services first, then shared libraries.
- If generated outputs already exist: update impacted sections only and preserve unchanged content.
- If requirement documents change but code does not: still update architecture, workflows, data model, and playbook outputs based on document deltas.

## Completion Criteria
- All required artifacts are present under `generated-architecture-output/`.
- If no established architecture exists, `architecture/Architecture_Options_Pros_Cons.md` contains at least three options and a recommended path.
- Primary document `architecture/Architecture_and_Design_Document.md` exists and is complete.
- Workflows and data-model docs exist with business logic and model relationships.
- Open questions document exists even if empty (with `No open questions` marker).
- Playbook application document exists and references both requirements and code evidence.
- Every major section has sourced content or explicit `TBD` plus question.
- Diagram source files exist for each mandatory view (component, data flow, deployment, ER/schema).
- Timeline and state files are updated for the run.
- Old structure files remain available and are synchronized where equivalent outputs exist.
- A reviewer can trace architecture conclusions back to concrete code/config evidence.

## Invocation Pattern
When invoked, ask only for:
1. `codebaseRootFolder`

Then:
1. Analyze the codebase.
2. Generate/update artifacts in detailed-sequential mode (one file at a time with file-level gates).
3. Report output paths, change summary, open questions, and per-file gate outcomes.