Mappins - Map Information Sharing Platform

Version: 1.0.0 Created: 2025-08-28 Updated: 2025-08-28 Author: Kim Hsiao

Overview

Mappins is a community platform based on maps that allows users to share and edit location information, and manage content changes through a version control system. The platform combines Geographic Information Systems (GIS), community interaction features, and collaborative editing mechanisms.

Features

• Map-based location information management
• WYSIWYG Markdown editor
• Git-like version control system
• Multimedia content support (text, images, videos, documents)
• Member system and community features
• Personal blog functionality
• Cross-platform support

Tech Stack

Frontend

• Web: React 18.3.1 + TypeScript + Vite
• Mobile: React Native 0.75.2 + Expo 51.0.20
• Desktop: Electron + React
• Map Service: OpenStreetMap + Leaflet
• Editor: TinyMCE / Quill.js + Markdown support
• State Management: Zustand / Redux Toolkit
• UI Framework: Shadcn UI + Tailwind CSS
• i18n: React i18next (Traditional Chinese/Simplified Chinese/English)

Backend (Microservices)

• API Gateway: Nginx
• User Service: Port 3001
• Location Service: Port 3002
• Version Control Service: Port 3003
• Blog Service: Port 3004
• Social Service: Port 3005
• File Service: Port 3006
• Search Service: Port 3007
• Admin Service: Port 3008
• Chat Service: Port 3009

Data Layer

• PostgreSQL 16.4 (Main database)
• Redis 7.2.5 (Cache & Session)
• MeiliSearch 1.10.1 (Search engine)
• MinIO RELEASE.2025-08-06T01-26-25Z (File storage)

Infrastructure

• Docker Compose
• Prometheus 2.54.0 (Monitoring)
• Grafana 11.2.0 (Visualization)
• RabbitMQ 3.13.2 (Message broker)

Project Structure

mappins/
├── README.md
├── CHANGELOG.md
├── LICENSE
├── .gitignore
├── .editorconfig
├── .env.example
├── docker-compose.yml
├── frontend/
│   ├── web/
│   ├── mobile/
│   └── desktop/
├── backend/
│   ├── services/
│   │   ├── user-service/
│   │   ├── location-service/
│   │   ├── version-service/
│   │   ├── blog-service/
│   │   ├── social-service/
│   │   ├── file-service/
│   │   ├── search-service/
│   │   ├── admin-service/
│   │   └── chat-service/
│   └── packages/
├── docs/
└── scripts/

Development Setup

Prerequisites

• Bun 1.x (runtime environment and package manager)
• Docker 25.x
• Docker Compose 2.x

Installation

1. Clone the repository:

   git clone <repository-url>
   cd mappins

2. Install dependencies:

   # Install all dependencies
   bun install

3. Set up environment variables:

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

4. Start the development environment:

   docker-compose up -d

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and continuous deployment:

CI Pipeline

• Runs on every push to main and develop branches
• Runs on every pull request to main and develop branches
• Performs code quality checks (linting, formatting, type checking)
• Runs unit tests

CD Pipeline

• Runs on every push to main branch
• Builds and pushes Docker images
• Deploys to staging environment
• Deploys to production environment (manual trigger)

Configuration

• CI workflow: .github/workflows/ci.yml
• CD workflow: .github/workflows/cd.yml

Secrets Required

• DOCKERHUB_USERNAME: Docker Hub username
• DOCKERHUB_TOKEN: Docker Hub access token

Development Guidelines

• Use bun for all Node.js package management and package management
• Use bun instead of node.js runtime environment
• Write all documentation in English
• Update CHANGELOG.md after each development
• Add appropriate and effective comments in all development files, written in English
• Store all environment settings, URLs, port numbers, environment variables, private passwords, and other sensitive or environment-dependent data in .env or .yaml files
• Use uv for Python-related settings or environments
• Use the latest/stable (LTS) versions for all packages and container images
• Reference context7 for all development work

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License