TeamMapper

TeamMapper is a self‑hosted, real‑time mind‑mapping service that extends the discontinued mindmapp project by adding collaborative features via WebSockets. The application exposes a RESTful API for CRUD operations on mindmaps and a separate WebSocket channel that propagates node edits, cursor movements, and chat messages to all connected clients. Internally the backend is a Node.js/TypeScript service built on Fastify for low‑latency request handling, while the frontend is a React/TypeScript SPA that consumes the REST endpoints and subscribes to the WebSocket stream. The data model is persisted in a PostgreSQL database (the README ships with a Docker Compose template that uses postgres:12-alpine), and the service automatically purges maps older than a configurable number of days, which is useful for GDPR compliance.

Technical Stack

• Backend: Node.js 20+, TypeScript, Fastify, pg for PostgreSQL connectivity, socket.io (or native WebSocket) for real‑time collaboration.
• Frontend: React 18+, TypeScript, Vite as the build tool, react-flow or similar for node rendering, and a state‑management layer (Redux Toolkit or Zustand) that mirrors the backend’s real‑time updates.
• Database: PostgreSQL 12+ (the Docker image uses 12‑alpine). All CRUD operations are performed via parameterized SQL queries to avoid injection risks.
• Containerization: The repository provides a pre‑built Docker image (ghcr.io/b310-digital/teammapper:latest) and a ready‑to‑use docker-compose.yml. The compose file exposes environment variables for database credentials, SSL flags, and map‑retention settings.
• Deployment: The app listens on a configurable BINDING address and exposes HTTP/HTTPS endpoints. It can be fronted by any reverse proxy (NGINX, Traefik) and supports TLS termination via the same certificate files mounted into the PostgreSQL container.

Core Capabilities

• Real‑time Collaboration: WebSocket channel broadcasts node creation, deletion, and property changes. Clients receive delta updates that are merged into the local state without full re‑rendering.
• Import/Export: The API supports JSON, Mermaid, SVG, PDF, and PNG formats. Importing a Mermaid string triggers a parser that translates it into the internal node structure.
• Access Control: Each map can be shared with a view‑only or edit link. The backend validates the token on each WebSocket connection and enforces permissions at the message level.
• Undo/Redo: The frontend maintains a command stack that is synchronized with the server, allowing users to revert or reapply changes locally and remotely.
• QR‑Code Sharing: A lightweight endpoint generates a QR image that encodes the share URL, making mobile access trivial.

Deployment & Infrastructure

TeamMapper is designed to run in a Docker‑based environment, but it can also be compiled locally and executed as a native binary. The only external dependency is PostgreSQL; the compose file ships with an SSL‑enabled Postgres instance for secure data at rest. For scaling, the WebSocket server can be clustered behind a sticky‑session load balancer; Fastify’s HTTP layer is stateless, so horizontal scaling is straightforward. Because the data model is relational and the API is idempotent, database sharding or read replicas can be introduced without major refactoring.

Integration & Extensibility

The application exposes a REST API (/api/maps, /api/maps/:id) that can be consumed by custom frontends or automation scripts. Webhooks are not yet implemented, but the architecture allows for an event bus (e.g., Kafka) to be plugged in. The source code is modular; developers can replace the rendering engine or swap out PostgreSQL for another SQL database with minimal effort. A plugin system is not part of the current release, but the codebase follows a clear separation between domain logic and presentation, making future extensions (e.g., AI‑powered node suggestions) straightforward.

Developer Experience

Configuration is driven entirely by environment variables, which are well documented in the README. The Docker Compose template includes comments explaining each variable and how to enable SSL. Unit tests cover the API routes, and integration tests spin up a test database using pg-mem. The repository’s issue tracker is active, and the community provides quick responses to pull requests. Documentation for the API endpoints is minimal but sufficient; developers can generate OpenAPI specs from the Fastify routes if needed.

Use Cases

• Team Collaboration Platforms: Embed TeamMapper behind an internal portal to allow distributed teams to brainstorm in real time.
• Education: Use the import/export features to create lesson plans that can be shared as Mermaid diagrams or PDFs.
• Product Management: Integrate the API into a custom product roadmap tool that stores maps in a central database.
• Compliance‑Focused Environments: The automatic deletion of old maps and GDPR‑friendly defaults make it suitable for regulated industries.

Advantages

TeamMapper’s lightweight Node.js stack delivers low latency, and its use of PostgreSQL ensures ACID guarantees for collaborative edits. Compared to cloud‑hosted alternatives, developers gain full control over data residency, can customize the rendering engine, and avoid vendor lock‑in. The application’s open‑source license (MIT) permits commercial use without royalties, and the Docker images simplify onboarding while still allowing for deep customization