create-project-arch

A scaffolding tool designed to bootstrap new projects with project-arch integrated natively. Create production-ready monorepos with architecture management built-in from day one.

Features

🚀 Quick Setup - Get started with architecture-first development in minutes
📦 Modern Stack - Next.js, React, TypeScript, and Turborepo
🎨 UI Templates - Pre-built architecture visualization components
🏗️ Structured Architecture - Phases, milestones, and tasks from the start
📝 ADR Support - Architecture decision records included
🔧 Customizable - Choose your package manager and template options

Quick Start

Create a new project with npx (no installation required):

npx create-project-arch my-awesome-project

Or with pnpm:

pnpm create project-arch my-awesome-project

Or with yarn:

yarn create project-arch my-awesome-project

Then follow the interactive prompts to configure your project!

Usage

create-project-arch <project-name> [options]

Options

| Option | Description | Default | | ------------------- | ---------------------------------------- | --------- | | --template <name> | Template to use | arch-ui | | --pm <name> | Package manager (pnpm, npm, yarn) | pnpm | | --force | Allow scaffolding in non-empty directory | false |

Examples

Basic usage:

# Create with default options (pnpm, arch-ui template)
npx create-project-arch my-project

# Specify package manager
npx create-project-arch my-project --pm npm

# Use specific template
npx create-project-arch my-project --template ui-package

# Force creation in existing directory
npx create-project-arch my-project --force

What Gets Created?

When you run create-project-arch, it:

1. Creates a Turborepo monorepo with modern tooling
2. Initializes project-arch with arch-model/ directory
3. Scaffolds template applications based on your selection
4. Configures package scripts for architecture management
5. Installs dependencies using your chosen package manager

Project Structure

my-awesome-project/
├── apps/
│   ├── arch/                    # Architecture UI (Next.js app)
│   │   ├── app/
│   │   │   ├── page.tsx        # Dashboard
│   │   │   ├── phases/         # Phase explorer
│   │   │   ├── milestones/     # Milestone viewer
│   │   │   ├── tasks/          # Task manager
│   │   │   └── decisions/      # ADR browser
│   │   └── components/
│   │       ├── PhaseCard.tsx
│   │       ├── TaskList.tsx
│   │       └── MilestoneTimeline.tsx
│   └── web/                     # Your main application
├── packages/
│   └── ui/                      # Shared UI components
│       ├── src/
│       │   ├── button.tsx
│       │   ├── card.tsx
│       │   └── ...
│       └── package.json
├── arch-model/                  # Architecture directory
│   ├── phases/
│   │   └── phase-1/
│   │       └── milestones/
│   ├── decisions/
│   ├── docs/
│   └── concept-map.json         # Concept-to-module traceability map
├── architecture/
│   ├── foundation/              # Milestone 1 prerequisite docs
│   │   ├── prompt.md
│   │   ├── project-overview.md
│   │   ├── goals.md
│   │   ├── user-journey.md
│   │   └── scope.md
│   ├── architecture/            # System architecture specs
│   │   ├── SPEC_TEMPLATE.md
│   │   └── example-system.md
│   ├── decisions/               # Architecture decision records
│       ├── DECISION_TEMPLATE.md
│       └── example-decision.md
│   └── reference/               # Reusable quality and closure references
│       ├── GAP_CLOSURE_TEMPLATE.md
│       └── example-gap-closure.md
├── arch-domains/                # Domain boundaries and ownership
│   ├── README.md
│   ├── domains.json
│   ├── DOMAIN_TEMPLATE.md
│   ├── core.md
│   ├── ui.md
│   └── api.md
├── scripts/
│   └── validate.sh              # Local architecture validation hook
├── .githooks/
│   └── pre-commit               # Optional local pre-commit validation hook
├── package.json
├── turbo.json
└── pnpm-workspace.yaml

Milestone 1 Prerequisites

Scaffolded projects include these foundation docs by default under architecture/foundation/:

• prompt.md (canonical source brief)
• project-overview.md
• goals.md
• user-journey.md
• scope.md

Complete these files first before implementing milestone tasks.

Domain Spec Scaffold

Scaffolded projects also include baseline domain specs under arch-domains/:

• domains.json with starter domains (core, ui, api)
• DOMAIN_TEMPLATE.md with required sections:
  • Responsibilities
  • Primary Data Ownership
  • Interface Contracts
  • Non-Goals
  • Milestone Mapping
• Starter specs: core.md, ui.md, and api.md

System Architecture Spec Scaffold

Scaffolded projects include reusable architecture specs under architecture/architecture/:

