Shelldo - Production-Ready Todo Application

A scalable todo application built for 10 million users with OAuth authentication, real-time features, and modern React design.

🚀 Features

• OAuth Authentication: Google, GitHub, and Microsoft login
• Production-Ready Architecture: Built to handle 10M+ users
• Real-time Updates: Instant synchronization across devices
• Smart Organization: Categories, priorities, and due dates
• Team Collaboration: Share todos and work together
• Offline Support: Works without internet connection
• Modern UI: Clean, responsive design with dark mode
• Enterprise Security: JWT sessions, rate limiting, audit logs

🛠 Technology Stack

• Frontend: Next.js 15, React 19, TypeScript
• Backend: Next.js API Routes, Prisma ORM
• Database: PostgreSQL with optimized indexing
• Caching: Redis for performance and rate limiting
• Authentication: NextAuth.js with OAuth 2.0
• Styling: Tailwind CSS v4, Radix UI components
• Testing: Vitest, React Testing Library
• DevOps: Docker, GitHub Actions CI/CD

📋 Prerequisites

• Node.js 18+
• npm or yarn
• PostgreSQL database
• Redis server (optional - graceful fallback)
• OAuth credentials (Google, GitHub, Microsoft)

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/RidgetopAi/shelldo.git
cd shelldo

# Install dependencies and setup
npm run setup

2. Environment Configuration

Copy the environment template and configure your settings:

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/shelldo"

# JWT Secrets
JWT_SECRET="your-super-secure-jwt-secret-key"
NEXTAUTH_SECRET="your-nextauth-secret"
NEXTAUTH_URL="http://localhost:3000"

# OAuth Providers
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

GITHUB_CLIENT_ID="your-github-client-id" 
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Optional: Redis for caching
REDIS_URL="redis://localhost:6379"

3. Database Setup

# Run database migrations
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

4. Development Server

# Start development server
npm run dev

# Or use the Windows startup script
./startup.bat

Visit http://localhost:3000 to see the application.

🏗 Development Commands

# Setup (install, migrate, generate)
npm run setup

# Development
npm run dev              # Start dev server with Turbopack
npm run dev:daemon       # Start as daemon, logs to logs.txt
npm run build           # Build for production
npm run start           # Start production server

# Testing & Quality
npm run test            # Run Vitest tests
npm run lint            # Run ESLint

# Database
npm run db:reset        # Reset database and run migrations

🔧 Configuration

OAuth Setup

Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: http://localhost:3000/api/auth/callback/google

GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth App
3. Set Authorization callback URL: http://localhost:3000/api/auth/callback/github

Microsoft OAuth

1. Go to Azure Portal
2. Register new application in Azure AD
3. Add redirect URI: http://localhost:3000/api/auth/callback/microsoft

Database Configuration

The application uses PostgreSQL with optimized schemas for high performance:

• Connection pooling for efficient database usage
• Indexes on frequently queried columns
• Audit logging for security and compliance
• Soft deletes for data recovery

Redis Configuration (Optional)

Redis provides caching and rate limiting. If unavailable, the app gracefully falls back to in-memory alternatives.

🏭 Production Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Scale for high availability
docker-compose up -d --scale app=3

Environment Variables for Production

# Security
NODE_ENV=production
JWT_SECRET="complex-production-secret"
NEXTAUTH_SECRET="complex-nextauth-secret"

# Database
DATABASE_URL="postgresql://user:pass@db-host:5432/shelldo"

# Redis
REDIS_URL="redis://redis-host:6379"

# OAuth (use production URLs)
NEXTAUTH_URL="https://your-domain.com"

📊 Performance & Scaling

Built for 10M Users

• Rate limiting: 100 requests/hour per user
• Caching: Redis-backed response caching
• Database optimization: Proper indexing and query optimization
• CDN ready: Static asset optimization
• Horizontal scaling: Stateless architecture

Monitoring

• Health checks: /api/health endpoint
• Metrics: OpenTelemetry compatible
• Logging: Structured JSON logs
• Error tracking: Built-in error boundaries

🔒 Security Features

• OAuth 2.0 authentication with major providers
• JWT session management with secure cookies
• Rate limiting to prevent abuse
• CORS protection with allowed origins
• Security headers (HSTS, CSP, etc.)
• Input validation with Zod schemas
• SQL injection protection via Prisma ORM
• Audit logging for all user actions

🧪 Testing

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test structure:

• Unit tests: Component and utility testing
• Integration tests: API route testing
• E2E tests: Full user flow testing

📁 Project Structure

shelldo/
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── api/            # API routes
│   │   ├── auth/           # Authentication pages
│   │   └── dashboard/      # Main app interface
│   ├── components/         # React components
│   │   ├── ui/            # Base UI components
│   │   └── todo/          # Todo-specific components
│   ├── lib/               # Utilities and configurations
│   │   ├── hooks/         # Custom React hooks
│   │   ├── contexts/      # React contexts
│   │   └── utils/         # Helper functions
│   └── styles/            # Global styles
├── prisma/                # Database schema and migrations
├── __tests__/             # Test files
├── public/                # Static assets
└── docs/                  # Additional documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Use ESLint and Prettier for code formatting
• Write tests for new features
• Update documentation for API changes
• Follow conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the /docs folder for detailed guides
• Issues: Report bugs on GitHub Issues
• Discussions: Join conversations in GitHub Discussions

🎯 Roadmap

• Mobile app development (React Native)
• Advanced analytics dashboard
• AI-powered task suggestions
• Advanced team collaboration features
• Plugin system for extensibility
• Multi-language internationalization

---

Built with ❤️ for productivity and scale