# reearth/reearth-visualizer architecture

> Architecture diagram of the GitHub repository reearth/reearth-visualizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reearth/reearth-visualizer
- Repository: https://github.com/reearth/reearth-visualizer

## Overview

This project is a full‐stack GIS visualization platform (Re:Earth Visualizer) that combines a modern Go-based backend with a rich React/TypeScript frontend. Its purpose is to display and let users interact with spatial data via Cesium and other WebGIS technologies, while also supporting features like interactive geometry editing, conditional layer styling, storytelling, and an extensible plugin system.

##### Main Components
- Frontend (Web): Located in the “web” directory, this is built with React and TypeScript. It handles user interactions, renders the GIS map (using Cesium) and storytelling features, and integrates with plugins through dedicated modules.
- Backend (Server): The “server” directory contains Go code that implements the GraphQL API, handles business logic, authentication, file handling, integration with databases and external services, and supports real-time operations.
- Database & Persistence: The infrastructure (notably under server/internal/infrastructure/mongo and other storage-related packages) indicates that MongoDB is used, possibly with additional support for file storage (e.g., GCS, S3).
- Plugin System & WebAssembly: The project features a plugin system (visible in directories like “server/pkg/plugin” and “web” components handling plugin UI) and uses WebAssembly for executing plugins. This shows extensibility thinking and a clear separation of plugin-related functionalities.
- External Services & API Gateways: This includes authentication (mock auth and possible integrations like Auth0), Cesium Ion token integration for map rendering, and connections with external APIs (GraphQL endpoints, marketplace).
- DevOps and CI/CD: The repository’s .github/workflows and Docker/Docker-compose files indicate continuous integration, deployment scripts, and containerized services.
- Shared Libraries & Utilities: The “pkg”, “internal/usecase”, “services”, and “lib” directories for both server and web provide reusable logic for internationalization (i18n), authentication, error handling, theming and UI components.

##### Relationships and Data Flow
- The Frontend connects to the Backend via GraphQL and REST API endpoints for data (assets, properties, projects, etc.) and also loads plugins (using WebAssembly and dedicated endpoints).
- The Backend communicates with the database (MongoDB) for storing GIS data, projects, users and runs migrations and other business logic.
- External services (Cesium Ion, authentication providers) are integrated into the flow, with the backend providing necessary configuration details to the frontend.
- The plugin system acts as an extension module whereby plugins (developed externally or in-house) can be dynamically deployed and interact with the API.

##### Architectural Patterns & Key Design Principles
- Separation of Concerns:
– Frontend vs. Backend separation is clear.
– Domain logic is separated into use cases, repositories, and adapters (as seen in the “server/internal/usecase” and “server/internal/adapter”).
- Microservice-ish Modularization:
– Although not strictly microservices, the code organization in “internal/infrastructure” and “internal/app” suggests a modular organization.
- Extensibility:
– The plugin system is architected to allow integration via WebAssembly and dedicated plugin packages.
- CI/CD and containerization:
– Docker, Makefiles, and GitHub workflows attest to automated builds, tests, and deployment pipelines.

