MyBMAD Dashboard

A web dashboard - https://mybmad.hichem.cloud/ - to visualize and track BMAD (Breakthrough Method of Agile AI-Driven Development) projects from your GitHub repositories — or directly from local folders.

License: MIT — see LICENSE for details.

---

Table of Contents

• What is MyBMAD Dashboard?
• Tech Stack
• Quick Start
• Project Structure
• Available Scripts
• Production Deployment
• Documentation
• Contributing
• License

---

What is MyBMAD Dashboard?

MyBMAD Dashboard connects to your GitHub repositories (or local folders), reads the BMAD project structure (epics, stories, sprint status, docs), and displays everything in a clean, real-time dashboard. It is designed for solo developers and small teams who use the BMAD methodology with AI coding agents.

Key features:

• Import any GitHub repository that follows the BMAD structure
• Import local folders — no GitHub needed for self-hosted setups (learn more)
• Visualize epic progress and story status at a glance
• Support for chunked epics (individual files in epics/ directory) as well as a single epics.md
• Browse BMAD docs and planning artifacts directly in the app
• Track sprint status and velocity metrics
• Repo settings modal to switch branches directly from the UI
• Email/password authentication and optional GitHub OAuth login
• Multi-user support with role management (admin / user)
• Self-hostable with Docker and automatic TLS via Traefik

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript
Database	PostgreSQL + Prisma
Auth	Better Auth (email/password + GitHub OAuth)
GitHub API	@octokit/rest
UI	React 19 + Tailwind CSS v4 + shadcn/ui
Deployment	Docker + Traefik (automatic TLS)
Tests	Vitest

---

Quick Start

Full guide with all environment variables explained: docs/GETTING_STARTED.md

git clone https://github.com/DevHDI/my-bmad.git
cd my-bmad
pnpm install

# Auto-generate .env with secrets
bash scripts/setup.sh

# Start PostgreSQL
docker compose up -d

# Run migrations & create admin
pnpm db:migrate
pnpm db:create-admin --email you@example.com --password your_password --name Admin

# Start dev server
pnpm dev

Open http://localhost:3002 and log in.

---

Project Structure

my-bmad/
├── src/
│   ├── app/                    # Next.js App Router pages and API routes
│   │   ├── (dashboard)/        # Authenticated dashboard pages
│   │   │   ├── page.tsx        # Home — projects overview
│   │   │   ├── repo/           # Per-repository views (epics, stories, docs)
│   │   │   ├── admin/          # Admin panel (user management)
│   │   │   └── profile/        # User profile
│   │   ├── api/
│   │   │   ├── auth/           # Better Auth handler
│   │   │   ├── health/         # Health check endpoint
│   │   │   └── revalidate/     # Cache revalidation webhook
│   │   └── login/              # Login page
│   ├── components/             # React components
│   │   ├── dashboard/          # Dashboard-specific components
│   │   ├── docs/               # Markdown/doc viewer components
│   │   ├── epics/              # Epics & stories components
│   │   ├── layout/             # Sidebar, header, nav
│   │   └── ui/                 # shadcn/ui base components
│   ├── lib/
│   │   ├── auth/               # Better Auth configuration
│   │   ├── bmad/               # BMAD parser (reads repo structure)
│   │   ├── db/                 # Prisma client and helpers
│   │   └── github/             # Octokit client with retry/throttle
│   └── actions/                # Next.js Server Actions
├── prisma/
│   ├── schema.prisma           # Database schema
│   └── migrations/             # Migration history
├── docker/
│   ├── docker-compose.prod.yml # Production Docker Compose
│   └── DEPLOY.md               # Production deployment guide
├── docs/                       # Documentation
├── _bmad/                      # BMAD methodology system (used to build this app)
└── _bmad-output/               # Planning artifacts generated during development

---

Available Scripts

pnpm dev              # Start development server (port 3002)
pnpm build            # Build for production
pnpm start            # Start production server
pnpm lint             # Run ESLint
pnpm test             # Run tests (Vitest)
pnpm test:watch       # Run tests in watch mode
pnpm db:generate      # Generate Prisma client
pnpm db:migrate       # Run database migrations (dev)
pnpm db:push          # Push schema changes without migration
pnpm db:studio        # Open Prisma Studio (database GUI)
pnpm db:create-admin  # Create an admin user from the CLI

---

Production Deployment (Docker)

See the full guide in docker/DEPLOY.md.

Quick summary:

1. Clone the repo on your VPS
2. Create .env and .env.local from .env.example
3. Create the external Docker network: docker network create web
4. Launch: docker compose --env-file .env -f docker/docker-compose.prod.yml up -d
5. Run migrations: docker compose ... exec my-bmad npx prisma migrate deploy

The stack includes:

• Next.js application container
• PostgreSQL database
• Traefik reverse proxy with automatic Let's Encrypt TLS

---

Documentation

Document	Description
Getting Started	Full local setup guide with all environment variables
Local Folder Import	Import BMAD projects from the filesystem without GitHub
API Endpoints	REST API reference (revalidation, health check)
Production Deployment	Docker + Traefik deployment guide
Contributing	How to contribute to the project
Security	Vulnerability reporting policy

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

---

Security

Found a vulnerability? Please read our SECURITY.md and report it responsibly.

---

License

This project is licensed under the MIT License.

You are free to use, modify, and distribute this software, including for commercial purposes, as long as the original copyright notice is preserved. See LICENSE for the full license text.

---

Acknowledgements

Built with the BMAD Method — an AI-driven agile development methodology.