ArchAI 🏗️

AI-powered project structure generator CLI

Scaffold production-grade backend and fullstack projects in seconds. Describe your idea — AI picks the best template and features for you.

npx @naymhdev/arch-ai init

📖 Table of Contents

Why ArchAI?
Features
Quick Start
Installation
Usage
Templates
Features (Add-ons)
AI Integration
Project Structure
Configuration
Contributing
Roadmap
License

🤔 Why ArchAI?

Every time you start a new project, you repeat the same boring setup:

❌ Create folders manually
❌ Copy-paste boilerplate from old projects
❌ Install the same packages every time
❌ Set up Express, middlewares, tsconfig again
❌ Wire up auth, docker, CI/CD from scratch

ArchAI does all of this in under 10 seconds:

✅ Describe your idea
✅ AI suggests the best template & features
✅ Full project structure generated instantly
✅ Boilerplate code ready to run
✅ All configs pre-wired

✨ Features

🤖 AI-Powered Suggestions — Describe your project idea, AI recommends the best template and features
🔄 Regenerate with Feedback — Don't like the suggestion? Give feedback and AI tries again (up to 3 times)
📦 6 Production-Grade Templates — Backend MVP, Clean Architecture, Microservice, Next.js Basic, DDD, SaaS
⚡ 11 Feature Add-ons — Auth, AI, Billing, Email, Storage, Cache, Queue, WebSocket, Testing, Docker, CI/CD
🎯 Interactive CLI — Beautiful prompts with structure preview before generation
🔧 TypeScript First — Every generated file is fully typed
📋 Structure Preview — See exactly what will be created before confirming
🌈 Multiple AI Providers — Works with Groq (free), Anthropic Claude, or Google Gemini

🚀 Quick Start

# No installation needed
npx @naymhdev/arch-ai init

Or install globally:

npm install -g @naymhdev/arch-ai
arch-ai init

You'll see an interactive prompt like this:

  ╔═══════════════════════════════════╗
  ║      🏗  ArchAI — Project Init     ║
  ╚═══════════════════════════════════╝

  AI-powered project structure generator

? Project name: my-awesome-app
? Short description: A SaaS platform for pet adoption
? Use AI to suggest best template & features? Yes
? Describe your project idea: Pet adoption platform with shelters,
  user bookmarks, admin panel, and subscription plans

⏳ Consulting AI for best project structure...
✔ AI suggestion ready!

  Template:   Next.js SaaS — Full SaaS boilerplate
  Features:   auth, billing, email, storage, testing
  💡 A multi-role platform with subscriptions fits the SaaS template best.

? What would you like to do?
❯ ✅  Accept this suggestion
  🔄  Regenerate — give feedback to AI
  🖊️   Choose manually instead

📦 Installation

Requirements

Node.js >= 18
npm / pnpm / yarn / bun

Global Install

# npm
npm install -g @naymhdev/arch-ai

# pnpm
pnpm add -g @naymhdev/arch-ai

# yarn
yarn global add @naymhdev/arch-ai

# bun
bun add -g @naymhdev/arch-ai

Without Install (npx)

npx @naymhdev/arch-ai init

🎯 Usage

Commands

# Scaffold a new project (interactive)
arch-ai init

# List all available templates and features
arch-ai list

# Show version
arch-ai --version

# Show help
arch-ai --help

`arch-ai init` — Step by Step

Step	Prompt	Description
1	Project name	Your project's directory name
2	Description	Short description (optional)
3	Use AI?	Enable AI-powered suggestions
4	Project idea	Describe what you're building
5	Template	Auto-suggested or manual pick
6	Features	Checkbox selection of add-ons
7	Package manager	npm / pnpm / yarn / bun
8	Output directory	Where to create the project
9	Preview + Confirm	See structure before generating

🗂️ Templates

Backend Templates

`backend-mvp` — Backend MVP

Minimal Express + TypeScript backend. Perfect for REST APIs and quick prototypes.

my-project/
├── src/
│   ├── controllers/     # Route handlers
│   ├── services/        # Business logic
│   ├── routes/          # Express route definitions
│   ├── middlewares/     # Auth, validation, error handling
│   ├── utils/           # Shared utilities
│   ├── config/          # App configuration
│   ├── types/           # TypeScript types
│   ├── app.ts           # Express app setup
│   └── server.ts        # Server entry point
├── .env.example
├── package.json
└── tsconfig.json