• SPEC_TEMPLATE.md with required sections:
  • Purpose
  • Scope (in-scope / out-of-scope)
  • Key Definitions
  • Design
  • Data Model
  • Owning Domain
  • MVP Constraints
• example-system.md showing a realistic completed reference

Concept-To-Module Traceability Scaffold

Scaffolded projects include arch-model/concept-map.json with:

• concept metadata (id, name, description)
• owning domain assignment
• module responsibilities
• implementation surfaces (API/UI/component/code paths)
• concept dependencies
• domain-module mapping and implementation checklist placeholders

Decision Record Scaffold

Scaffolded projects include architecture decision templates under architecture/decisions/:

• DECISION_TEMPLATE.md with structured frontmatter (id, title, slug, status, timestamps, relatedTasks, relatedDocs, supersedes)
• Required sections:
  • Context
  • Decision
  • Rationale
  • Alternatives Considered
  • Affected Artifacts
  • Implementation Status Checklist
• example-decision.md demonstrating a completed decision record

Use pa decision new for operational decision creation linked into roadmap decision indexes.

Milestone Gap-Closure Report Scaffold

Scaffolded projects include closure report artifacts under architecture/reference/:

• GAP_CLOSURE_TEMPLATE.md with sections for:
  • Executive Summary
  • Gap Categories And Resolutions
  • Layer Synchronization Check
  • Coverage Audit
  • Remaining Gaps And Follow-On Items
  • Template Improvement Feedback
• example-gap-closure.md demonstrating a completed closure report

Recommended workflow:

1. Complete milestone tasks and decision updates.
2. Run pa lint frontmatter --fix.
3. Run pnpm lint:md.
4. Run pa check and pa report.
5. Record closure outcomes in milestone closure report.
6. Track remaining gaps as follow-on tasks/decisions.

Local Validation Hook Scaffold

Scaffolded projects include local validation automation assets:

• scripts/validate.sh runs:
  • pnpm arch:check
  • pnpm arch:report
• Optional local hook example:
  • .githooks/pre-commit

Use these hooks to keep architecture validation consistent in local workflows.

Available Templates

arch-ui (Default)

A complete Next.js application for visualizing and managing your project architecture.

Includes:

• 📊 Dashboard with project overview
• 📋 Phase and milestone explorer
• ✅ Task management interface
• 📝 ADR browser and editor
• 📈 Progress tracking and metrics
• 🎨 Beautiful UI with Tailwind CSS

Perfect for:

• Teams that want visual architecture management
• Projects with multiple phases and complex dependencies
• Organizations adopting architecture-first development

Technologies:

• Next.js 14+ (App Router)
• React 18+
• TypeScript
• Tailwind CSS
• project-arch SDK

ui-package

A starter template for building a shared React component library.

Includes:

• 🎨 Basic UI components (Button, Card, Input, etc.)
• 📚 Component documentation structure
• 🔧 TypeScript configuration
• 📦 Optimized for publishing

Perfect for:

• Building design systems
• Creating shared component libraries
• Publishing npm packages

Technologies:

• React 18+
• TypeScript
• ESLint configuration

Getting Started with Your New Project

After scaffolding completes:

1. Navigate to your project

cd my-awesome-project

2. Install dependencies (if not auto-installed)

pnpm install

3. Start the development server

# Start all apps
pnpm dev

# Or start specific app
pnpm dev --filter=arch

The architecture UI will be available at http://localhost:3000

4. Initialize your architecture

The project comes with a sample architecture, but you can customize it:

# Create a new phase
pnpm arch phase new phase-1

# Create a milestone
pnpm arch milestone new phase-1 milestone-1

# Create tasks
pnpm arch task new phase-1 milestone-1

# Document a decision
pnpm arch decision new use-react

# Run validations
pnpm arch check

5. View your architecture

Open the architecture UI at http://localhost:3000 to see:

• Visual representation of phases and milestones
• Task progress and dependencies
• Architecture decision records
• Project metrics and reports

Architecture Management Commands

Your scaffolded project includes these scripts in package.json:

{
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "arch": "pa",
    "arch:check": "pa check",
    "arch:report": "pa report",
    "arch:docs": "pa docs"
  }
}

Available Commands

# Initialize architecture (already done during scaffolding)
pnpm arch init

# Create and manage phases
pnpm arch phase new <phase-id>
pnpm arch phase list

# Create and manage milestones
pnpm arch milestone new <phase> <milestone>
pnpm arch milestone list <phase>

