Stitchfy v2

A framework that turns structured Markdown requirements into traceable solution architecture, plus artifacts your team can start building from.

What is Stitchfy?

Stitchfy is an open source framework. Give it a plain Markdown file describing a business (its goals, processes, systems, and requirements), and it generates a structured, traceable solution architecture: which capabilities apply, what each one specifies, and, where a real exporter exists, scaffolding a team can review and build from.

It supports:

Static website generation. Stitchfy's original capability, and still fully working: a complete, accessible, SEO optimized static site built from one Markdown file. See "Website Quick Start" below.
Business process discovery. Structured extraction of goals, actors, processes, systems, integrations, and requirements from Markdown.
Workflow automation specs. Steps, decisions, notifications, and human in the loop approvals, derived from real process and requirement text.
Integration architecture. REST and webhook contracts, authentication, and data contracts, plus a generic-rest-typescript export adapter for integrations that have a complete contract.
AI agent architecture. Tool, permission, guardrail, and memory specifications tied to real integrations. Never assumed autonomous, persistent, or bound to a specific model by default.
Security and governance architecture. Requirements, trust boundaries, and risk assessment, derived from real integration, data, and workflow evidence.
Observability architecture. Signals, alerts, and operational objectives that cite real architecture entities, with no fabricated thresholds.
Cloud and deployment architecture. A vendor neutral deployment topology that never assumes a provider unless one is explicitly stated.
Legacy modernization architecture. Assessment and migration strategy, optionally enriched with read only local repository evidence, plus a generic-java-replatform export adapter that proposes (and never applies) a migration recipe.