Best for: Quick APIs, MVPs, solo projects, learning

`backend-clean` — Backend Clean Architecture

Layered architecture with use-cases, repository pattern, and dependency injection.

my-project/
├── src/
│   ├── domain/
│   │   ├── entities/        # Core business objects
│   │   ├── repositories/    # Repository interfaces
│   │   └── use-cases/       # Application use cases
│   ├── infrastructure/
│   │   ├── database/        # DB adapters & migrations
│   │   └── repositories/    # Concrete implementations
│   ├── presentation/
│   │   ├── controllers/
│   │   ├── routes/
│   │   └── middlewares/
│   └── shared/              # Errors, types, utils
├── tests/
└── ...

Best for: Enterprise apps, team projects, complex business logic

`backend-microservice` — Backend Microservice

Event-driven modular microservice with in-memory event bus.

my-project/
├── src/
│   ├── modules/
│   │   └── health/          # Self-contained feature module
│   ├── events/              # Event bus & handlers
│   ├── shared/              # Shared kernel
│   ├── app.ts
│   └── server.ts
├── Dockerfile
└── docker-compose.yml

Best for: Distributed systems, high-scale apps, modular teams

Full-Stack Templates

`nextjs-basic` — Next.js Basic

Next.js 14 App Router with Tailwind CSS and TypeScript.

my-project/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   └── api/health/route.ts
│   ├── components/
│   │   ├── ui/Button.tsx
│   │   └── layout/Navbar.tsx
│   ├── lib/utils.ts
│   └── types/index.ts
├── next.config.mjs
└── tailwind.config.ts

Best for: Websites, landing pages, portfolios, simple web apps

`nextjs-ddd` — Next.js DDD

Next.js with Domain-Driven Design — server actions, feature modules, repository pattern.

my-project/
├── src/
│   ├── app/
│   │   ├── (auth)/          # Auth route group
│   │   ├── (dashboard)/     # Dashboard route group
│   │   └── api/             # API route handlers
│   ├── domain/
│   │   ├── entities/
│   │   ├── repositories/
│   │   └── use-cases/
│   ├── infrastructure/
│   │   └── repositories/
│   └── presentation/
│       ├── actions/         # Server actions
│       ├── components/
│       └── hooks/
└── ...

Best for: Complex web apps, rich domain logic, server actions

`nextjs-saas` — Next.js SaaS ⭐

Full SaaS starter: landing page, auth, billing, dashboard, and Prisma ORM.

my-project/
├── src/
│   ├── app/
│   │   ├── (marketing)/     # Public landing & pricing pages
│   │   ├── (auth)/          # Login & register pages
│   │   ├── (dashboard)/     # Authenticated dashboard + sidebar
│   │   └── api/
│   │       └── webhooks/
│   │           └── stripe/  # Stripe webhook handler
│   ├── lib/
│   │   ├── auth.ts          # Session management
│   │   ├── stripe.ts        # Stripe client
│   │   └── utils.ts
│   └── ...
├── prisma/
│   └── schema.prisma        # User + Subscription models
└── .env.local.example

Best for: SaaS products, subscription apps, startup MVPs

⚡ Features (Add-ons)

Select any combination of features when running arch-ai init:

Feature	What's Included	Key Packages
`auth`	JWT middleware, AuthService, AuthController, routes	`jsonwebtoken`, `bcryptjs`
`ai`	Anthropic Claude client + streaming setup	`@anthropic-ai/sdk`
`billing`	Stripe subscriptions + webhook handler	`stripe`
`email`	Resend transactional email service	`resend`
`storage`	AWS S3 presigned URL upload service	`@aws-sdk/client-s3`
`cache`	Redis caching layer with TTL helpers	`ioredis`
`queue`	BullMQ background job processing	`bullmq`
`websocket`	Socket.io real-time support	`socket.io`
`testing`	Jest + Supertest config + example tests	`jest`, `supertest`
`docker`	Multi-stage Dockerfile + docker-compose	—
`ci-cd`	GitHub Actions CI workflow	—

Each feature automatically:

✅ Injects the relevant boilerplate files
✅ Adds env variables to .env.example
✅ Lists the npm packages you need to install

