Bopper — Personal Chief-of-Staff

Bopper is an open-source personal assistant that helps you manage calendars, tasks, and priorities in one unified interface. Connect your Google Calendar, create tasks, set priorities, and stay organized.

✨ Features

• 📅 Calendar Sync: Automatically sync events from Google Calendar
• ✓ Task Management: Create, organize, and complete tasks
• 🎯 Prioritization: Intelligent priority system based on due dates & time estimates
• 🔐 Secure Auth: Google OAuth 2.0 with encrypted token storage
• ⚡ Real-time Sync: Incremental calendar sync with webhook support
• 🚀 Full Stack: TypeScript everywhere (frontend + backend)
• 🐳 Docker Ready: Deploy with one command

🚀 Quick Start

For Users (5 minutes)

1. Go to https://bopper.local
2. Click "Connect with Google Calendar"
3. Authorize Bopper
4. Start managing your priorities!

→ See User Guide

For Developers (10 minutes)

# 1. Clone & install
git clone https://github.com/bopper/bopper.git
cd bopper
pnpm install

# 2. Configure
cp .env.example .env.local
# Edit with Google OAuth credentials

# 3. Database setup
pnpm --filter server prisma migrate dev

# 4. Start dev servers
pnpm dev

Visit http://localhost:3000 (web) and http://localhost:4000 (API)

→ See Quick Start Guide

For Operators (Docker)

# 1. Configure
cp .env.example .env
# Edit with your settings

# 2. Deploy
docker-compose up -d

# 3. Initialize
docker-compose exec server npm run migrate

# 4. Verify
curl http://localhost:4000/health

→ See Admin Guide

📚 Documentation

Document	Audience	Contents
USER_GUIDE.md	End Users	Getting started, features, FAQ, tips
ADMIN_GUIDE.md	Operators	Deployment, config, monitoring, security
TECHNICAL_GUIDE.md	Developers	Architecture, API reference, development
QUICK_START.md	Everyone	5-minute setup for all roles
CLAUDE.md	Internal	Development conventions & workflows
docs/ARCHITECTURE.md	Architects	System design & data flow

🏗️ Architecture

Frontend (Next.js)          Backend (Express)           Storage
├─ Home                     ├─ OAuth 2.0                ├─ PostgreSQL
├─ Dashboard               ├─ Calendar API             ├─ Redis
├─ Calendars               ├─ Task API                 └─ Encrypted Tokens
├─ Tasks                   ├─ Token Manager
└─ Settings                ├─ Sync Worker
                          └─ Error Handler

Tech Stack:

• Frontend: Next.js 14, React 18, TypeScript
• Backend: Express.js, Node 18, TypeScript
• Database: PostgreSQL 15, Prisma ORM
• Cache/Queue: Redis 7, BullMQ
• Auth: Google OAuth 2.0, AES-256-GCM encryption
• Deployment: Docker, Docker Compose, Kubernetes

🔐 Security

• Encrypted Tokens: OAuth tokens encrypted at rest with AES-256-GCM
• Secure Sessions: httpOnly cookies with CSRF protection
• HTTPS: TLS 1.3 for all production traffic
• OAuth 2.0: Delegated Google authentication (no password storage)
• Rate Limiting: API endpoint throttling to prevent abuse
• SQL Injection: Prisma ORM with parameterized queries

📊 Roadmap

MVP (Current)

• Google Calendar OAuth
• Calendar sync (incremental)
• Task management
• Dashboard
• Task prioritization

v0.2 (Next)

• Webhook listeners for real-time sync
• Recurring task templates
• Calendar conflict detection
• Email digest summaries
• Mobile app

v1.0 (Future)

• Outlook/iCloud calendar support
• Slack integration
• AI-powered prioritization
• Time tracking
• Analytics dashboard

🛠️ Development

Common Tasks

# Development
pnpm dev              # Start dev servers
pnpm build            # Build for production
pnpm test             # Run tests

# Database
pnpm --filter server prisma migrate dev      # Create migration
pnpm --filter server prisma studio           # Open GUI

# Code Quality
pnpm lint             # Check code style
pnpm format           # Auto-format code

# Docker
docker-compose up -d  # Start services
docker-compose down   # Stop services
docker-compose logs   # View logs

Project Structure

bopper/
├── server/              # Express API
│   ├── src/
│   │   ├── auth/       # Google OAuth
│   │   ├── api/        # REST endpoints
│   │   ├── services/   # Business logic
│   │   ├── middleware/ # Auth, errors, CORS
│   │   └── lib/        # Utilities
│   └── prisma/         # Database schema
├── web/                # Next.js frontend
│   └── app/            # Pages & components
├── docs/               # Documentation
└── docker-compose.yml  # Deployment config

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Getting Started with Code

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Follow CLAUDE.md for code style
4. Submit a pull request

Code Style

• TypeScript: Strict mode, type-safe
• Formatting: Prettier
• Linting: ESLint
• Commits: Atomic, action-focused messages

# Auto-fix code
pnpm lint:fix
pnpm format:fix

📄 License

MIT - See LICENSE for details

🆘 Support

• Documentation: Read docs/ for comprehensive guides
• Issues: Report bugs on GitHub Issues
• Discussions: Ask questions on GitHub Discussions
• Email: support@bopper.local

🙏 Acknowledgments

• Next.js - React framework
• Express - Web framework
• Prisma - ORM
• BullMQ - Job queue
• Google Calendar API - Calendar data

---

Made with ❤️ for organizing chaos.

📖 User Guide • ⚙️ Admin Guide • 🔧 Technical Guide • ⚡ Quick Start