A beautiful, modern full-stack web application for discovering and exploring specialty coffee roasters. Built with Next.js 14, Express.js, and PostgreSQL in a Docker-first development environment.

• 🌍 Location-based Discovery: Find coffee roasters near you
• ☕ Roaster Profiles: Detailed information including contact info, hours, and bean offerings
• � Owner Contact Information: Store roaster owner details (name, email, bio, mobile)
• �👥 User Authentication: Secure sign up and login system
• ⭐ Reviews & Favorites: Rate roasters and save your favorites
• 📸 Image Uploads: Upload and share roaster photos
• 🔔 Notifications: Stay updated on new roasters and activity

• 🔒 Secure API: RESTful API with comprehensive Swagger documentation
• 🌐 Internationalization: Full i18n support (English/French)
• 💜 Beautiful Design: Purple-themed UI with lavender, violet, and orchid colors
• 🔒 Admin Dashboard: Complete user and role management (admin only)
• � Audit Logging: Comprehensive activity tracking with geolocation and change history
• �📱 Responsive Design: Works seamlessly on desktop, tablet, and mobile
• 🐳 Docker-First: Containerized development and deployment

• Frontend: Next.js 14 (App Router) with TypeScript
• Backend: Express.js API with Prisma ORM
• Database: PostgreSQL
• Deployment: Docker-based containerization
• CDN: Cloudflare for assets and domain management

⚠️ Critical: This project requires Docker container restarts for code changes to take effect. Hot reload is unreliable due to Docker volume mounting.

• Docker Desktop
• Git

1. Clone the repository

   git clone https://github.com/thephm/the-beans.git
   cd the-beans

2. Start all services

   docker-compose up --build

3. Access the applications

   • 🌐 Frontend: http://localhost:3000
   • 🔧 Backend API: http://localhost:5000
   • 📚 API Documentation: http://localhost:5000/api-docs

Essential: Always restart containers after code changes:

# After making frontend changes
docker-compose restart client

# After making backend changes  
docker-compose restart server

# Rebuild everything if needed
docker-compose up --build

# Stop all services
docker-compose down

• Email: [email protected]
• Password: admin123

# Connect to PostgreSQL shell
docker exec -it the-beans-database-1 psql -U beans_user -d the_beans_db

# Check admin users
docker exec -it the-beans-database-1 psql -U beans_user -d the_beans_db -c "SELECT email, username, role FROM users WHERE role = 'admin';"

# Run database migrations
docker-compose exec server npx prisma migrate dev

# Generate Prisma client after schema changes
docker-compose exec server npx prisma generate

# Reset database (careful!)
docker-compose exec server npx prisma migrate reset

To enable the Contact Us form and email notifications, configure the following environment variables in server/.env:

# Email Recipients
CONTACT_US_EMAIL=[email protected]  # Receives Contact Us form submissions
ADMIN_EMAIL=[email protected]                    # Receives admin notifications

# SMTP Server Configuration
SMTP_HOST=smtp.yourprovider.com                  # e.g., smtp.gmail.com, smtp.fastmail.com
SMTP_PORT=587                                    # 587 for TLS, 465 for SSL
SMTP_USER=your-smtp-username                     # Usually your email address
SMTP_PASS=your-smtp-password                     # App-specific password or API key

After updating .env, restart the server container:

docker-compose restart server

For detailed setup instructions including Gmail, Fastmail, SendGrid, and troubleshooting, see the 📧 Email Configuration Guide.

Comprehensive documentation is maintained in the docs/ directory following docs-as-code principles.

• 🏗️ Architecture Overview
• 📖 Documentation Index
• 📝 Glossary
• ⚙️ Setup Guide
• 🐳 Docker Documentation
• 📋 Project Summary

• 🔐 Authentication System
• 🔍 Search & Discovery
• ☕ Roaster Management
• ⭐ Favorites & Reviews
• 👤 User Profiles
• ⚙️ Settings & Preferences
• 🛡️ Admin Dashboard
• 📊 Audit Logging

the-beans/
├── 🌐 client/                    # Next.js 14 Frontend
│   ├── src/
│   │   ├── app/                 # App Router pages & layouts
│   │   ├── components/          # Reusable React components
│   │   ├── contexts/            # React Context providers
│   │   ├── lib/                # Utilities & configurations
│   │   └── types/              # TypeScript type definitions
│   ├── public/
│   │   ├── locales/            # i18n translation files
│   │   └── images/             # Static images & icons
│   └── Dockerfile              # Frontend container config
├── 🔧 server/                   # Express.js Backend
│   ├── src/
│   │   ├── routes/             # RESTful API endpoints
│   │   ├── middleware/         # Auth & validation middleware
│   │   └── lib/               # Server utilities
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema
│   │   ├── migrations/        # Database migrations
│   │   └── seed.ts           # Database seeding
│   ├── uploads/               # File upload storage
│   └── Dockerfile            # Backend container config
├── 📚 docs/                    # Documentation (docs-as-code)
├── 🐳 docker-compose.yml       # Multi-service orchestration
└── 📋 Various config files     # Setup, CI/CD, etc.

• Authentication: optionalAuth (public), requireAuth (protected)
• Admin Routes: Check user.role === 'admin'
• Validation: express-validator for input sanitization
• Error Handling: Consistent JSON error responses

• Centralized API client with JWT token management
• Base URL: http://localhost:5000 (configurable)
• Automatic token injection and refresh

# After schema changes
docker-compose exec server npx prisma generate
docker-compose exec server npx prisma migrate dev

1. Backend: Add routes in server/src/routes/ with proper middleware
2. Frontend: Create components in client/src/components/
3. Database: Update server/prisma/schema.prisma + generate + migrate
4. i18n: Add translations to client/public/locales/{en,fr}/common.json
5. Restart: Always restart containers after changes

• Frontend: Jest + React Testing Library
• Backend: Jest + Supertest for API testing
• E2E: Playwright for integration tests
• Manual: Admin dashboard at /admin (requires admin login)

For complete deployment documentation, see the Deployment Guide.

The Beans includes a complete render.yaml configuration for one-click deployment on Render.com:

1. Connect your GitHub repository to Render.com
2. Create a new Blueprint from your repository (Render will detect render.yaml)
3. Configure environment variables in Render dashboard:

   # Required for all deployments
   CLOUDINARY_CLOUD_NAME=your_cloud_name
   CLOUDINARY_API_KEY=your_api_key
   CLOUDINARY_API_SECRET=your_secret
   
   # For custom domains (optional)
   CORS_ORIGIN=https://yourdomain.com
   NEXT_PUBLIC_API_URL=https://api.yourdomain.com
   

4. Deploy - Render will automatically create:
   • PostgreSQL database
   • Backend API service (Express.js)
   • Frontend web service (Next.js)

Alternative deployment using Docker containers with docker-compose.yml.

# Automatic via render.yaml build process
# Or manual via Render shell:
npx prisma migrate deploy
npx prisma generate

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Develop using Docker: docker-compose up --build
4. Restart containers after changes: docker-compose restart client server
5. Test your changes thoroughly
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Submit a pull request

• TypeScript: Strict typing required
• ESLint: Follow configured rules
• Prettier: Auto-formatting enabled
• i18n: All user-facing text must be translatable
• Tests: Include tests for new features
• Documentation: Update docs for new features

• Always restart containers after code changes: docker-compose restart client server
• Hot reload is unreliable in the Docker environment
• Database changes require Prisma generate + migrate
• New translations require client container restart

• The project builds TypeScript sources into a dist/ directory during the Docker image build. The files in /app/dist inside a running container are compiled artifacts and are not the authoritative source.
• Do not edit files inside running containers. Changes made directly inside a container are ephemeral and will be overwritten the next time you rebuild the image or recreate the container.
• To apply changes, edit the true source files (for the backend server/src/, for the frontend client/src/) and rebuild/restart the appropriate container(s):

# Rebuild server image and start it
docker-compose up -d --build server

# Or restart after code changes
docker-compose restart server

# Inspect compiled output in a running server container
docker exec the-beans-server-1 ls -la /app/dist

• Recommended CI check: add a job that runs npm run build in the server (and optionally client) package to ensure TypeScript builds succeed on pull requests. This prevents mismatches between src/ and compiled dist/ artifacts.

• Container won't start: Check Docker Desktop is running
• Database connection fails: Ensure PostgreSQL container is healthy
• API calls fail: Verify backend container is running on port 5000
• Changes not visible: Restart the appropriate container
• Admin access needed: Use [email protected] / admin123

• 🌐 Frontend: http://localhost:3000
• 🔧 Backend: http://localhost:5000
• 📚 API Docs: http://localhost:5000/api-docs
• 🛡️ Admin Panel: http://localhost:3000/admin

MIT License - see LICENSE file for details.

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Documentation: ./docs/
• 🚀 Setup Help: SETUP.md