🤖 AI Integration

ArchAI supports 3 AI providers. Set any one API key to enable AI suggestions.

Option 1 — Groq (Recommended, Free ✅)

The fastest inference engine. Best for CLI tools.

# Get free key at: https://console.groq.com
export GROQ_API_KEY=gsk_...

Option 2 — Anthropic Claude

Highest quality suggestions.

# Get key at: https://console.anthropic.com
export ANTHROPIC_API_KEY=sk-ant-...

Option 3 — Google Gemini

Generous free tier.

# Get free key at: https://aistudio.google.com
export GEMINI_API_KEY=AIza...

Without AI

ArchAI works perfectly without any API key — it gracefully falls back to manual template and feature selection.

AI Regeneration Feature

Don't like the AI suggestion? Give feedback and it will try again:

✔ AI suggestion ready!
  Template: backend-mvp
  Features: auth, docker

? What would you like to do?
❯ ✅  Accept this suggestion
  🔄  Regenerate — give feedback to AI   ← pick this
  🖊️   Choose manually instead

? What didn't you like? Tell AI what to change:
> "I need Next.js not Express, and add billing"

⏳ Regenerating suggestion (attempt 2/3)...
✔ New suggestion ready!
  Template: nextjs-saas
  Features: auth, billing, email

🗄️ Project Structure (ArchAI Source)

arch-ai/
├── src/
│   ├── cli/                      # CLI entry & commands
│   │   ├── index.ts              # Commander program entry
│   │   └── commands/
│   │       └── init.command.ts   # All Inquirer prompts + AI flow
│   │
│   ├── core/                     # Business logic
│   │   ├── init.ts               # Orchestrator
│   │   ├── generator.ts          # File & directory creator
│   │   ├── template.engine.ts    # In-memory boilerplate renderer
│   │   └── feature.engine.ts     # Feature file injector
│   │
│   ├── ai/                       # AI integration layer
│   │   ├── ai.service.ts         # API client (Groq/Claude/Gemini)
│   │   ├── ai.prompts.ts         # Prompt engineering
│   │   └── ai.parser.ts          # Response validation & parsing
│   │
│   ├── config/                   # App configuration
│   │   ├── templates.config.ts   # 6 template definitions
│   │   └── features.config.ts    # 11 feature definitions
│   │
│   ├── templates/                # Static template files
│   │   ├── backend-mvp/
│   │   ├── backend-clean/
│   │   ├── backend-microservice/
│   │   ├── nextjs-basic/
│   │   ├── nextjs-ddd/
│   │   └── nextjs-saas/
│   │
│   ├── types/index.ts            # Global TypeScript types
│   ├── utils/                    # logger, spinner, file helpers
│   └── constants/index.ts        # App-wide constants
│
├── dist/                         # Compiled output
├── package.json
└── tsconfig.json

⚙️ Configuration

Environment Variables

ArchAI reads these from your shell environment or a .env file:

Variable	Provider	Required
`GROQ_API_KEY`	Groq	Optional
`ANTHROPIC_API_KEY`	Anthropic	Optional
`GEMINI_API_KEY`	Google	Optional

At least one AI key is needed to use AI suggestions. Without any key, manual mode is used.

🤝 Contributing

Contributions are very welcome! Here's how to get started:

1. Fork & Clone

git clone https://github.com/naymHdev/arch-ai.git
cd arch-ai
npm install

2. Run in Development

npm run dev -- init

3. Build

npm run build

4. Project Areas to Contribute

Area	Description
🗂️ New Templates	Add new project templates (e.g., `fastify-api`, `remix-app`)
⚡ New Features	Add new feature add-ons (e.g., `graphql`, `prisma`, `monitoring`)
🤖 AI Improvements	Better prompts, new AI providers
🐛 Bug Fixes	Fix issues, improve error messages
📖 Documentation	Improve docs, add examples
🧪 Tests	Add unit and integration tests

5. Adding a New Template

Step 1 — Add config in src/config/templates.config.ts:

'my-template': {
  id: 'my-template',
  name: 'My Template',
  description: 'Description of what this template does.',
  category: 'backend', // or 'fullstack'
  tags: ['express', 'typescript'],
  defaultFeatures: [],
  compatibleFeatures: ['auth', 'docker', 'testing'],
  structure: {
    // FolderNode tree
  }
}

