Skip to content

README.md

Latest commit

 

History

History
121 lines (96 loc) · 4.52 KB

README.md

File metadata and controls

121 lines (96 loc) · 4.52 KB

BuildBrief 🚀

From Vague Idea to Production-Ready Spec — in minutes, not weeks.

BuildBrief is an AI-powered interview app that transforms half-baked app ideas into comprehensive "Mega-Prompt" specifications. Designed for vibecoders — people building apps with AI tools like Cursor, Windsurf, and Bolt — it acts as a Senior Technical Product Manager, asking the right questions, making smart decisions automatically, and producing a spec document you can hand directly to an AI coding agent.

✨ Features

  • AI-Driven Interview — A dynamic 5–10 question flow that adapts based on your project's complexity. No fixed questionnaire.
  • Idea Analysis — Validates your concept immediately with a vision statement, implementation approaches, and honest cautions.
  • Auto-Decisions — The AI makes non-critical technical decisions for you (database type, auth method, folder structure) and shows them in a live sidebar.
  • Target-Specific Exports — Export your spec formatted for Cursor (.cursorrules), Windsurf (.windsurfrules), or Bolt, or download as Markdown.
  • Task Breakdown — Post-spec AI-generated implementation checklist with phases, priorities, and time estimates. Interactive — check off tasks as you build.
  • Starter Prompt — A ready-to-paste first message for your AI coder, generated alongside the spec.
  • Session Persistence — Your interview progress survives tab closes and page refreshes (localStorage with 24h expiry).
  • Error Recovery — Automatic retries with visual feedback. Go Back and Start Over buttons at every step.
  • Existing Project Support — "I have an existing project" mode that focuses on extensions, not starting from scratch.
  • Aurora Design System — A premium glassmorphic dark/light UI with Clash Display typography and subtle grain textures.

🛠️ Tech Stack

Client

  • React 18 + Vite 5
  • TypeScript (strict mode)
  • Tailwind CSS v4 + Aurora design system
  • Framer Motion (animations)
  • Lucide React (icons)
  • React Markdown + React Router

Server

  • Node.js + Express
  • OpenRouter API (xiaomi/mimo-v2-flash)
  • TypeScript (strict mode)
  • Zod (request validation)
  • Winston-style structured logger

Shared

  • Unified type definitions in shared/types.ts
  • Path aliases (@shared/*) configured in both client and server

🚀 Getting Started

Prerequisites

Installation

  1. Clone the repository

    git clone https://github.com/arjun-arihant/BuildBrief.git
cd buildbrief

  2. Setup Server

    cd server
npm install
cp .env.example .env

    Edit .env and set your OPENROUTER_API_KEY.

  3. Setup Client

    cd ../client
npm install

Running the App

  1. Start the Server (Terminal 1)

    cd server
npm run dev

    Server runs on http://localhost:3000.

  2. Start the Client (Terminal 2)

    cd client
npm run dev

    Client runs on http://localhost:5173.

  3. Open http://localhost:5173 in your browser.

📖 How It Works

  1. Describe your idea — "A Tinder for adopting rescue dogs" is enough.
  2. AI analyzes it — You get a vision statement, suggested app name, and implementation approaches.
  3. Answer a few questions — The AI asks only what matters architecturally (5–10 questions max).
  4. Review auto-decisions — Watch the sidebar fill with smart defaults the AI chose for you.
  5. Get your spec — A detailed Mega-Prompt covering user stories, data models, API design, and tech stack.
  6. Break into tasks — Optional: generate a phased implementation checklist with time estimates.
  7. Export & build — Download for Cursor/Windsurf/Bolt and start building immediately.

📁 Project Structure

buildbrief/
├── client/          # React frontend (Vite)
│   └── src/
│       ├── components/  # UI components + templates
│       ├── hooks/       # usePersistedSession
│       ├── lib/         # exportFormats, utils
│       └── pages/       # LandingPage, AppPage
├── server/          # Express backend
│   └── src/
│       ├── index.ts     # Routes + middleware
│       ├── openrouter.ts # AI integration
│       ├── prompts.ts   # System prompts
│       └── state.ts     # In-memory session store
├── shared/          # Shared TypeScript types
│   └── types.ts
└── docs/            # GitHub Pages site

📄 License

MIT