PromptArch/README.md

# PromptArch: The Prompt Enhancer 🚀

> **Development Note**: This entire platform was developed exclusively using [TRAE.AI IDE](https://trae.ai) powered by elite [GLM 4.7 model](https://z.ai/subscribe?ic=R0K78RJKNW).
> **Learn more about this architecture [here](https://z.ai/subscribe?ic=R0K78RJKNW).**

---

> **Fork Note**: This project is a specialized fork of [ClavixDev/Clavix](https://github.com/ClavixDev/Clavix), reimagined as a modern web-based platform for visual prompt engineering and product planning.

Transform vague ideas into production-ready prompts and PRDs. PromptArch is an elite AI orchestration platform designed for software architects and Vibe Coders.

**Developed by Roman | RyzenAdvanced**

- 📦 **Gitea Repository**: [admin/PromptArch](https://github.rommark.dev/admin/PromptArch)
- 📮 **Telegram**: [@VibeCodePrompterSystem](https://t.me/VibeCodePrompterSystem)

## 🌟 Visual Overview

### 🛠 Core Capabilities

- **Prompt Enhancer**: Refine vague prompts into surgical instructions for AI agents.
- **PRD Generator**: Convert ideas into structured Product Requirements Documents.
- **Action Plan**: Decompose PRDs into actionable development steps and framework recommendations.

## ✨ Features

- **Multi-Provider Ecosystem**: Native support for Qwen Code (OAuth), Ollama Cloud, and Z.AI Plan API.
- **Visual Prompt Engineering**: Patterns-based enhancement with 11+ intent types.
- **Architectural Decomposition**: Automatic generation of PRDs and structured Action Plans.
- **Resilient Fallbacks**: Multi-tier provider system that ensures uptime even if primary APIs fail.
- **Modern UI/UX**: Built with Next.js 15, Tailwind CSS, and shadcn/ui for a seamless developer experience.
- **OAuth Integration**: Secure Qwen authentication with 2,000 free daily requests.

## 🚀 Quick Start

1. **Clone & Install**:
   ```bash
   git clone https://github.rommark.dev/admin/PromptArch.git
   cd PromptArch
   npm install
   ```

2. **Configuration**:
   Copy `.env.example` to `.env` and add your API keys:
   ```bash
   cp .env.example .env
   ```

3. **Launch**:
   ```bash
   npm run dev
   ```

4. Open [http://localhost:3000](http://localhost:3000) to begin.

## 📋 Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [1.2.0] - 2025-01-19

#### Added
- **SEO Agent Behavior Fixes**
  - SEO agent now stays locked and answers queries through an SEO lens
  - Smart agent suggestions via `[SUGGEST_AGENT:xxx]` marker for clearly non-SEO tasks
  - Visual suggestion banner with Switch/Dismiss buttons
  - Prevented unwanted agent auto-switching mid-response
- **z.ai API Validation**
  - Real-time API key validation with 500ms debounce
  - Inline status indicators:
    - ✓ Green checkmark with "Validated Xm ago" for valid keys
    - ✗ Red X with error message for invalid keys
    - 🔄 Loading spinner during validation
  - "Test Connection" button for manual re-validation
  - Persistent validation cache (5 minutes) in localStorage
  - Clear error messages: "Invalid API key", "Network error", etc.
- **Store Enhancements**
  - `ApiValidationStatus` interface for tracking connection states
  - `apiValidationStatus` state with per-provider tracking
  - `setApiValidationStatus` action for updating validation results

#### Changed
- Updated Settings panel with improved UX for API key management
- Enhanced agent selection behavior to prevent unintended switches
- Improved error handling for authentication failures

#### Technical Details
- Files modified:
  - `lib/store.ts` - Added validation state management
  - `lib/services/zai-plan.ts` - Added `validateConnection()` method
  - `lib/services/model-adapter.ts` - Added validation proxy
  - `components/SettingsPanel.tsx` - Complete rewrite with validation UI
  - `components/AIAssist.tsx` - Added suggestion handling and UI

### [1.1.0] - 2025-01-15

#### Added
- GitHub integration for pushing AI-generated artifacts
- XLSX export functionality for Google Ads campaigns
- High-fidelity HTML report generation
- OAuth token management for Qwen API

### [1.0.0] - 2025-01-01

#### Added
- Initial release of PromptArch
- Multi-provider AI support (Qwen, Ollama, Z.AI)
- Prompt Enhancer with 11+ intent patterns
- PRD Generator with structured output
- Action Plan generator with framework recommendations
- Visual canvas for live code rendering
- Multi-language support (English, Russian, Hebrew)

## 🛠 Tech Stack

- **Framework**: [Next.js 15.5](https://nextjs.org/) (App Router)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/)
- **State Management**: [Zustand](https://zustand-demo.pmnd.rs/)
- **Components**: [shadcn/ui](https://ui.shadcn.com/)
- **Icons**: [Lucide React](https://lucide.dev/)

## 🤝 Attribution & Credits

**Author**: Roman | RyzenAdvanced
- 📦 **Gitea**: [admin/PromptArch](https://github.rommark.dev/admin/PromptArch)
- 📮 **Telegram**: [@VibeCodePrompterSystem](https://t.me/VibeCodePrompterSystem)

**Forked from**: [ClavixDev/Clavix](https://github.com/ClavixDev/Clavix)
- This project is a visual and architectural evolution of the Clavix framework
- Clavix focuses on agentic-first Markdown templates
- PromptArch provides a centralized web interface with advanced model orchestration

**Development Platform**: [TRAE.AI IDE](https://trae.ai) powered by elite [GLM 4.7 model](https://z.ai/subscribe?ic=R0K78RJKNW)
- 100% AI-assisted development using TRAE.AI's advanced coding capabilities
- Learn more about the architecture [here](https://z.ai/subscribe?ic=R0K78RJKNW)

## Development

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint
```

## License

ISC

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.