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!