Each of the eight capabilities beyond the website is selected, not always run. A planning stage checks every registered capability against structured evidence in the input document (an explicit ## Deployment Requirements section, an explicit REST integration, an explicit ## AI Agent Needs section, and so on) before any of them execute, and records why each one was or wasn't chosen. Look in output/reference/<scenario>/reports/solution-plan.md after running any example to see that reasoning. Stitchfy never blindly runs every capability on every input, and most of the pipeline is fully deterministic: no AI or LLM call is required anywhere in the solution architecture pipeline. (See "OpenAI Integration" below for the one optional exception, in the website blueprint pipeline.)

Three canonical, end to end worked examples, exercising real combinations of these capabilities together, live under examples/reference/. See docs/reference/END_TO_END.md for the full walkthrough.

Who it's built for: developers and agencies who need to turn a business requirements document into reviewable architecture, from a small business website, through workflow, integration, and AI agent specifications, to a legacy modernization migration recipe.

Architecture at a glance

Markdown Requirements
        ↓
Business Discovery              (extracts explicit facts — never infers)
        ↓
Solution Planning               (selects capabilities from structured evidence)
        ↓
Capability Registry
        ↓
┌─────────────────────────────────────────┐
│ Website                                  │
│ Workflow Automation                      │
│ Integrations                             │
│ AI Agents                                │
│ Security / Governance                    │
│ Observability                            │
│ Cloud / Deployment                       │
│ Legacy Modernization                     │
└─────────────────────────────────────────┘
        ↓
Validated Solution Architecture  (SolutionBlueprint)
        ↓
Optional Exporters / Codebase Evidence
   (generic-rest-typescript, generic-java-replatform, read-only repo analysis)

Not every capability executes on every input. Only the ones structured evidence actually supports do. See docs/reference/CAPABILITY_MATRIX.md for exactly which capability fires on each of the three canonical references.

The Problem It Solves (Website Generation)

Building a professional website for a local business involves repetitive work: establishing page structure, writing meta tags, ensuring WCAG compliance, setting up routing, wiring navigation, and applying brand colors, all before a single line of content is written.

Stitchfy encodes that professional knowledge into a pipeline. Each agent applies best practices for its domain so you don't have to rediscover them for every client:

The UX Agent decides page hierarchy and hero strategy based on industry type
The SEO Agent writes structured data (JSON-LD), Open Graph tags, and per page meta descriptions
The Accessibility Agent enforces WCAG 2.1 AA requirements: skip links, landmarks, keyboard navigation, color contrast, ARIA
The Frontend Agent assembles everything into a validated blueprint that drives real code generation

The output is a complete static site with prebuilt components and an HTML audit report, all from one Markdown file.

Solution Architecture Quick Start

# 1. Install
git clone https://github.com/devifyllc/stitchfy.git
cd stitchfy
npm install

# 2. Run one of the three canonical, end-to-end reference solutions
npm run solution -- --input examples/reference/appointment-automation-ai.md --output output/reference/appointment-automation-ai

# 3. Or write your own — see templates/solution/ for starting points
npm run solution -- --input path/to/your-requirements.md

Produces, under the output directory (output/ by default):

Directory	Contents
`context/`	`business-context.json`, the derived `BusinessContext`
`blueprints/`	`solution-blueprint.v1.json`, the full validated `SolutionBlueprint` and the canonical machine readable contract
`artifacts/`	Generated JSON and Markdown for each capability, plus any exporter scaffolding
`reports/`	`solution-plan.md` (why each capability was selected) and `solution-report.html` (the same blueprint, explained for a human reader)

solution-blueprint.v1.json is the canonical contract, but it's also a large, deeply nested JSON document spanning all eight capabilities, not something anyone should have to read in a text editor to understand what Stitchfy produced. solution-report.html exists for exactly that: a purely presentational, human readable explanation of the same blueprint, meant to be opened directly in a browser. It's generated automatically at the end of every npm run solution run, no extra flag needed, and it never redefines or recomputes anything: every status, count, risk, and recommendation shown in it is read straight from that run's solution-blueprint.v1.json.

Every run writes its own copy into its own output directory, so there's no single shared report: each of the three canonical reference scenarios gets one (output/reference/appointment-automation-ai/reports/solution-report.html, output/reference/order-platform/reports/solution-report.html, output/reference/legacy-java-modernization/reports/solution-report.html), and so does any custom run, at <your-output-dir>/reports/solution-report.html. See docs/architecture/ARCHITECTURE.md ("Solution Report") for how it relates to the JSON contract and to the exporters specific to each capability.

See docs/reference/END_TO_END.md for the full 8 step pipeline walkthrough, docs/reference/CAPABILITY_MATRIX.md for real per scenario capability coverage, and examples/reference/README.md for all three canonical scenarios, including the two optional flags used by the legacy modernization scenario (--codebase/--system-id and --modernization-export). Run all three, plus semantic validation, at once with npm run reference:validate.

Website Quick Start

# 1. Install
git clone https://github.com/devifyllc/stitchfy.git
cd stitchfy
npm install

# 2. Describe your business
cp examples/beauty-salon.md input/project.md
# (edit input/project.md with the real business details)

# 3. Generate the blueprint: no API key required
#    The five blueprint agents run deterministically by default.
#    An OpenAI key is optional and only needed if you replace the
#    deterministic logic with the AI calls (see OpenAI Integration below).
npm run stitchfy

# 4a. Generate website: template-based (no API key required)
npm run build:site

# 4b. Generate website: AI-designed via Google Stitch (only STITCH_API_KEY required)
#    No OpenAI key needed for this path.
npm run build:site:stitch

# 5. Audit accessibility and SEO
npm run audit

Open output/static-site/index.html (template) or output/stitch-site/index.html (Stitch) in any browser.

Which generator should I use?

No API key? Use npm run build:site (template based, and it always works).

Have a STITCH_API_KEY? Use npm run build:site:stitch for AI generated layouts. No OpenAI key needed.

Have an OPENAI_API_KEY? See the OpenAI Integration section below. It enables AI driven blueprints, not a different site generator.

How It Works

Stage 1: Blueprint pipeline (shared by both generators)

input/project.md
       │
       ▼
┌─────────────────────┐
│  1. Intake Agent    │  Parses Markdown → structured business data
└────────┬────────────┘  (name, hours, services, contact, socials, brand tone)
         │
         ▼
┌─────────────────────┐
│  2. UX Agent        │  Industry-aware page strategy, color palette,
└────────┬────────────┘  navigation, hero visual spec, typography
         │
         ▼
┌─────────────────────┐
│  3. SEO Agent       │  Per-page titles + descriptions, JSON-LD schema.org,
└────────┬────────────┘  Open Graph tags, canonical URLs
         │
         ▼
┌─────────────────────┐
│  4. Accessibility   │  WCAG 2.1 AA checklist (30 checks), landmark
│     Agent           │  requirements, ARIA guidelines, reduced-motion rules
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  5. Frontend Agent  │  Component map, routing plan, unsupported features
└────────┬────────────┘  list, implementation notes
         │
         ▼
┌─────────────────────┐
│  Schema Validation  │  Zod validates the entire blueprint before writing
└────────┬────────────┘
         │
         ▼
output/blueprint/website-blueprint.v1.json   ← Validated, machine-readable spec

Stage 2: Code generation (choose one)

output/blueprint/website-blueprint.v1.json
         │
         ├─── npm run build:site ──────────────────────────────────────────────┐
         │    Template-based generator                                         │
         │    Reads blueprint → writes Next.js app → next build → static export│
         │                                                                     ▼
         │                                                      output/static-site/
         │
         └─── npm run build:site:stitch ──────────────────────────────────────┐
              Google Stitch MCP generator                                      │
              Creates Stitch project → generates one AI screen per page        │
              → fetches HTML → post-processes → SEO Agent review               │
              → A11y Agent review → auto-patches → writes HTML                 │
                                                                               ▼
                                                              output/stitch-site/
                                                    output/reports/stitch-review-report.html

         └─── npm run audit ──────────────────────────────────────────────────┐
              Runs on output/static-site/ or output/stitch-site/              │
                                                                               ▼
                                              output/reports/accessibility-report.html
                                              output/reports/seo-report.html
                                              output/reports/final-report.html

Commands

Solution Architecture

Command	Description
`npm run solution -- --input path/to/file.md`	Run business discovery, capability selection, and every selected capability's architecture generation
`npm run solution -- --input path/to/file.md --output path/to/output`	Write output to a specific directory
`npm run solution -- --input path/to/file.md --codebase path/to/repo --system-id SYS-001`	Also run read only repository evidence analysis, mapped to one explicit system
`npm run solution -- ... --modernization-export generic-java-replatform`	Also generate a modernization migration recipe (requires `--codebase` and `--system-id`; it never runs without this explicit flag)
`npm run analyze:codebase -- --path path/to/repo`	Standalone repository inventory, with no solution or system mapping required
`npm run reference:validate`	Run all three canonical reference solutions and check them against semantic invariants

Website Generation

Command	Description
`npm run stitchfy`	Run the full agent pipeline on `input/project.md`
`npm run stitchfy -- --input path/to/file.md`	Run pipeline on a specific input file
`npm run validate`	Validate the input file and the last generated blueprint
`npm run build:site`	Generate Next.js app and export to `output/static-site/`
`npm run build:site -- --blueprint path/to/blueprint.json`	Build from a specific blueprint file
`npm run build:site:stitch`	Generate AI designed site via Google Stitch MCP
`npm run audit`	Run 14 point HTML accessibility + SEO audit; write HTML reports

Both

Command	Description
`npm run typecheck`	TypeScript type-check the framework without emitting
`npm run test`	Run the full deterministic test suite

Writing Your Input

Create input/project.md with the following sections. All sections are optional but the more you include, the better the output.

# Project: Your Business Name

## Business Information
- **Business Name:** Luxe Beauty Studio
- **Industry:** Beauty Salon
- **Description:** One-paragraph description of what you do and who you serve.

## Operating Hours
- Monday–Friday: 9:00 AM – 7:00 PM
- Saturday: 9:00 AM – 6:00 PM
- Sunday: Closed

## Services
- Service Name One
- Service Name Two
- Service Name Three

## Location
- Address: 1234 Main St, Suite 1, City, ST 00000
- Neighborhood: Optional (helps local SEO)

## Contact Information
- Phone: (555) 555-0100
- Email: hello@yourbusiness.com

## Social Networks
- Instagram: @yourhandle
- Facebook: /yourpage
- TikTok: @yourhandle

## Booking Preference
- Online booking via Vagaro (https://www.vagaro.com/yourbusiness)
- Phone call during business hours

## Desired Pages
- Home
- Services
- Gallery
- About Us
- Contact
- Book Online

## Brand Tone
- Warm and welcoming
- Modern and visually polished

## Color Preferences
- Primary: #C4847A
- Secondary: #FAF8F5
- Accent: #C9A96E
- Text: #2C2C2C
- Borders/subtle backgrounds: #EDD9D5

## Special Notes
- Any additional instructions for the agents go here.

See the examples/ directory for complete working inputs: beauty-salon.md, massage-spa.md, and medical-center.md.

Generated Output

Blueprint

output/blueprint/website-blueprint.v1.json is a versioned, Zod validated JSON document with eight sections:

Section	Content
`project`	Schema version, generation timestamp, source file, framework version
`business`	All extracted business data: hours, services, contact, socials, booking
`pages`	Page definitions with purpose, sections, CTAs, and component hints
`ux`	Color palette, typography, navigation, header/footer config, hero visual spec
`seo`	Site title, per page meta, JSON-LD fields, Open Graph values
`accessibility`	WCAG 2.1 AA target, 30 item QA checklist, landmark + ARIA requirements
`frontend`	Component map, routes, asset plan, unsupported features list
`qa`	Lighthouse targets, known limitations, expected report list

Template site (`output/static-site/`)

Generated by npm run build:site. It's a Next.js 14 App Router project, built from 12 prebuilt, accessible React components in site-template/components/, exported as pure HTML, CSS, and JS. No Node.js runtime required.

Stitch site (`output/stitch-site/`)

Generated by npm run build:site:stitch. Each page is designed by Google Stitch using Gemini, then post processed and reviewed by the framework's SEO and Accessibility agents before it's written to disk.

Reports (`output/reports/`)

Report	Generator	Contents
`accessibility-report.html`	`npm run audit`	WCAG 2.1 AA checklist, per page HTML analysis
`seo-report.html`	`npm run audit`	Per page meta, structured data, Open Graph audit
`final-report.html`	`npm run audit`	Pipeline summary, route table, next steps
`stitch-review-report.html`	`npm run build:site:stitch`	Per page: automatic patches applied, manual findings

Google Stitch Integration

Stitchfy integrates with Google Stitch as an alternative code generator. Stitch uses Gemini to transform text prompts into production HTML/CSS. Stitchfy drives Stitch via its official MCP server, using the blueprint as the structured brief for each page.

Setup

STITCH_API_KEY is the only API key required for this flow. The blueprint pipeline (npm run stitchfy) runs deterministically with no AI calls, so no OpenAI key is needed.

# Add to your .env file
STITCH_API_KEY=your-key-here

# Optional: choose the generation model (default: GEMINI_3_1_PRO)
STITCH_MODEL=GEMINI_3_FLASH   # faster; GEMINI_3_1_PRO for higher quality

Stitch pipeline flow

blueprint.json
    ↓
Create Stitch project
    ↓
For each page:
  generate_screen_from_text   ← Gemini generates the visual design
    ↓
  get_screen                  ← fetch HTML via downloadUrl
    ↓
  post-processor              ← inject SEO meta, skip link, lang, JSON-LD
    ↓
  stitch-seo.agent            ← fix JSON-LD @type/url/hours, flag dead links
    ↓
  stitch-a11y.agent           ← fix data-alt→alt, nav aria-label, icon aria-hidden
    ↓
  stitch-patcher              ← apply all attribute-level patches
    ↓
  write HTML                  → output/stitch-site/{route}/index.html
    ↓
stitch-review-reporter        → output/reports/stitch-review-report.html

What the review agents do

After Stitch generates HTML, two agents run on each page before it is written to disk:

SEO Agent (stitch-seo.agent.ts)

Patches: rewrites the JSON-LD with the correct @type (for example BeautySalon), an absolute URL, and Schema.org compliant opening hours (24 hour format, individual days)
Flags: a missing og:image, a relative canonical URL, a meta description that contains internal blueprint text, a title over 60 characters, and dead links to routes not in the blueprint

Accessibility Agent (stitch-a11y.agent.ts)

Patches: converts data-alt to alt on every <img> element, adds aria-label to an unlabelled <nav>, adds aria-label="Open menu" to the icon only mobile menu button, replaces focus:outline-none with a visible focus ring, adds role="img" and aria-label to star rating groups, and adds aria-hidden="true" to decorative material icons
Flags: footer links without a <nav> landmark, any remaining images without alt text, and repeated focus:outline-none occurrences

All patches are attribute level only: no structural changes, no content edits. The review report shows exactly what was patched automatically and what requires human review before deploying.

Template vs. Stitch: choosing a generator

	Template (`build:site`)	Stitch (`build:site:stitch`)
API key required	No	Yes (STITCH_API_KEY)
Visual quality	Consistent, predictable	Higher: AI generated layouts
Control	Full	Partial: Stitch decides visual detail
Speed	Fast (no network calls)	Slower (~30–90s per page)
Offline use	Yes	No
Deterministic output	Yes	No: reruns differ
Post generation review	Via `npm run audit`	Built in (agents run automatically)

OpenAI Integration

Scope: OpenAI is only used for the blueprint pipeline (the five agents that produce website-blueprint.v1.json). It has no role in the template generator or the Google Stitch generator. You do not need an OpenAI key to generate a website via either generator.

All five blueprint agents are structured to support an OpenAI API call but run fully deterministically in the default mode: no API key required. The integration point is marked in each agent file:

// OPENAI INTEGRATION POINT:
//   const response = await openai.chat.completions.create({
//     model: process.env.OPENAI_MODEL ?? "gpt-4o",
//     messages: [
//       { role: "system", content: readPrompt("ux.prompt.md") },
//       { role: "user", content: JSON.stringify(businessData) },
//     ],
//     response_format: { type: "json_object" },
//   });

To enable AI generation:

Add OPENAI_API_KEY=sk-... to a .env file in the project root
Replace the deterministic logic in each agent with the commented API call
Parse the response.choices[0].message.content into the expected typed output

The framework's Zod schema validates the agent output regardless of whether it comes from AI or local logic, so the pipeline stays safe either way.

Industry Support

The UX and SEO agents apply industry specific defaults for color palette, typography, page strategy, JSON-LD schema type, and gallery content. The Stitch SEO agent uses the same mapping to set the correct @type in the generated JSON-LD.

Industry keyword	Schema.org type	Palette style	Gallery seeds
`beauty`, `salon`, `hair`, `nail`, `lash`	`BeautySalon`	Warm rose + cream gradient	Hair, nails, skincare
`wellness`, `massage`, `yoga`, `spa`	`HealthAndBeautyBusiness`	Soft green + warm off white	Massage, classes, body
`medical`, `clinic`, `dental`, `doctor`	`MedicalClinic`	Clean white + navy	Facility, team, technology
`restaurant`, `cafe`, `bistro`, `dining`	`Restaurant`	Warm cream + tan gradient	Food, drinks, ambiance
(any other)	`LocalBusiness`	Neutral blue grey	Services, team, facility

Design System

Brand colors from input/project.md are wired into CSS custom properties applied across the entire site:

--color-primary      /* main brand color: buttons, accents */
--color-secondary    /* background tone */
--color-accent       /* highlight color: hover states, badges */
--color-text         /* body text */
--color-border       /* subtle dividers and card borders */
--font-heading       /* heading typeface (Google Fonts, loaded via <link>) */
--font-body          /* body typeface */

The hero background is derived from ux.heroStyle (a structured field the UX Agent generates from the palette), so the hero always uses the actual brand gradient rather than defaulting to white.

In the Stitch generator, these same values are embedded directly into each page's generation prompt so Stitch stays constrained to the blueprint's brand.

Gallery images use picsum.photos in the template generator. The Stitch generator uses Gemini generated images via Google's CDN. Replace the URLs before going live.

What This Does NOT Include

Specification versus runtime (framework wide)

Every capability in this framework generates a specification or proposal, never a running system. None of the following exist anywhere in Stitchfy:

A live workflow runtime: WorkflowDefinition is never executed
A live integration provider: no HTTP, webhook, or JDBC call is ever made to a real external system
LLM or model execution: AIAgentDefinition is a tool, permission, and guardrail specification, not a running agent, and no model API is called
Cloud provisioning: CloudArchitecture never creates a server, container, or billable resource, and no cloud SDK, Terraform, or CloudFormation call exists
Monitoring provider deployment: ObservabilityArchitecture never configures a real Datadog, Grafana, CloudWatch, or similar instance
Automatic patching or source code transformation: ModernizationExportBundle is a reviewable proposal, and no source file is ever written to

See docs/reference/END_TO_END.md's "Artifact taxonomy" for the full architecture/evidence/scaffolding/runtime layering, and docs/architecture/ROADMAP.md for the specific deferred tracks (Runtime Integration Providers, AI Agent Runtime, Cloud/Observability Runtime Providers, Reviewed Source Transformation) that would eventually fill the runtime layer.

Website capability limitations

By design, the website generator produces informational static websites only. The following are deliberately out of scope for it:

Real booking, scheduling, or appointment systems
Payment flows, e-commerce, or product catalogs
User accounts, authentication, or session management
Backend APIs, databases, or server-side logic
CRM or email marketing integrations
HIPAA-grade forms or protected health information handling

Booking links point to third party platforms the business already uses (Vagaro, Mindbody, OpenTable, etc.). Stitchfy generates the page that links out, not the booking engine itself.

Capability status

Capability	Architecture Generation	Export / Scaffolding	Runtime
Website	Yes	Yes	Static HTML/CSS/JS output
Workflow Automation	Yes	No vendor exporter yet	No
Integrations	Yes	`generic-rest-typescript`	No
AI Agents	Yes	Deferred (Phase 6.5)	No
Security & Governance	Yes	N/A (cross cutting)	No
Observability	Yes	Deferred (Phase 7C)	No
Cloud / Deployment	Yes	Deferred (Phase 7C)	No
Legacy Modernization	Yes	`generic-java-replatform`	No source mutation (proposals only)

Deployment

Both output/static-site/ and output/stitch-site/ are pure static HTML/CSS/JS with no Node.js runtime required. Deploy either folder anywhere:

# AWS S3 + CloudFront
aws s3 sync output/stitch-site/ s3://your-bucket --delete

# Netlify
netlify deploy --prod --dir output/stitch-site

# Vercel
vercel --prebuilt output/stitch-site

# GitHub Pages: copy contents into your gh-pages branch

Architecture History

Stitchfy began as a website only generator and grew into the broader solution engineering framework described above: website generation became one capability among eight, selected through a capability registry rather than hardcoded into the pipeline. The website pipeline documented earlier in this README hasn't changed and still works exactly as described. See docs/architecture/ARCHITECTURE.md for the full design rationale and docs/architecture/ROADMAP.md for the phase by phase history and what's still deferred.

Stitchfy has completed an Architecture Stabilization / Release Candidate review (RC1) and a Stable Contract Promotion review (RC2). docs/architecture/PUBLIC_CONTRACTS.md classifies what's stable versus experimental, docs/architecture/COMPATIBILITY.md defines the compatibility and deprecation policy, and docs/architecture/RELEASE_CANDIDATE.md has the full result, gate by gate. Upgrading from an earlier version? See docs/releases/2.2.0.md and docs/releases/UPGRADING_FROM_2_1.md.

Codebase analysis (advanced)

Legacy Modernization can optionally be enriched with real, read only, local repository evidence (Maven, npm, Java). See docs/architecture/CODEBASE_ANALYSIS.md for the full trust boundary and analyzer model, and docs/reference/LEGACY_JAVA_MODERNIZATION.md for a complete worked example including the generic-java-replatform export adapter.

Repository Structure

stitchfy/
├── input/
│   └── project.md                ← Your business spec goes here
│
├── examples/
│   ├── beauty-salon.md
│   ├── massage-spa.md
│   └── medical-center.md
│
├── framework/
│   ├── orchestrator/
│   │   ├── orchestrator.ts       ← Blueprint pipeline driver (9 steps)
│   │   ├── agent-runner.ts       ← Runs each blueprint agent, handles errors
│   │   └── workflow-state.ts     ← Shared state passed between agents
│   ├── agents/
│   │   ├── intake.agent.ts       ← Blueprint stage 1: business data extraction
│   │   ├── ux.agent.ts           ← Blueprint stage 2: UX strategy + hero spec
│   │   ├── seo.agent.ts          ← Blueprint stage 3: meta tags + structured data
│   │   ├── accessibility.agent.ts← Blueprint stage 4: WCAG 2.1 AA checklist
│   │   ├── frontend.agent.ts     ← Blueprint stage 5: component map + routes
│   │   ├── stitch-seo.agent.ts   ← Stitch review: SEO audit + JSON-LD patch
│   │   ├── stitch-a11y.agent.ts  ← Stitch review: A11y audit + attribute patches
│   │   └── stitch-html-review.types.ts ← Shared types for review agents
│   ├── core/
│   │   ├── site-generator.ts     ← Blueprint → Next.js source code (template)
│   │   ├── stitch-client.ts      ← Google Stitch MCP JSON-RPC 2.0 client
│   │   ├── stitch-generator.ts   ← Stitch pipeline orchestrator
│   │   ├── stitch-prompt-builder.ts ← Blueprint → per-page Stitch prompt
│   │   ├── stitch-post-processor.ts ← Injects SEO meta + base a11y into Stitch HTML
│   │   ├── stitch-patcher.ts     ← Applies agent patches to HTML string
│   │   ├── stitch-review-reporter.ts ← Generates stitch-review-report.html
│   │   ├── report-generator.ts   ← Static HTML audit reports (template generator)
│   │   ├── markdown-parser.ts    ← Parses input/project.md
│   │   └── blueprint-writer.ts   ← Writes output/blueprint/*.json
│   ├── schemas/
│   │   ├── blueprint.types.ts    ← TypeScript interfaces (source of truth)
│   │   └── blueprint.schema.ts   ← Zod validation + error messages
│   └── validators/
│       ├── validate-input.ts
│       └── validate-blueprint.ts
│
├── site-template/                ← React components copied into every generated site
│   ├── app/
│   │   ├── layout.tsx            ← Root layout: JSON-LD, Google Fonts, metadata
│   │   └── page.tsx              ← Template placeholder (overwritten per site)
│   ├── components/               ← 12 accessible React components
│   └── lib/types.ts              ← Shared TypeScript types
│
├── scripts/
│   ├── run-stitchfy.ts           ← Entry point: npm run stitchfy
│   ├── build-site.ts             ← Entry point: npm run build:site (template)
│   ├── build-site-stitch.ts      ← Entry point: npm run build:site:stitch
│   ├── audit-site.ts             ← Entry point: npm run audit
│   └── validate.ts               ← Entry point: npm run validate
│
├── output/                       ← All generated artifacts (gitignored)
│   ├── blueprint/
│   ├── generated-site/           ← Next.js source (template generator)
│   ├── static-site/              ← Deployable HTML (template generator)
│   ├── stitch-site/              ← Deployable HTML (Stitch generator)
│   └── reports/
│       ├── accessibility-report.html
│       ├── seo-report.html
│       ├── final-report.html
│       └── stitch-review-report.html
│
├── examples/
├── assets/
├── .env.example                  ← OPENAI_API_KEY + STITCH_API_KEY placeholders
├── LICENSE
├── NOTICE
└── package.json

The tree above is the original website pipeline layout, and it's still fully accurate for it. The Solution Architecture pipeline (see "Architecture at a glance" above) was added alongside it, without changing anything shown above:

stitchfy/
├── framework/
│   ├── discovery/            ← Business Discovery extractors (one per Discovery entity)
│   ├── planning/              ← Solution Planning (capability assessment, solution plan, risk)
│   ├── capabilities/          ← One directory per capability (workflow-automation, integrations,
│   │                            ai-agents, security-governance, observability, cloud, modernization),
│   │                            each with generators/, validators/, schemas/, and (where one exists)
│   │                            an exporters/ subdirectory
│   ├── analysis/codebase/     ← Phase 8.5A read-only repository evidence analyzer
│   └── orchestrator/
│       └── solution-orchestrator.ts   ← Drives the whole Solution Architecture pipeline
├── scripts/
│   ├── run-solution.ts        ← Entry point: npm run solution
│   ├── analyze-codebase.ts    ← Entry point: npm run analyze:codebase
│   └── reference-validate.ts  ← Entry point: npm run reference:validate
├── examples/
│   ├── solution/               ← Focused, single-capability worked examples
│   └── reference/               ← Three canonical, end-to-end reference solutions
├── templates/solution/         ← Reusable starting-point Markdown templates
├── docs/
│   ├── architecture/           ← Design rationale + docs/architecture/ROADMAP.md
│   └── reference/               ← End-to-end walkthrough + capability matrix
└── tests/                      ← node:test suite, including tests/reference/ (test infra only)

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Blueprint agents live in framework/agents/: one file per stage, following the AgentConfig interface in framework/orchestrator/agent-runner.ts
Stitch review agents live in framework/agents/stitch-*.agent.ts: implement reviewSEO / reviewA11y returning HtmlReviewResult from stitch-html-review.types.ts
Add or update the Zod schema in framework/schemas/blueprint.schema.ts for any new blueprint fields
Keep TypeScript types in framework/schemas/blueprint.types.ts in sync with the Zod schema
Run npm run typecheck before submitting a pull request

When adding a new component to site-template/components/, the site generator picks it up automatically. No additional copy step needed.

License

Apache License 2.0: see LICENSE and NOTICE for full terms.

Stitchfy v2.2.0, built by Devify LLC

Name		Name	Last commit message	Last commit date
.claude		.claude
assets		assets
docs		docs
examples		examples
framework		framework
input		input
output		output
scripts		scripts
site-template		site-template
templates		templates
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation