# rjbrown57/cartographer architecture

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

- Interactive diagram: https://gitdiagram.com/rjbrown57/cartographer
- Repository: https://github.com/rjbrown57/cartographer

## Overview

##### Main Components

a. Frontend Layer:
- Web UI (HTML/JS) located in /web directory
- Static assets and templates
- Client-side JavaScript interactions

b. Backend Layer:
- GRPC Server (main application server)
- In-memory Backend Storage
- Configuration Management
- API Endpoints

c. Client Components:
- CLI Client
- GRPC Client implementations

##### Service Architecture
**[Web UI] <-> [GRPC Server] <-> [In-memory Backend]**
- ^

**[CLI Client]**

##### Data Flow Components
- Configuration Management (/pkg/types/config)
- Data Models (Groups, Tags, Links)
- Backend Storage System
- Template Engine

##### Specific Implementation Details

- HTTP/Web Server (Gin Framework)
- GRPC Server
- In-memory Backend
- Configuration Manager

b. API Layer (show as interfaces):
- GRPC Protocol Definitions (/proto)
- REST Endpoints
- Backend Interface

c. Data Models (show as entities):
- Groups
- Tags
- Links

##### Integration Points

Clear integration points for:
- Kubernetes deployment (via Helm)
- Configuration loading
- Client interactions (CLI and Web)

**┌─────────────────────────────────────────────┐**
- Client Layer               │
- (Web UI / CLI Client / GRPC Client)     │
- ┤
- Service Layer                 │
- (GRPC Server / HTTP Server / Config)    │
- ┤
- Storage Layer                 │
- (In-memory Backend)             │
- ┘

##### Important Details to Capture

- GRPC service definitions
- Configuration flow
- Authentication points (TODO item)
- Data model relationships
- API versioning (v1 noted in structure)

##### Deployment Context

A separate section showing:
- Kubernetes deployment topology
- Helm chart structure
- Configuration mounting

- Line styles
- Version information
- Configuration sources

This will provide a comprehensive view of Cartographer's architecture while maintaining clarity about its core purpose of managing and sharing URLs and environment information.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef storage fill:#f1c40f,stroke:#f39c12,color:black
    classDef config fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef api fill:#e74c3c,stroke:#c0392b,color:white

    %% Client Layer
    subgraph ClientLayer["Client Layer"]
        WebUI["Web UI"]
        CLIClient["CLI Client"]
        GRPCClient["GRPC Client"]
        Templates["HTML Templates"]
        ClientJS["Client JavaScript"]
    end

    %% Service Layer
    subgraph ServiceLayer["Service Layer"]
        GRPCServer["GRPC Server"]
        HTTPServer["HTTP Server (Gin)"]
        ConfigMgr["Configuration Manager"]
        APIEndpoints["API Endpoints"]
    end

    %% Storage Layer
    subgraph StorageLayer["Storage Layer"]
        InMemoryBackend["In-memory Backend"]
        DataModels["Data Models"]
    end

    %% Data Models Detail
    subgraph DataModelDetails["Data Models"]
        Groups["Groups"]
        Tags["Tags"]
        Links["Links"]
    end

    %% Relationships
    WebUI --> HTTPServer
    CLIClient --> GRPCClient
    GRPCClient --> GRPCServer
    HTTPServer --> GRPCServer
    GRPCServer --> InMemoryBackend
    ConfigMgr --> GRPCServer
    ConfigMgr --> HTTPServer
    APIEndpoints --> HTTPServer
    InMemoryBackend --> DataModels
    DataModels --> Groups
    DataModels --> Tags
    DataModels --> Links

    %% Click Events
    click WebUI "https://github.com/rjbrown57/cartographer/tree/main/web"
    click Templates "https://github.com/rjbrown57/cartographer/tree/main/web/html"
    click ClientJS "https://github.com/rjbrown57/cartographer/blob/main/web/js/cartographer.js"
    click GRPCServer "https://github.com/rjbrown57/cartographer/blob/main/pkg/types/server/server.go"
    click InMemoryBackend "https://github.com/rjbrown57/cartographer/tree/main/pkg/backends/inmemory"
    click ConfigMgr "https://github.com/rjbrown57/cartographer/tree/main/pkg/types/config"
    click APIEndpoints "https://github.com/rjbrown57/cartographer/blob/main/proto/cartographer/v1/cartographer.proto"
    click CLIClient "https://github.com/rjbrown57/cartographer/tree/main/cmd/client"
    click GRPCClient "https://github.com/rjbrown57/cartographer/blob/main/pkg/proto/cartographer/v1/cartographer_grpc.pb.go"
    click Groups "https://github.com/rjbrown57/cartographer/blob/main/pkg/types/data/group.go"
    click Tags "https://github.com/rjbrown57/cartographer/blob/main/pkg/types/data/tag.go"
    click Links "https://github.com/rjbrown57/cartographer/blob/main/pkg/types/data/link.go"
    click HTTPServer "https://github.com/rjbrown57/cartographer/blob/main/pkg/types/ui/gin.go"

    %% Style Applications
    class WebUI,Templates,ClientJS frontend
    class GRPCServer,HTTPServer,APIEndpoints backend
    class InMemoryBackend,DataModels storage
    class ConfigMgr config
    class GRPCClient,CLIClient api

    %% Legend
    subgraph Legend["Legend"]
        Frontend["Frontend Components"]:::frontend
        Backend["Backend Services"]:::backend
        Storage["Storage Components"]:::storage
        Config["Configuration"]:::config
        API["API/Clients"]:::api
    end
```
