Hive Sudbury Connect

A comprehensive full-stack community platform for Greater Sudbury, connecting residents with local government, services, and each other.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation & Setup

1. Clone the repository

   git clone <your-repo-url>
   cd hive-sudbury-connect

2. Start all services

   docker-compose up -d

3. Wait for services to be ready (about 30-60 seconds)

   docker-compose logs -f backend
   # Wait for "Server running on port 3001" and database connections

4. Seed the database with sample data

   docker-compose exec backend npm run seed

5. Access the application

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:3001
   • API Health Check: http://localhost:3001/health

Default Login Credentials

Username: mayor_sudbury
Password: password123

Username: concerned_citizen  
Password: password123

🏗️ Architecture

Frontend (React + TypeScript)

• Framework: React 18.3.1 with TypeScript
• Build Tool: Vite 5.4.1
• Styling: Tailwind CSS + Shadcn UI
• Routing: React Router Dom
• State Management: React Query + Context API
• Forms: React Hook Form + Zod validation

Backend (Node.js + Express)

• Runtime: Node.js 20+ with Express.js
• Database: PostgreSQL 15 (primary) + MongoDB 7 (flexible data)
• Authentication: JWT with bcrypt password hashing
• File Upload: Multer middleware
• Real-time: Socket.io for live updates
• Security: Helmet, CORS, rate limiting

Infrastructure

• Containerization: Docker + Docker Compose
• Reverse Proxy: Nginx (production)
• Caching: Redis
• Database Persistence: Docker volumes

📊 Features

🏛️ Municipal Integration

• Department Pages: Direct communication with city departments
• Official Announcements: Verified posts from city officials
• Service Requests: Report issues directly to relevant departments
• Event Calendar: City meetings, public hearings, community events

🏘️ Community Features

• Subcommunities: Neighborhood groups, interest-based communities
• Discussion Threads: Reddit-style voting and nested comments
• User Profiles: Customizable profiles with verification badges
• Following System: Follow users and subcommunities

📱 Social Media Features

• Post Types: Text, images, videos, polls, events
• Real-time Updates: Live comments, votes, and notifications
• Search: Full-text search across posts and users
• Mobile Responsive: Works perfectly on all devices

🔒 Security & Moderation

• Content Reporting: Community moderation tools
• User Verification: Official verification for city staff
• Rate Limiting: API protection against abuse
• Data Privacy: GDPR-compliant user controls

🗄️ Database Schema

PostgreSQL Tables

• users - User accounts and profiles
• posts - Community posts and announcements
• comments - Threaded comment system
• votes - Upvote/downvote system
• subcommunities - Community groups
• departments - City departments and services
• events - Community events and meetings
• notifications - User notification system

MongoDB Collections

• users - Extended user preferences and metadata
• posts - Flexible post content and media
• comments - Complex comment threading and reactions

🛠️ Development

Local Development Setup

1. Environment Variables

   cp .env.example .env
   # Edit .env with your configuration

2. Start development environment

   docker-compose up -d

3. View logs

   docker-compose logs -f backend
   docker-compose logs -f frontend

Database Management

Access PostgreSQL

docker-compose exec postgres psql -U postgres -d sudbury_community

Access MongoDB

docker-compose exec mongodb mongosh sudbury_community

Reset Database

docker-compose down -v
docker-compose up -d
docker-compose exec backend npm run seed

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user
• POST /api/auth/refresh - Refresh JWT token

Posts

• GET /api/posts - Get posts with pagination
• POST /api/posts - Create new post
• GET /api/posts/:id - Get single post
• PUT /api/posts/:id - Update post
• DELETE /api/posts/:id - Delete post
• POST /api/posts/:id/vote - Vote on post

Comments

• GET /api/comments/:postId - Get post comments
• POST /api/comments - Create comment
• PUT /api/comments/:id - Update comment
• DELETE /api/comments/:id - Delete comment
• POST /api/comments/:id/vote - Vote on comment

Users

• GET /api/users/:id - Get user profile
• PUT /api/users/:id - Update user profile
• GET /api/users/:id/posts - Get user's posts
• POST /api/users/:id/follow - Follow/unfollow user

Subcommunities

• GET /api/subcommunities - Get all subcommunities
• GET /api/subcommunities/:slug - Get subcommunity details
• POST /api/subcommunities - Create subcommunity
• POST /api/subcommunities/:id/join - Join subcommunity

🚢 Production Deployment

Using Docker Compose (Recommended)

1. Clone and configure

   git clone <your-repo-url>
   cd hive-sudbury-connect
   cp .env.example .env
   # Configure production environment variables

2. Start with Nginx

   docker-compose --profile production up -d

3. Setup SSL (optional)

   # Add your SSL certificates to ./ssl/
   # Update nginx.conf for HTTPS

Environment Variables for Production

NODE_ENV=production
JWT_SECRET=your-super-secure-secret-key
DATABASE_URL=postgresql://user:pass@db:5432/sudbury_community
MONGODB_URI=mongodb://user:pass@mongo:27017/sudbury_community
FRONTEND_URL=https://yourdomain.com

📈 Monitoring & Maintenance

Health Checks

• Backend: http://localhost:3001/health
• Database connections verified on startup
• Docker health checks configured

Backups

# PostgreSQL backup
docker-compose exec postgres pg_dump -U postgres sudbury_community > backup.sql

# MongoDB backup
docker-compose exec mongodb mongodump --db sudbury_community --out /tmp/backup

Logs

# View all logs
docker-compose logs

# Follow specific service
docker-compose logs -f backend

# Save logs to file
docker-compose logs > app.log

🤝 Contributing

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

📝 License

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

📞 Support

For support and questions:

• Create an issue on GitHub
• Contact the development team
• Check the documentation in /docs

---

Built with ❤️ for the Greater Sudbury community