VibeWork

A production-ready, VIBE Code compliant monorepo with a modular monolith backend (Bun + ElysiaJS) and React frontend, featuring User (MySQL/Drizzle) and Notification (MongoDB/Typegoose) modules, with comprehensive testing, internationalization, and GCP-focused infrastructure.

📚 Documentation

Comprehensive documentation available in multiple languages:

English

• Complete Documentation - Full English documentation
  • Getting Started
  • Architecture Overview
  • Backend Guide
  • Frontend Guide
  • Infrastructure Guide
  • Deployment Guide
  • Contributing Guide

Português (Brasil)

• Documentação Completa - Documentação em português
  • Primeiros Passos
  • Visão Geral da Arquitetura
  • Guia do Backend (em inglês, veja en-US)
  • Guia do Frontend (em inglês, veja en-US)
  • Guia de Infraestrutura (em inglês, veja en-US)
  • Guia de Deployment (em inglês, veja en-US)
  • Guia de Contribuição (em inglês, veja en-US)

🚀 Quick Start

Prerequisites

• Bun 1.0+ (Install)
• Docker & Docker Compose (Install)
• Git

Setup (5 minutes)

# 1. Clone repository
git clone <repository-url>
cd VibeWork

# 2. Install dependencies
bun install

# 3. Configure environment
cp .env.example .env
# Edit .env with your settings

# 4. Start services
docker-compose up -d

# 5. Run migrations
cd backend && bun run db:migrate

# 6. Start development servers
cd .. && bun run dev

Open:

• Frontend: http://localhost:5173
• Backend: http://localhost:3000
• API Docs: http://localhost:3000/swagger

See Getting Started Guide for detailed setup.

🏗️ Project Structure

VibeWork/
├── backend/                    # ElysiaJS API backend
├── frontend/                   # React SPA
├── shared/
│   └── contract/              # Shared TypeBox schemas
├── infra/                     # Terraform IaC (GCP)
├── e2e/                       # Playwright tests
├── docs/                      # Documentation
│   ├── en-US/                 # English docs
│   └── pt-BR/                 # Portuguese docs
└── docker-compose.yml         # Local dev services

🛠️ Tech Stack

Layer	Technology	Purpose
Runtime	Bun 1.2.8	Fast JavaScript runtime
Backend	ElysiaJS	Type-safe REST API
Frontend	React 18 + Vite	Modern SPA
SQL DB	MySQL 8.0 + Drizzle	Relational data
Document DB	MongoDB 6.0 + Typegoose	Document storage
Cache	Redis 7.0	Performance caching
Events	Google Cloud Pub/Sub	Async messaging
Email	AWS SES	Email delivery
Auth	Better-Auth	Authentication
RPC	Eden	Type-safe API calls
State Mgmt	TanStack Query	Server state
i18n	i18next	Localization (en, pt-BR)
Testing	Vitest + Playwright	Unit & E2E tests
Monorepo	Turborepo + Bun	Build orchestration

📖 Key Features

• Type-Safe End-to-End: TypeBox schemas used by frontend and backend
• Modular Monolith: Backend architecture ready for microservice extraction
• Event-Driven: Pub/Sub for async operations
• Multi-Language: Built-in support for English and Portuguese
• Comprehensive Testing: Unit, integration, and E2E tests
• Production-Ready: Database backups, monitoring, zero-downtime deployment
• Infrastructure as Code: Terraform for GCP infrastructure

🔧 Common Commands

# Development
bun install                    # Install dependencies
docker-compose up -d           # Start services
bun run dev                    # Start all dev servers
bun run db:migrate             # Run database migrations

# Testing
bun run test                   # Unit tests
bun run test:integration       # Integration tests
bun run test:e2e               # E2E tests
bun run test:coverage          # Coverage report

# Code Quality
bun run lint                   # Check linting
bun run lint:fix               # Auto-fix linting
bun run typecheck              # TypeScript check
bun run format                 # Format code

# Building
bun run build                  # Build all packages
bun run clean                  # Clean artifacts

See CLAUDE.md for detailed command reference.

📚 Documentation Map

Getting Started