##### Technologies and Frameworks
- Frontend: React, TypeScript, Yarn; uses libraries such as Cesium for 3D mapping and other UI frameworks.
- Backend: Go, GraphQL server (using gqlgen), and integrations with MongoDB.
- Authentication: Built-in mock auth with the possibility for OpenID Connect or Auth0.
- Testing and Deployment: Docker Compose for environment setup; CI/CD pipelines defined in .github/workflows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend (Web UI)"
        FEApp["React/TypeScript App (Web UI)"]:::frontend
        FEPlugin["Plugin UI (Cesium & Plugin Playground)"]:::frontend
        FEShared["Shared Frontend Services"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Server"
        BE["Go-based API Server (GraphQL)"]:::backend
        BEPlugin["Backend Plugin Support & WebAssembly"]:::backend
        BEConfig["Server Config (GraphQL, Auth, Cesium Ion)"]:::backend
        BEAuth["Auth Integration Module"]:::backend
        BEGateway["GraphQL Auth Gateway"]:::backend
        BEPkg["Backend Shared Library (Pkg)"]:::backend
        BEUsecase["Backend Usecase"]:::backend
        BEAdapter["Backend Adapter"]:::backend
    end

    %% Database & Persistence
    subgraph "Database & Persistence"
        DB["MongoDB Database"]:::database
    end

    %% External Services
    subgraph "External Services"
        ExtCesium["Cesium Ion & External APIs"]:::external
        ExtAuth["Authentication Providers"]:::external
    end

    %% DevOps & CI/CD
    subgraph "DevOps & CI/CD"
        GitHubWF["GitHub Workflows"]:::devops
        DockerCompose["Docker Compose File"]:::devops
        ServerDocker["Server Dockerfile"]:::devops
        WebDocker["Web Dockerfile"]:::devops
    end

    %% Connections - Data Flow
    FEApp -->|"GraphQL/REST calls"| BE
    FEApp -->|"Utilizes"| FEShared
    FEApp -->|"Loads Plugin UI"| FEPlugin

    BE -->|"Handles requests & business logic"| BEConfig
    BE -->|"Integrates with"| BEPlugin
    BE -->|"Uses Shared Libs"| BEPkg
    BE -->|"Executes Domain Logic"| BEUsecase
    BE -->|"Executes Domain Logic"| BEAdapter
    BE -->|"Queries/Updates"| DB
    BEConfig -->|"Manages Auth"| BEAuth
    BEConfig -->|"Manages Auth"| BEGateway
    BEConfig -->|"Integrates with"| ExtCesium
    BEAuth -->|"Validates"| ExtAuth

    GitHubWF --- BE
    GitHubWF --- FEApp
    DockerCompose --- BE
    DockerCompose --- FEApp
    ServerDocker --- BE
    WebDocker --- FEApp

    %% Click Events for Component Mappings
    click FEApp "https://github.com/reearth/reearth-visualizer/tree/main/web/"
    click BE "https://github.com/reearth/reearth-visualizer/tree/main/server/"
    click DB "https://github.com/reearth/reearth-visualizer/tree/main/server/internal/infrastructure/mongo/"
    click BEPlugin "https://github.com/reearth/reearth-visualizer/tree/main/server/pkg/plugin/"
    click FEPlugin "https://github.com/reearth/reearth-visualizer/tree/main/web/src/beta/features/PluginPlayground/"
    click BEConfig "https://github.com/reearth/reearth-visualizer/tree/main/server/internal/app/config/"
    click BEAuth "https://github.com/reearth/reearth-visualizer/tree/main/server/internal/infrastructure/auth0/"
    click BEGateway "https://github.com/reearth/reearth-visualizer/blob/main/server/internal/usecase/gateway/authenticator.go"
    click GitHubWF "https://github.com/reearth/reearth-visualizer/tree/main/.github/workflows/"
    click DockerCompose "https://github.com/reearth/reearth-visualizer/blob/main/docker-compose.yml"
    click ServerDocker "https://github.com/reearth/reearth-visualizer/tree/main/server/Dockerfile"
    click WebDocker "https://github.com/reearth/reearth-visualizer/tree/main/web/Dockerfile"
    click BEPkg "https://github.com/reearth/reearth-visualizer/tree/main/server/pkg/"
    click BEUsecase "https://github.com/reearth/reearth-visualizer/tree/main/server/internal/usecase/"
    click BEAdapter "https://github.com/reearth/reearth-visualizer/tree/main/server/internal/adapter/"
    click FEShared "https://github.com/reearth/reearth-visualizer/tree/main/web/src/services/"

    %% Styles
    classDef frontend fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef backend fill:#e6f2ff,stroke:#0047b3,stroke-width:2px;
    classDef database fill:#e6ffe6,stroke:#008000,stroke-width:2px;
    classDef external fill:#fff2e6,stroke:#b35900,stroke-width:2px;
    classDef devops fill:#ffffe6,stroke:#b3b300,stroke-width:2px;
```
