🎨 Blueprint - Visual Microservice Builder

Build Go microservices visually with drag-and-drop - No code required!

Blueprint is a visual platform for building Go microservices using the Unicorn framework. Design backend flows with drag-and-drop, generate production-ready code instantly.

🚀 Quick Start

Prerequisites

Go 1.21+
Node.js 20+ (or 18+, but 20 is recommended)
MongoDB 7.0+
Docker (optional)

1️⃣ Clone & Install

git clone https://github.com/madcok-co/blueprint.git
cd blueprint

# Install all dependencies
make install

2️⃣ Setup Environment

# Copy environment files
cp backend/.env.example backend/.env

# Edit backend/.env - MUST change in production:
# JWT_SECRET=your-super-secret-key
# MONGO_URI=mongodb://localhost:27017

3️⃣ Start MongoDB

# Option 1: Docker (recommended)
docker run -d -p 27017:27017 --name blueprint-mongo mongo:7.0

# Option 2: Docker Compose
make docker-up

# Option 3: Local MongoDB
# (ensure MongoDB is installed and running)

4️⃣ Run Development

# Terminal 1: Backend
cd backend && go run cmd/server/main.go

# Terminal 2: Frontend  
cd frontend && npm run dev

# Open browser: http://localhost:5173

That's it! 🎉

📁 Project Structure (Simple)

blueprint/
├── backend/              # Go API Server
│   ├── cmd/server/      # Main entry point
│   ├── internal/        # Business logic
│   │   ├── api/         # HTTP handlers
│   │   ├── middleware/  # Auth, logging, etc
│   │   ├── models/      # Data models
│   │   └── services/    # Core logic
│   ├── pkg/             # Shared packages
│   │   ├── auth/        # JWT & password
│   │   ├── database/    # MongoDB
│   │   └── logger/      # Logging
│   └── test/            # Tests
│
├── frontend/            # React UI
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── stores/      # State (Zustand)
│   │   └── services/    # API calls
│   └── dist/            # Production build
│
└── docs/                # Documentation
    └── archive/         # Old docs (safe to ignore)

🎯 Features

✨ Currently Working

✅ Visual Flow Editor - Drag & drop nodes to build APIs
✅ Multi-Trigger Support - HTTP, Message Queue, Cron, gRPC
✅ Code Generation - Generate production-ready Go code
✅ User Authentication - JWT-based auth with refresh tokens
✅ Authorization - User isolation & admin controls
✅ Security - Rate limiting, CORS, security headers
✅ Database - MongoDB with optimized indexes
✅ Error Handling - Comprehensive error & panic recovery
✅ Logging - Structured JSON logging with zap
✅ Testing - 78% test coverage (27 passing tests)
✅ CI/CD - GitHub Actions pipelines ready

🚧 In Progress / Roadmap

⏳ Frontend unit tests
⏳ E2E tests
⏳ Monitoring (Prometheus/Grafana)
⏳ Multi-tenancy
⏳ Billing integration
⏳ Project templates

🔐 Security

Default Security Features

✅ JWT Authentication - Secure token-based auth
✅ Password Hashing - Bcrypt with cost 12
✅ User Isolation - Complete data separation
✅ Rate Limiting - 100 requests/minute default
✅ Security Headers - X-Frame-Options, CSP, HSTS
✅ Input Validation - Request validation
✅ CORS - Configurable origins

⚠️ IMPORTANT: Production Checklist

Before deploying to production, you MUST change:

# backend/.env
JWT_SECRET=<generate-random-secret-64-chars>
MONGO_ROOT_PASSWORD=<strong-password>
SESSION_SECRET=<another-random-secret>

# Set environment
SERVER_ENV=production

Generate secrets:

# Linux/Mac
openssl rand -base64 64

# or use online: https://randomkeygen.com/

🧪 Testing

Run Tests

# Backend tests
cd backend
go test ./... -v -cover

# View coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test Status

✅ 27/27 tests passing (100%)
✅ 78.1% code coverage
✅ No race conditions
✅ All security tests pass

🐳 Docker Deployment

Development

make docker-up

Production

# 1. Edit .env with production values
cp .env.example .env
nano .env

# 2. Build & deploy
docker-compose -f docker-compose.yml up -d --build

# 3. Check status
docker-compose ps

# 4. View logs
docker-compose logs -f

Services:

Frontend: http://localhost (port 80)
Backend: http://localhost:8080
MongoDB: localhost:27017

📖 API Endpoints

Authentication

POST   /api/auth/register      - Register user
POST   /api/auth/login         - Login
POST   /api/auth/refresh       - Refresh token
GET    /api/auth/me           - Get current user (auth)
POST   /api/auth/logout       - Logout (auth)

