A full-featured platform for volunteers and charitable organizations, built to gamify good deeds and build an active community.
- β¨ About the project
- πΈ Screenshots
- π Key features
- π οΈ Tech stack and architecture
- βοΈ Quick start
- πΆββοΈ User scenarios
- π¨βπ» Developer guide
- βοΈ Deployment
- π₯ Authors and contacts
- π License
MAX Dobro is a web application built to bring together people who want to do good deeds and organizations that need help. The platform is not only a bulletin board for volunteer events, but also adds gamification and social-network elements to boost engagement.
Key project goals:
- Simplify the search for volunteer activities.
- Motivate users through a karma system, achievements, and rewards.
- Educate volunteers via built-in courses and tests.
- Build a community through stories, comments, and a friends system.
- Provide convenient tools for event organizers.
Place a few key screenshots of the app here to clearly show its interface.
| Home screen | Event details | User profile |
|---|---|---|
 |
 |
 |
| Rewards shop | Organizer panel | Achievements |
|---|---|---|
 |
 |
 |
- Event feed and map: Find events as a list or on an interactive map.
- Gamification:
- Karma points and good hours: Earned for participating in events.
- Achievements ("achievs"): Awarded for completing specific goals.
- Rewards shop: Spend karma on virtual items.
- Weekly challenges: Extra tasks for bonus rewards.
- Learning: Built-in courses with tests and the ability to earn a certificate.
- Social features:
- Stories feed: Share impressions from events.
- Friends, likes, comments: Interact with other volunteers.
- Profile: Track your progress, stats, achievements, and certificates.
- Subscriptions: Follow news from your favorite organizations.
- Control panel: A convenient interface for managing an organization's activities.
- Event creation and management: The full lifecycle from draft to publication.
- Participant management: Approve and reject volunteer applications.
- Statistics: Analytics on subscribers, events, and ratings.
- Authentication: Seamless login via the MAX platform and standard registration via Supabase (email/password).
- AI assistant: A chatbot for quick navigation and information lookup.
- Leaderboards: Compete with other volunteers for the title of most active.
The project is built on a microservice (in this case, service-oriented) architecture and consists of three independent parts:
- Backend (API): The core of the application, handling all business logic.
- Frontend (Mini App): The client application the user interacts with.
- Chat Bot: The entry point for users of the MAX platform.
A simple architecture diagram can be inserted here.
[User] <--> [MAX Platform] <--> [Chat Bot]
|
+-----> [Frontend (Mini App)] <--> [Backend API] <--> [PostgreSQL (Supabase)]
^
|
[Supabase Auth (Webhooks)]
- Framework: NestJS (Node.js)
- Language: TypeScript
- Database: PostgreSQL (managed via Supabase)
- ORM: Prisma
- Authentication: Supabase Auth + JWT + MAX Auth
- API: REST API with Swagger documentation
- Framework: React
- Bundler: Vite
- Language: TypeScript
- Styling: Tailwind CSS
- Maps: Leaflet + React Leaflet
- Platform: MAX Bot API
- Runtime: Node.js + TypeScript
- Docker and Docker Compose
- Node.js (v20+) and npm
- Git
git clone https://github.com/ShutovKS/MAX-Dobro.git
cd MAX-DobroCreate .env files in each of the folders (backend, frontend, chat-bot) based on the *.env.example files.
PORT: Port for the backend server. 3001 is the default value.MAX_BOT_TOKEN: Your bot token from the MAX platform. Required for MAX login validation.MINI_APP_URL: The URL of your deployed frontend application.JWT_INTERNAL_SECRET: Secret key for signing internal JWTs. Generate it withopenssl rand -base64 32.DATABASE_URL: The connection string to your Supabase database (Project Settings -> Database -> Connection string -> URI). Add?pgbouncer=trueat the end for better performance.DIRECT_URL: The same asDATABASE_URL.SUPABASE_URL: Your Supabase project URL (Project Settings -> API -> Project URL).SUPABASE_ANON_KEY: Supabase anonymous public key (Project Settings -> API -> Project API Keys).SUPABASE_WEBHOOK_SECRET: Any secret string you come up with. It must be specified in the webhook settings in Supabase ( Database -> Webhooks).
VITE_API_BASE_URL: The URL of your local backend (e.g.,http://localhost:3001).VITE_API_MODE: Set torealto work with the backend ormockto use mock data.VITE_SUPABASE_URL: Your Supabase project URL.VITE_SUPABASE_ANON_KEY: Supabase anonymous public key.
BOT_TOKEN: The bot token from the MAX platform.BOT_NAME: The bot's MAX username without the @.
This file launches all three services (without a local DB, since Supabase is used).
docker-compose up --build -d- Frontend will be available at:
http://localhost:3000 - Backend API will be available at:
http://localhost:3001 - Swagger Docs will be available at:
http://localhost:3001/api/docs
After the first launch of the containers, apply migrations and seed the database.
# Apply migrations to the Supabase database
docker-compose exec backend npm run migrate:dev
# (Optional) Seed the database with test data
docker-compose exec backend npm run seed- The user registers in the app via Supabase or logs in via MAX.
- Goes through a short onboarding, selecting the directions of interest (e.g., "Ecology", "Animals").
- On the home screen, sees a map with nearby events and an event feed.
- Finds "Park cleanup", opens the details, reads the requirements.
- Clicks "I'll help" and confirms participation.
- After the event, leaves feedback and receives karma points, hours, and possibly their first achievement.
- A user with the
organizationrole logs in. They are redirected to the control panel. - Clicks "Create event" and fills in all fields: title, description, date, location, requirements.
- Publishes the event. It appears in the common feed for volunteers.
- In the "Event management" section, tracks new applications.
- Reviews volunteer profiles and confirms their participation.
- After the event is held, the event chat is archived, and participants automatically receive rewards.
The project is divided into three main directories:
/backend: NestJS application./frontend: React (Vite) application./chat-bot: Node.js application for the MAX bot.
All commands are run from the root folder of the corresponding service (e.g., cd backend).
npm run start:dev: Start the service in development mode with hot-reload.npm run build: Build the production version.npm run lint: Check the code with ESLint.npm run format: Format the code with Prettier.
- Backend: Configured for deployment on Vercel (
vercel.json). - Frontend: Docker container with Nginx for serving static files.
- Chat Bot: Can be deployed on any Node.js hosting (e.g., Render, Vercel).
Provide information about yourself or the team here.