ArchFlow

Architecture Studio for VS Code — scaffold, document, and maintain architecture as code using Markdown, YAML frontmatter, and Mermaid diagrams.

What it does

ArchFlow turns VS Code into an architecture workbench. With a single command it generates a complete, structured .architecture/ folder pre-filled with domain-specific templates, placeholder content, and Mermaid diagrams — ready for a real architect to edit, not start from scratch.

All artefacts are plain text, Markdown-first, and Git-native. No proprietary tools, no vendor lock-in.

Quick Start

1. Install and open a project folder

Open any folder in VS Code (your source repo, or a dedicated architecture repo).

2. Run the command

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

ArchFlow: Initialize New Architecture Workspace

3. Pick your archetype

4. Enter your project name and author

ArchFlow scaffolds .architecture/ instantly and opens master-architecture.md as your entry point.

Generated Structure

Cloud-Native Application

.architecture/
├── architecture-manifest.json
├── master-architecture.md          ← Start here
├── 00-core/
│   ├── core-ask.md                 Problem statement, stakeholders, success criteria
│   └── thinking.md                 Assumptions, options, risks
├── 01-context/
│   ├── requirements.md             FR + NFR tables
│   └── c4-context.md              C4 Level 1 diagram (Mermaid)
├── 02-design/
│   ├── high-level-solution.md      Architecture overview + sequence diagrams
│   ├── tech-mapping-nfrs.md        Tech stack, SLAs, security controls
│   └── c4-container.md            C4 Level 2 container diagram
├── 03-adrs/
│   ├── README.md                   ADR index + conventions
│   └── 0001-initial-architectural-decisions.md
└── 04-cloud/
    ├── cloud-architecture.md       Cloud topology diagram (Azure template)
    └── deployment-topology.md      CI/CD pipeline + environment strategy

Data & Analytics Platform (additional unique files)

├── 01-discovery/
│   ├── data-sources.md             Source catalogue with SLAs, schemas, PII mapping
│   └── data-lineage.md            Medallion architecture, governance, retention policy
├── 02-design/
│   ├── ingestion-design.md         Batch + stream pipeline design with error handling
│   ├── pipeline-flows.md           Pipeline dependency graph + scheduling
│   └── storage-tiers.md           Bronze/Silver/Gold design + dimensional model
└── 04-cloud/
    ├── lakehouse-topology.md       Azure/AWS/GCP lakehouse topology
    ├── access-control-matrix.md    RBAC matrix + PII handling rules
    └── sla-mapping.md             Data contracts + operational runbooks

Integration & API Gateway (additional unique files)

├── 01-context/
│   ├── system-boundaries.md        Interface inventory + contract governance
│   └── message-flows.md           Event catalogue + messaging requirements
├── 02-design/
│   ├── sequence-diagrams.md        4 annotated sequence diagrams (sync, async, protocol transform, circuit breaker)
│   ├── payload-schemas.md          OpenAPI/AsyncAPI fragments + schema evolution policy
│   └── auth-policies.md           APIM policy XML + scope/permission matrix
└── 04-infrastructure/
    ├── event-bus-topology.md       Topic/queue design + DLQ policy
    ├── rate-limiting.md           Rate limits + circuit breaker config + failover topology
    └── deployment-topology.md     Azure APIM + Logic Apps + Service Bus cloud topology

Mobile App Development (additional unique files)

├── 01-context/
│   ├── user-journeys.md           Flowchart diagrams for 4 key journeys (onboarding, core flow, offline, push)
│   └── platform-constraints.md   iOS/Android OS versions, app store requirements + risks
├── 02-design/
│   ├── app-architecture.md        MVVM/Clean Arch layer diagram + DI strategy
│   ├── backend-integration.md     PKCE auth flow + API endpoint table + presigned upload
│   └── offline-strategy.md       Sync queue schema + conflict resolution + SQLite design
└── 04-deployment/
    ├── ci-cd-pipeline.md          Fastlane lanes + gitGraph + phased rollout
    ├── backend-topology.md        Push notifications (ANH) + presigned upload flow
    └── security-model.md         Threat model + token storage + certificate pinning

Every file includes

• YAML frontmatter — title, project, status, created, author, tags
• Contextual placeholder text — written for a real architect, not generic Lorem Ipsum
• Mermaid diagrams — pre-wired placeholders that render immediately in VS Code
• Tables — structured for copy-paste editing

Commands

Adding a new archetype

1. Create src/scaffolder/archetypes/myArchetype.ts implementing the Archetype interface
2. Add it to ALL_ARCHETYPES in src/scaffolder/archetypes/index.ts
3. Recompile — it appears in the QuickPick automatically

Development

# Install dependencies
npm install

# Compile (one-shot)
npm run compile

# Compile + watch
npm run watch

# Press F5 in VS Code to launch Extension Development Host

Roadmap

• [ ] ArchFlow: Add ADR — create a sequentially numbered ADR with one command
• [ ] ArchFlow: Open Master Architecture View — rendered webview panel stitching all files
• [ ] AI-assisted draft generation (VS Code Language Model API)
• [ ] Custom archetype definition via archflow.archetypes workspace setting
• [ ] Export to PDF / HTML for stakeholder review