mirror of
https://github.com/utopia-os/utopia-ui.git
synced 2025-12-13 07:46:10 +00:00
updated readme
This commit is contained in:
parent
1828f29cfb
commit
e83887746c
103
README.md
103
README.md
@ -4,30 +4,117 @@ The Utopia Map is a flexible collaborative app for decentralized coordination an
|
||||
|
||||
Utopia Map is made for networks and initiatives that aim to connect people in real life. By providing a custom instance of Utopia Map, each network can grow and coordinate its ecosystem effectively while encouraging real-world interactions and collaborations.
|
||||
|
||||
**Utopia Map** is based on **[Utopia UI](https://github.com/utopia-os/utopia-ui)**.
|
||||
**Utopia Map** is based on our library **[Utopia UI](https://github.com/utopia-map/lib)**.
|
||||
|
||||
## Key Features
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Key Features](#key-features)
|
||||
- [Architecture](#architecture)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [Tech Stack](#tech-stack)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Development](#development)
|
||||
- [Deployment Options](#deployment-options)
|
||||
- [Examples](#examples)
|
||||
- [Support](#support)
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
- **Interactive Map**: The core feature is an intuitive geographical map where users can add, edit, and manage items like members, activities, and resources. Each map instance has its own identity, users, and unique configuration.
|
||||
- **Customizable Layers**: Items are organized into predefined Layers, each with specific icons, colors, texts, and Map Markers. This ensures clarity and relevance for different networks.
|
||||
- **Dynamic Map Markers**: Geographic position of item are indicated on the map by adaptive and customizable Map Markers
|
||||
- **Dynamic Map Markers**: Geographic positions of items are indicated on the map by adaptive and customizable Map Markers
|
||||
- **Popups**: Clicking a Map Marker reveals a Popup — a compact preview of the Item with its most relevant information. Define custom Popups for each of your Layers.
|
||||
- **Profiles**: Each Item has a dedicated Profile that showcases all its associated data, making it easier to explore and manage. Define custom profiles for each of your Layers.
|
||||
- **Authentication System**: Built-in user authentication with login, signup, and password reset functionality
|
||||
- **Permission Management**: Role-based access control for different user types
|
||||
- **Gaming Elements**: Quest system for gamification and user engagement
|
||||
|
||||
## Deployment Options
|
||||
## 🏗️ Architecture
|
||||
|
||||
- **SaaS**: A hosted solution with regular updates and support for easy onboarding and maintenance.
|
||||
- **Self-Hosted**: Deploy on your own infrastructure to retain full control and customization.
|
||||
Utopia Map consists of three main parts:
|
||||
|
||||
## Getting Started
|
||||
### 1. Frontend Application (`/frontend`)
|
||||
A React-based single-page application that provides the user interface for the map and all its features.
|
||||
|
||||
Clone the repository and get started with the following commands:
|
||||
### 2. Component Library (`/lib` - published as `utopia-ui`)
|
||||
A reusable React component library (v3.0.106) that contains all the UI components needed to build mapping applications.
|
||||
|
||||
### 3. Backend (`/backend`)
|
||||
A Directus-powered backend that handles data management, user authentication, and API services.
|
||||
|
||||
## 🔑 Core Concepts
|
||||
|
||||
- **Maps**: Each instance can have its own identity, users, and unique configuration
|
||||
- **Items**: Geographic entities added to the map (members, activities, resources)
|
||||
- **Layers**: Predefined categories for organizing items with specific icons, colors, and markers
|
||||
- **Popups**: Compact previews shown when clicking map markers
|
||||
- **Profiles**: Detailed views for each item with customizable templates
|
||||
- **Tags**: Flexible categorization system for items
|
||||
- **Permissions**: Fine-grained role-based access control
|
||||
- **Attestations**: Verification system for items and users
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
### Frontend
|
||||
- **React 18** with TypeScript
|
||||
- **Vite** for fast development and building
|
||||
- **Tailwind CSS** & **DaisyUI** for styling
|
||||
- **React Router** for navigation
|
||||
- **@directus/sdk** for backend communication
|
||||
- **Leaflet** for map functionality
|
||||
|
||||
|
||||
### Component Library (Utopia UI)
|
||||
- **Rollup** for building
|
||||
- **TypeScript** for type safety
|
||||
- **Vitest** for unit testing
|
||||
- **Cypress** for component testing
|
||||
- **TypeDoc** for documentation
|
||||
|
||||
### Backend
|
||||
- **Directus CMS**
|
||||
- **Docker**
|
||||
- **GraphQL** & **REST API**
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Node.js (see `.tool-versions` for specific version)
|
||||
- npm or yarn
|
||||
|
||||
### Installation
|
||||
|
||||
Clone the repository and install dependencies:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/utopia-os/utopia-map.git
|
||||
cd utopia-map
|
||||
```
|
||||
|
||||
#### Frontend Development
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The frontend will be available at `http://localhost:5173`.
|
||||
|
||||
#### Component Library Development
|
||||
```bash
|
||||
cd lib
|
||||
npm install
|
||||
npm run start # Watch mode
|
||||
npm run build # Production build
|
||||
```
|
||||
|
||||
#### Backend Setup
|
||||
```bash
|
||||
cd backend
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
## Get your Map! 🌱 🌍
|
||||
|
||||
Start mapping and growing your community ecosystem together with your custom map.
|
||||
|
||||
8
frontend/package-lock.json
generated
8
frontend/package-lock.json
generated
@ -18,7 +18,7 @@
|
||||
"react-dom": "^18.2.0",
|
||||
"react-rnd": "^10.4.1",
|
||||
"react-router-dom": "^6.23.0",
|
||||
"utopia-ui": "^3.0.105"
|
||||
"utopia-ui": "^3.0.106"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint-community/eslint-plugin-eslint-comments": "^4.4.1",
|
||||
@ -11438,9 +11438,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/utopia-ui": {
|
||||
"version": "3.0.105",
|
||||
"resolved": "https://registry.npmjs.org/utopia-ui/-/utopia-ui-3.0.105.tgz",
|
||||
"integrity": "sha512-QihvnHeR0R9GXIZ/Mx1EBlsYBthhykM/jPdfN/5bHyyBAXGX0jm+6msEySo0jFWASxPr2G4rhImJJzeRxPyUhw==",
|
||||
"version": "3.0.106",
|
||||
"resolved": "https://registry.npmjs.org/utopia-ui/-/utopia-ui-3.0.106.tgz",
|
||||
"integrity": "sha512-O7G+iS0VBa9bOghzYCZnpRjyhrExCw0bloI97ch8MxDsiGoC0qPlvemp1GeO4HHfR1gJrTcVHWiUJMbEqaFqXQ==",
|
||||
"license": "GPL-3.0-only",
|
||||
"dependencies": {
|
||||
"@heroicons/react": "^2.0.17",
|
||||
|
||||
@ -20,7 +20,7 @@
|
||||
"react-dom": "^18.2.0",
|
||||
"react-rnd": "^10.4.1",
|
||||
"react-router-dom": "^6.23.0",
|
||||
"utopia-ui": "^3.0.105"
|
||||
"utopia-ui": "^3.0.106"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint-community/eslint-plugin-eslint-comments": "^4.4.1",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user