# josh-project/josh architecture

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

- Interactive diagram: https://gitdiagram.com/josh-project/josh
- Repository: https://github.com/josh-project/josh

## Overview

##### Project type and purpose
- This is a polyglot monorepo for a full-stack “Git history filtering proxy” system (“josh-project”).
It comprises:
- A Rust-based proxy service (`josh-proxy`) exposing HTTP, SSH and GraphQL endpoints.
- A React front-end (`josh-ui`) for browsing/filtering repo contents.
- Core filtering and history-manipulation libraries in Rust (`josh-core`, `josh-filter`, `josh-rpc`, `josh-graphql`).
- Auxiliary components (CGI, reverse-proxy, SSH shell, LFS test server).
- Docker/S6 init scripts to package the service.

##### File structure
- Top level:
- Docker configuration (`Dockerfile`, `docker/`, S6 scripts).
- Cargo workspace crates:
– hyper-reverse-proxy, hyper_cgi (HTTP/CGI plumbing)
– josh-core (filter engine, history, workspace logic)
– josh-filter (CLI shim)
– josh-rpc (async IO, RPC helpers)
– josh-graphql (GraphQL schema and resolvers)
– josh-proxy (main HTTP/SSH/GraphQL server)
– josh-ssh-shell & josh-ssh-dev-server (SSH integration)
– josh-ui (React SPA)
- Go-based LFS test server.
- Extensive integration tests under `tests/`.

##### README for additional insights
- Core use cases: partial cloning, workspace composition, CI/CD sandboxing, GraphQL API, caching proxy.
- The proxy sits in front of any Git host, mounts a local volume for cached repos, and exposes:
- HTTP Git transport
- SSH Git transport
- GraphQL API
- Static UI assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        GitHTTP["Git Client (HTTP)"]:::client
        GitSSH["Git Client (SSH)"]:::client
        GraphQLClient["GraphQL Client (UI/CI)"]:::client
    end

    %% UI Layer
    subgraph "UI Layer"
        ReactUI["React SPA"]:::frontend
    end

    %% Proxy Service
    subgraph "josh-proxy Service"
        HTTPListener["HTTP Listener\n(Hyper)"]:::service
        SSHListener["SSH Listener\n(sshd + josh-ssh-shell)"]:::service
        CGI["CGI Endpoint\n(hyper_cgi)"]:::service
        ReverseProxy["Reverse-Proxy Module"]:::service
        GraphQLAPI["GraphQL Module"]:::service
        RPCIO["RPC & Async IO\n(josh-rpc)"]:::logic
        FilterCore["Filter/Core Engine"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        Cache["Local Git Repo Cache"]:::data
    end

    %% External Services
    subgraph "External Services"
        UpstreamGit["Upstream Git Host"]:::external
        LFS["LFS Storage"]:::external
    end

    %% Connections
    GitHTTP -->|"HTTP"| HTTPListener
    HTTPListener -->|"Git HTTP"| ReverseProxy
    HTTPListener -->|"GraphQL"| GraphQLAPI
    HTTPListener -->|"Static Assets"| ReactUI
    GitSSH -->|"SSH"| SSHListener
    SSHListener -->|"exec shell"| FilterCore
    CGI -->|"CGI calls"| FilterCore
    ReverseProxy -->|"proxy to core"| FilterCore
    GraphQLClient -->|"GraphQL"| GraphQLAPI
    GraphQLAPI -->|"query/resolver"| FilterCore
    FilterCore -->|"read/write"| Cache
    Cache -->|"data"| FilterCore
    FilterCore -->|"fetch on miss"| UpstreamGit
    FilterCore -->|"LFS requests"| LFS
    ReactUI -->|uses API| GraphQLAPI

    %% Click Events
    click ReactUI "https://github.com/josh-project/josh/tree/master/josh-ui/"
    click HTTPListener "https://github.com/josh-project/josh/blob/master/josh-proxy/src/bin/josh-proxy.rs"
    click SSHListener "https://github.com/josh-project/josh/blob/master/josh-ssh-shell/src/bin/josh-ssh-shell.rs"
    click CGI "https://github.com/josh-project/josh/blob/master/hyper_cgi/src/hyper_cgi.rs"
    click ReverseProxy "https://github.com/josh-project/josh/blob/master/hyper-reverse-proxy/src/lib.rs"
    click GraphQLAPI "https://github.com/josh-project/josh/blob/master/josh-graphql/src/graphql.rs"
    click RPCIO "https://github.com/josh-project/josh/blob/master/josh-rpc/src/calls.rs"
    click FilterCore "https://github.com/josh-project/josh/blob/master/josh-core/src/history.rs"
    click LFS "https://github.com/josh-project/josh/blob/master/lfs-test-server/main.go"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085
    classDef frontend fill:#b8daff,stroke:#004085,color:#373b3e
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef logic fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#ffe5b4,stroke:#cc8400,color:#663C00
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#1b1e21
```