Step 2 — Add boilerplate files in src/templates/my-template/

Step 3 — Add renderers in src/core/template.engine.ts

Step 4 — Update types in src/types/index.ts

6. Submit a PR

git checkout -b feat/my-new-template
git commit -m "feat: add my-template"
git push origin feat/my-new-template

Then open a Pull Request on GitHub!

Code Style

Use TypeScript for all new code
Follow existing file naming conventions (kebab-case.ts)
Add JSDoc comments for public methods
Keep each file focused on a single responsibility

🗺️ Roadmap

Feature	Status
6 production templates	✅ Done
11 feature add-ons	✅ Done
AI suggestions (Groq/Claude/Gemini)	✅ Done
AI regenerate with feedback	✅ Done
Structure preview	✅ Done
`backend-modular` template	🔄 In Progress
Prisma / Drizzle ORM feature	📋 Planned
GraphQL feature add-on	📋 Planned
`fastify-api` template	📋 Planned
`remix-app` template	📋 Planned
Plugin system for custom templates	📋 Planned
Web UI (browser-based generator)	💡 Idea
VS Code extension	💡 Idea

🐛 Common Issues

`arch-ai: command not found`

# Reinstall globally
npm install -g @naymhdev/arch-ai

# Or use npx
npx @naymhdev/arch-ai init

AI suggestions not working

# Check your key is set
echo $GROQ_API_KEY

# Set it temporarily
export GROQ_API_KEY=gsk_your_key_here

# Or add to your shell profile (~/.zshrc or ~/.bashrc)
echo 'export GROQ_API_KEY=gsk_your_key_here' >> ~/.zshrc
source ~/.zshrc

`Directory already exists` error

# ArchAI won't overwrite existing directories
# Either delete the folder first or choose a different name
rm -rf my-project
arch-ai init

📊 Tech Stack

Tool	Purpose
Node.js	Runtime
TypeScript	Language
Commander.js	CLI framework
Inquirer.js	Interactive prompts
fs-extra	File system operations
Chalk	Terminal colors
Ora	Loading spinners
Groq SDK	AI inference (primary)
Anthropic SDK	AI inference (alternative)

📄 License

MIT © naymHdev

🙏 Acknowledgements

Inspired by create-t3-app and create-next-app
AI suggestions powered by Groq, Anthropic, and Google Gemini
Built with ❤️ for the developer community

NPM Package • GitHub • Report Bug • Request Feature

If ArchAI saved you time, please ⭐ the repo!

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
public		public
src		src
.gitignore		.gitignore
README.md		README.md
package.json		package.json
test-ai.ts		test-ai.ts
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

ArchAI 🏗️

📖 Table of Contents

🤔 Why ArchAI?

✨ Features

🚀 Quick Start

📦 Installation

Requirements

Global Install

Without Install (npx)

🎯 Usage

Commands

arch-ai init — Step by Step

🗂️ Templates

Backend Templates

backend-mvp — Backend MVP

backend-clean — Backend Clean Architecture

backend-microservice — Backend Microservice

Full-Stack Templates

nextjs-basic — Next.js Basic

nextjs-ddd — Next.js DDD

nextjs-saas — Next.js SaaS ⭐

⚡ Features (Add-ons)

🤖 AI Integration

Option 1 — Groq (Recommended, Free ✅)

Option 2 — Anthropic Claude

Option 3 — Google Gemini

Without AI

AI Regeneration Feature

🗄️ Project Structure (ArchAI Source)

⚙️ Configuration

Environment Variables

🤝 Contributing

1. Fork & Clone

2. Run in Development

3. Build

4. Project Areas to Contribute

5. Adding a New Template

6. Submit a PR

Code Style

🗺️ Roadmap

🐛 Common Issues

arch-ai: command not found

AI suggestions not working

Directory already exists error

📊 Tech Stack

📄 License

🙏 Acknowledgements

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`arch-ai init` — Step by Step

`backend-mvp` — Backend MVP

`backend-clean` — Backend Clean Architecture

`backend-microservice` — Backend Microservice

`nextjs-basic` — Next.js Basic

`nextjs-ddd` — Next.js DDD

`nextjs-saas` — Next.js SaaS ⭐

`arch-ai: command not found`

`Directory already exists` error

Packages