# neo4j/neo4j-browser architecture

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

- Interactive diagram: https://gitdiagram.com/neo4j/neo4j-browser
- Repository: https://github.com/neo4j/neo4j-browser

## Overview

##### Project type and purpose
- It includes:
– A rich browser-based frontend under `src/browser`
– A companion UI component library (“neo4j-arc”) under `src/neo4j-arc`
– Shared Redux-style state & services logic under `src/shared`
– A minimal Node.js “auth_server” for issuing delegation tokens (for SSO)
– Docker compositions for Keycloak SSO and a Neo4j test database
– Cypress end-to-end tests and unit tests (Jest)

##### File structure
- Top-level directories:
– `src/browser`: React application, webpack entry point, components, hooks, modules, styles
– `src/neo4j-arc`: reusable component library consumed via an alias
– `src/shared`: cross-cutting state management (ducks/epics), services (Bolt driver, remote, localStorage)
– `auth_server`: Node.js service for delegation token endpoint (certificates, HTML pages)
– `docker/sso-keycloak`: docker-compose setup for Keycloak and Neo4j in tests
– `docs`: Antora-based documentation site
– `e2e_tests`: Cypress fixtures, integration and SSO tests
– `build_scripts`, `scripts`: custom build-and-release helpers
- Architectural patterns:
– Component-based UI (React) organized into “modules” by feature (Stream, Sidebar, Frame, Docs, etc.)
– State management via Redux ducks + RxJS epics (thunks in `shared/modules`)
– Shared utility library (neo4j-arc) built separately and consumed via webpack aliases
– Minimal backend (auth_server) for token brokerage, otherwise direct Bolt connections to Neo4j

##### README for additional insights
- Describes how the browser connects directly to a local Neo4j (bolt://localhost:7687) or remote instance
- Mentions SSO support via Keycloak and a local auth server
- Explains testing commands (unit, e2e) and required Docker setup

##### Detail
- Essential parts: webpack dev server, shared modules, subproject build, auth_server endpoints, direct Bolt connections, test harness.
- Special interactions (e.g., SSO token flow, Cosmos-style epics pipeline, Arc library import).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        BBBrowse["User's Web Browser"]:::frontend
        SPA["React SPA\n(src/browser)"]:::frontend
        Modules["Feature Modules\n(src/browser/modules)"]:::frontend
        Arc["Companion UI Library\n(src/neo4j-arc)"]:::frontend
        Shared["Shared State & Services\n(src/shared)"]:::frontend
    end

    %% Backend & Infrastructure
    subgraph "Backend & Infrastructure"
        Auth["Auth Server\n(auth_server)"]:::infrastructure
        Keycloak["Keycloak SSO"]:::infrastructure
        Neo4jDB["Neo4j DB\n(Bolt)"]:::infrastructure
    end

    %% Test Orchestration
    subgraph "Test Orchestration"
        DockerCompose["Docker Compose Env\n(docker/sso-keycloak)"]:::test
        Cypress["Cypress E2E Tests\n(e2e_tests)"]:::test
        Jest["Jest Unit Tests\n(jest.config.js)"]:::test
    end

    %% Documentation & Build
    subgraph "Documentation & Build"
        Docs["Docs (Antora)\n(docs)"]:::infrastructure
        BuildScripts["Webpack & Build Scripts\n(build_scripts)"]:::infrastructure
        ReleaseScripts["Release & Ancillary Scripts\n(scripts)"]:::infrastructure
    end

    %% Data Flows
    BBBrowse -->|"HTTP GET bundle"| SPA
    SPA -->|"imports"| Modules
    SPA -->|"imports"| Arc
    SPA -->|"uses"| Shared
    SPA -->|"Bolt (TCP/WebSocket)"| Neo4jDB
    SPA -->|"HTTPS POST/GET"| Auth
    Auth -->|"OIDC/OAuth2"| Keycloak
    Cypress -->|"drives UI"| BBBrowse
    DockerCompose --> Keycloak
    DockerCompose --> Neo4jDB
    Jest --> SPA

    %% Click Events
    click SPA "https://github.com/neo4j/neo4j-browser/tree/master/src/browser"
    click Modules "https://github.com/neo4j/neo4j-browser/tree/master/src/browser/modules"
    click Arc "https://github.com/neo4j/neo4j-browser/tree/master/src/neo4j-arc"
    click Shared "https://github.com/neo4j/neo4j-browser/tree/master/src/shared"
    click Auth "https://github.com/neo4j/neo4j-browser/tree/master/auth_server"
    click DockerCompose "https://github.com/neo4j/neo4j-browser/tree/master/docker/sso-keycloak"
    click Docs "https://github.com/neo4j/neo4j-browser/tree/master/docs"
    click Cypress "https://github.com/neo4j/neo4j-browser/tree/master/e2e_tests"
    click Jest "https://github.com/neo4j/neo4j-browser/blob/master/jest.config.js"
    click BuildScripts "https://github.com/neo4j/neo4j-browser/tree/master/build_scripts"
    click ReleaseScripts "https://github.com/neo4j/neo4j-browser/tree/master/scripts"

    %% Styles
    classDef frontend fill:#B3D7FF,stroke:#333,stroke-width:1px;
    classDef infrastructure fill:#C3E6CB,stroke:#333,stroke-width:1px;
    classDef test fill:#FFE5B4,stroke:#333,stroke-width:1px;
```