# Create and manage tasks
pnpm arch task new <phase> <milestone>
pnpm arch task discover <phase> <milestone> --from <task-id>
pnpm arch task idea <phase> <milestone>
pnpm arch task lanes <phase> <milestone>

# Document decisions
pnpm arch decision new <decision-id>
pnpm arch decision list

# Validation and reporting
pnpm arch check
pnpm arch report
pnpm arch docs

Developing Templates (For Contributors)

If you want to customize the templates or contribute new ones:

1. Initialize the Sandbox

pnpm run sandbox:init

This creates a testProject/ directory with the scaffolded templates.

2. Start Development

pnpm run sandbox:dev

This starts the Next.js dev server for the arch-ui template at http://localhost:4020.

3. Make Changes

Edit files in testProject/apps/arch/ and testProject/packages/ui/. Changes will hot-reload.

4. Sync Changes Back

When satisfied with your changes:

pnpm run sandbox:sync

This copies your changes back to the templates/ directory so they're included in the next release.

5. Test Scaffolding

# Build the CLI
pnpm build

# Test scaffolding
node dist/cli.js test-output --force

Template Structure

Templates are stored in templates/ directory:

templates/
├── arch-ui/
│   ├── package.json
│   ├── next.config.js
│   ├── tailwind.config.ts
│   ├── app/
│   │   ├── page.tsx
│   │   ├── layout.tsx
│   │   └── ...
│   └── components/
│       └── ...
└── ui-package/
    ├── package.json
    ├── tsconfig.json
    └── src/
        └── ...

Creating a New Template

1. Create a new directory in templates/
2. Add all necessary files for the template
3. Use placeholders for project-specific values:
   • {{PROJECT_NAME}} - Replaced with the project name
   • {{PACKAGE_MANAGER}} - Replaced with pm choice
4. Update the CLI to recognize the new template
5. Add documentation

Configuration

Package Manager Detection

The tool automatically detects and uses the package manager you invoked it with:

npx create-project-arch my-app      # Uses npm
pnpm create project-arch my-app     # Uses pnpm
yarn create project-arch my-app     # Uses yarn

You can override with --pm:

npx create-project-arch my-app --pm pnpm

Template Selection

Choose a template with --template:

npx create-project-arch my-app --template ui-package

Troubleshooting

Installation Fails

Issue: Dependencies fail to install

Solution:

# Clear cache and retry
pnpm store prune
pnpm install

Port Already in Use

Issue: Dev server can't start (port 3000 in use)

Solution:

# Use a different port
PORT=3001 pnpm dev

Template Not Found

Issue: Template 'xyz' not found

Solution: Check available templates:

npx create-project-arch --help

Valid templates: arch-ui, ui-package

Force Flag Required

Issue: Directory not empty

Solution: Use --force flag to scaffold in existing directory:

npx create-project-arch my-app --force

Warning: This will overwrite existing files!

Examples

Create a Team Project

# Scaffold with architecture UI
npx create-project-arch team-project

# Navigate and start
cd team-project
pnpm install
pnpm dev

# Set up initial architecture
pnpm arch phase new foundation
pnpm arch milestone new foundation mvp
pnpm arch task new foundation mvp

Create a Component Library

# Use ui-package template
npx create-project-arch my-ui-lib --template ui-package

cd my-ui-lib
pnpm install

# Build the library
pnpm build

# Develop with hot reload
pnpm dev

Quick Prototype

# Use npm for simplicity
npx create-project-arch prototype --pm npm

cd prototype
npm install
npm run dev

Migration from Existing Projects

To add project-arch to an existing project:

1. Install project-arch

pnpm add project-arch -w

2. Initialize architecture

pnpm exec pa init

3. (Optional) Copy template files manually from this repository

API Reference (Programmatic Usage)

You can use create-project-arch programmatically:

import { scaffold } from "create-project-arch";

await scaffold({
  projectName: "my-project",
  template: "arch-ui",
  packageManager: "pnpm",
  targetDir: "/path/to/project",
  force: false,
});

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas for Contribution

• 🎨 New templates
• 🐛 Bug fixes
• 📚 Documentation improvements
• ✨ Feature enhancements
• 🧪 Test coverage

Changelog

See CHANGELOG.md for version history and updates.

License

MIT License - see LICENSE for details.

Related Projects

• project-arch - Core CLI and SDK
• Turborepo - High-performance build system
• Next.js - React framework

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

Built with:

• Commander.js - CLI framework
• fs-extra - File system utilities
• project-arch - Architecture management

Ready to build architecture-first? 🚀

npx create-project-arch my-next-project