• Setup Guide (English) - Environment configuration
• Guia de Início (Português) - Configuração em português
• Architecture Overview (English) - System design and data flows
• Visão Geral da Arquitetura (Português) - Design do sistema

Backend (English)

• Backend Setup - Installation and configuration
• API Reference - Complete endpoint documentation
• Modules Guide - Users & Notifications architecture
• Database Guide - MySQL, MongoDB, schemas & migrations
• Infrastructure - Redis, Pub/Sub, SES, health checks
• Testing Guide - Unit, integration tests

Frontend (English)

• Frontend Setup - Development environment
• Components Guide - React components & patterns
• State Management - TanStack Query guide
• Internationalization - i18n configuration
• Testing Guide - Component & E2E tests

Shared Packages (English)

• Contract Package - TypeBox schemas & validation
• UI Components - Component library

Infrastructure & Deployment (English)

• Infrastructure Guide - Docker, GCP, services
• Deployment Guide - Production deployment & CI/CD
• Contributing Guide - Code standards & workflow

Original Module Documentation (CLAUDE.md)

• backend/CLAUDE.md - Backend overview & commands
• frontend/CLAUDE.md - Frontend overview
• backend/modules/users/CLAUDE.md - Users & authentication
• backend/modules/notifications/CLAUDE.md - Notifications system
• shared/contract/CLAUDE.md - Shared contracts

🎯 Architecture

┌────────────────────────────┐
│  Frontend (React + Vite)   │
│  TanStack Query + Eden RPC │
└──────────────┬─────────────┘
               │ HTTP/REST
┌──────────────▼─────────────┐
│ Backend (ElysiaJS + Bun)  │
│ ├── Users Module           │
│ └── Notifications Module   │
└──────────────┬─────────────┘
               │
    ┌──────────┼──────────┬────────────┐
    ▼          ▼          ▼            ▼
  MySQL    MongoDB     Redis       Pub/Sub
  (Data)   (Docs)     (Cache)    (Events)

🔐 Security

• Passwords hashed with Argon2id (OWASP recommended)
• HTTP-only session cookies
• Input validation on all endpoints
• HTTPS/TLS in production
• Rate limiting at reverse proxy
• Environment variables for secrets

📊 Testing Coverage

• Unit Tests: 80%+ coverage
• Integration Tests: Critical paths covered
• E2E Tests: User workflows covered
• Performance: Monitoring and alerts configured

🌍 Internationalization

• English (en) - Default
• Portuguese (Brazil) (pt-BR) - Fully translated
• Easy to add more languages via i18n

🚀 Deployment

Development

docker-compose up -d
bun run dev

Staging

gcloud run deploy vibe-backend-staging \
  --image gcr.io/project/vibe-backend:staging

Production

gcloud run deploy vibe-backend \
  --image gcr.io/project/vibe-backend:latest \
  --region us-central1

See Deployment Guide for details.

📝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -m "feat: description"
4. Push to branch: git push origin feature/my-feature
5. Create Pull Request

See Contributing Guide for conventions.

📄 License

MIT License - see LICENSE file for details

🤝 Support

English

• Check documentation
• Review existing issues
• Start discussion
• See CLAUDE.md for original project documentation

Português (Brasil)

• Consulte a documentação
• Revise problemas existentes
• Inicie uma discussão
• Veja CLAUDE.md para documentação original do projeto

🔗 Resources

• Bun Documentation - JavaScript runtime
• ElysiaJS Documentation - Backend framework
• React Documentation - Frontend framework
• TanStack Query - State management
• TypeBox - Schema validation
• Drizzle ORM - SQL ORM
• Typegoose - MongoDB ODM
• i18next - Localization

🌐 Supported Languages

• 🇬🇧 English - Full documentation available
• 🇧🇷 Português (Brasil) - Partial documentation (getting started, architecture)
• More languages can be easily added via i18n

👥 Authors

Built with VibeWork framework and VIBE Code standards.

---

Status: Production-Ready ✅ Version: 1.0.0 Last Updated: December 2024 License: MIT

Quick Links

• 🚀 Quick Start
• 📚 English Docs | Portuguese Docs
• 🤝 Contributing
• 📖 Full Documentation Map
• 🏗️ Architecture Overview

Get started in 5 minutes: Follow the Quick Start section above!