The Beans - Coffee Roaster Discovery App

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.

Features

Core Features

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 & Favourites: Rate roasters and save your favourites
Image Uploads: Upload and share roaster photos
Notifications: Stay updated on new roasters and activity

Technical Features

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

Architecture

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

Quick Start (Docker - Recommended)

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

Prerequisites

Setup Steps

Clone the repository

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

Start all services
```
docker-compose up --build
```
Access the applications
- Frontend: http://localhost:3000
- Backend API: http://localhost:5000
- API Documentation: http://localhost:5000/api-docs

Development Workflow

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

👤 Default Admin Account

Email: admin@example.com
Password: admin123

Database Management

# 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

Contact Us Email Setup

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

# Email Recipients
CONTACT_US_EMAIL=your-contact-email@example.com  # Receives Contact Us form submissions
ADMIN_EMAIL=admin@example.com                    # 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.

Documentation

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

Core Documentation

Feature Documentation

Project Structure

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.

Development

Key Development Patterns

API Routes (`server/src/routes/`)

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

Frontend API Client (`client/src/lib/api.ts`)

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

Database (Prisma)

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

Adding New Features

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

Testing Strategy

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

Deployment

For complete deployment documentation, see the Deployment Guide.

Render.com (Recommended)

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

Connect your GitHub repository to Render.com
Create a new Blueprint from your repository (Render will detect render.yaml)

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

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

Docker-Based Deployment

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

Database Migration

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

Contributing

Development Process

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

Code Standards

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

Important Development Notes

Docker-First Workflow

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

Do Not Edit Compiled Files in Containers

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.

Common Issues

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 admin@example.com / admin123

URLs & Access

Frontend: http://localhost:3000
Backend: http://localhost:5000
API Docs: http://localhost:5000/api-docs
Admin Panel: http://localhost:3000/admin

License

MIT License - see LICENSE file for details.

Support

Email: support@the-beans.app
Issues: GitHub Issues
Documentation: ./docs/
Setup Help: SETUP.md

Name		Name	Last commit message	Last commit date
Latest commit History 456 Commits
.github		.github
client		client
docs		docs
server		server
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
git_files.txt		git_files.txt
package-lock.json		package-lock.json
package.json		package.json
post-roasters.py		post-roasters.py
render.yaml		render.yaml
setup.ps1		setup.ps1
setup.sh		setup.sh

License

thephm/the-beans

Folders and files

Latest commit

History

Repository files navigation

The Beans - Coffee Roaster Discovery App

Features

Core Features

Technical Features

Architecture

Quick Start (Docker - Recommended)

Prerequisites

Setup Steps

Development Workflow

👤 Default Admin Account

Database Management

Contact Us Email Setup

Documentation

Core Documentation

Feature Documentation

Project Structure

Development

Key Development Patterns

API Routes (server/src/routes/)

Frontend API Client (client/src/lib/api.ts)

Database (Prisma)

Adding New Features

Testing Strategy

Deployment

Render.com (Recommended)

Docker-Based Deployment

Database Migration

Contributing

Development Process

Code Standards

Important Development Notes

Docker-First Workflow

Do Not Edit Compiled Files in Containers

Common Issues

URLs & Access

License

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

API Routes (`server/src/routes/`)

Frontend API Client (`client/src/lib/api.ts`)

Packages