Projects

GET    /api/projects          - List projects (auth)
POST   /api/projects          - Create project (auth)
GET    /api/projects/:id      - Get project (auth)
PUT    /api/projects/:id      - Update project (auth + owner)
DELETE /api/projects/:id      - Delete project (auth + owner)
POST   /api/projects/:id/generate - Generate code (auth + owner)

Handler Flows

GET    /api/projects/:pid/handlers         - List handlers (auth + owner)
POST   /api/projects/:pid/handlers         - Create handler (auth + owner)
GET    /api/projects/:pid/handlers/:hid    - Get handler (auth + owner)
PUT    /api/projects/:pid/handlers/:hid    - Update handler (auth + owner)
DELETE /api/projects/:pid/handlers/:hid    - Delete handler (auth + owner)

Auth: Bearer token required
Owner: Must own the project

🛠️ Development Commands

# Install dependencies
make install

# Run development
make dev

# Build
make build              # Both backend + frontend
make build-backend      # Backend only
make build-frontend     # Frontend only

# Tests
make test               # Run backend tests

# Docker
make docker-up          # Start containers
make docker-down        # Stop containers
make docker-logs        # View logs

# Clean
make clean              # Remove build artifacts

# Help
make help               # Show all commands

🐛 Troubleshooting

MongoDB connection failed

# Check MongoDB running
docker ps | grep mongo

# Restart MongoDB
docker restart blueprint-mongo

# Check connection string
# backend/.env: MONGO_URI=mongodb://localhost:27017

Port already in use

# Change ports in .env
BACKEND_PORT=8081
FRONTEND_PORT=3001
MONGO_PORT=27018

Frontend build fails

# Clear cache & reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

Tests fail (MongoDB required)

# Start MongoDB first
docker run -d -p 27017:27017 mongo:7.0

# Then run tests
cd backend && go test ./...

📊 Current Status

Component	Status	Coverage
Backend	✅ Production Ready	-
Frontend	✅ Production Ready	-
Auth System	✅ Complete	78%
Authorization	✅ Complete	-
Code Generation	✅ Working	-
Tests	✅ Passing	78%
CI/CD	✅ Configured	-
Documentation	✅ Complete	-

Production Ready: YES ✅
Test Coverage: 78.1% (target: 70%)
Security: Hardened ✅

📚 Documentation

Quick Links

Getting Started: Read the Quick Start section above
API Reference: Check the API Endpoints section
Deployment: Check the Docker Deployment section
Project Structure: Check the PROJECT_STRUCTURE.md file
Security Guide: Check the SECURITY.md file

Detailed Docs (Archive)

Complete documentation is stored in docs/archive/:

Implementation plans
Phase completion reports
Security test checklists
Health check reports

You usually don't need to read these unless you need technical details.

🤝 Contributing

We love contributions! Blueprint is open source and we welcome contributions from the community.

Ways to Contribute

🐛 Report bugs
💡 Suggest new features
📝 Improve documentation
🔧 Submit pull requests
⭐ Star the project

Quick Start for Contributors

Fork the repository

Clone your fork

git clone https://github.com/YOUR_USERNAME/blueprint.git
cd blueprint

Create a branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Follow our coding standards
- Add tests for new features
- Update documentation
Run tests
```
make test
```

Commit your changes

git commit -m 'feat: Add amazing feature'

Push to your fork
```
git push origin feature/amazing-feature
```
Open a Pull Request

Guidelines

Code Style
- Backend: Follow standard Go conventions (go fmt)
- Frontend: ESLint + Prettier configured
Testing
- Add tests for new features
- Minimum coverage: 70%
- All tests must pass before merge
Commits
- Use Conventional Commits
- Examples: feat:, fix:, docs:, refactor:

For detailed guidelines, see CONTRIBUTING.md

Code of Conduct

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

📝 License

MIT License - See LICENSE file for details

🙋 Support

Issues: https://github.com/madcok-co/blueprint/issues
Docs: Check docs/ folder
Repository: https://github.com/madcok-co/blueprint

🎉 Acknowledgments

Built with Go + Gin
Frontend: React + TypeScript + Vite
Database: MongoDB
Auth: JWT + Bcrypt
Testing: Testify
UI: React Flow

Made with ❤️ for developers who love visual tools

🚀 Happy building!

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
docs/archive		docs/archive
frontend		frontend
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCS_SUMMARY.md		DOCS_SUMMARY.md
LICENSE		LICENSE
Makefile		Makefile
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
start-dev.sh		start-dev.sh

Latest commit

History

Folders and files

Repository files navigation