Hero Collab Web2

Multi-service proxy architecture for managing Forgeo (Git) and Espocrm (CRM) via unified OpenRPC interfaces.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                      Browser UI (JavaScript)                     │
│                    http://localhost:8080                        │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│                   hero_collab_ui (Axum Server)                   │
│         Serves HTML/CSS/JS + /rpc proxy endpoint                │
│         Binds to: ~/hero/var/sockets/hero_collab_ui.sock        │
│         (Currently TCP for dev, will migrate to Unix socket)    │
└──────┬────────────────────────────────────────────┬─────────────┘
       │                                            │
       │ /rpc proxy forwards JSON-RPC calls        │ API endpoints
       │                                            │
       ↓                                            ↓
┌──────────────────────────────┐    ┌──────────────────────────────┐
│  hero_collab_client (Lib)     │    │  hero_collab (CLI)          │
│  Unified client for both      │    │  Command-line tool using    │
│  proxy servers via OpenRPC    │    │  the client library         │
└──────┬───────────────┬────────┘    └──────────┬─────────────────┘
       │               │                        │
       ↓               ↓                        │
┌──────────────────┐ ┌──────────────────┐      │
│  Forgeo Proxy    │ │  Espocrm Proxy   │      │
│  OpenRPC Server  │ │  OpenRPC Server  │      │
│  Unix socket     │ │  Unix socket     │      │
└────────┬─────────┘ └─────────┬────────┘      │
         │                      │               │
         ↓                      ↓               │
     ┌────────────────────────────────┐        │
     │  Forgeo Backend (Gitea-like)   │        │
     │  Espocrm Backend (CRM)         │        │
     │  (External HTTP APIs)          │        │
     └────────────────────────────────┘        │
                                               │
      All CLI commands also work via client ───┘

Project Structure

hero_collab_web2/
├── Cargo.toml                              # Workspace root
├── Makefile                                # Build targets
├── buildenv.sh                             # Build environment setup
├── scripts/
│   └── build_lib.sh                        # Unified build script
├── .forgejo/workflows/
│   └── build.yml                           # CI/CD pipeline
├── README.md                               # This file
│
├── crates/
│   ├── hero_collab_forgeo_proxy/           # [SERVER] Forgeo proxy
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   ├── hero_collab_espocrm_proxy/          # [SERVER] Espocrm proxy
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   ├── hero_collab_client/                 # [LIBRARY] Unified client
│   │   ├── Cargo.toml
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── error.rs
│   │   │   ├── forgeo.rs
│   │   │   └── espocrm.rs
│   │
│   ├── hero_collab/                        # [CLI] Command-line tool
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   └── hero_collab_ui/                     # [UI] Admin dashboard
│       ├── Cargo.toml
│       ├── src/
│       │   ├── main.rs
│       │   ├── types.rs
│       │   └── handlers/
│       │       ├── mod.rs
│       │       └── connections.rs
│       └── assets/
│           └── index.html

Crate Responsibilities

Crate	Type	Responsibility
hero_collab_forgeo_proxy	binary	OpenRPC server proxying to Forgeo backend
hero_collab_espocrm_proxy	binary	OpenRPC server proxying to Espocrm backend
hero_collab_client	library	Unified client connecting to both proxies via OpenRPC
hero_collab	binary	CLI tool for scripting and command-line operations
hero_collab_ui	binary	Axum-based admin dashboard + RPC proxy for browser

Dependency Graph (v2 - Generated Client Model)

hero_collab_forgeo_proxy (server)     hero_collab_espocrm_proxy (server)
         ↑                                           ↑
         │                                           │
         └─────────── hero_collab_client ───────────┘
                      (unified client library)
                             ↑         ↑
                    ┌────────┘         └────────┐
                    │                           │
            hero_collab (CLI)            hero_collab_ui (UI)

Getting Started

Prerequisites

• Rust 1.70+
• Cargo
• Connection to Forgeo backend
• Connection to Espocrm backend

Build

make build

Check

make check

Test

make test

Run

make run

This will:

1. Build all crates
2. Start hero_collab_forgeo_proxy on Unix socket
3. Start hero_collab_espocrm_proxy on Unix socket
4. Start hero_collab_ui on TCP (currently http://localhost:8080)

Socket Configuration

All services communicate via Unix sockets in ~/hero/var/sockets/:

hero_collab_forgeo_proxy.sock    → Forgeo proxy OpenRPC server
hero_collab_espocrm_proxy.sock   → Espocrm proxy OpenRPC server
hero_collab_ui.sock              → UI HTTP server (planned)

Configuration

All configuration is via environment variables. No config files needed!

EspoCRM Proxy Configuration

Required:

• ESPOCRM_URL — EspoCRM backend URL
• ESPOCRM_API_KEY — API authentication key

Optional:

• ESPOCRM_TIMEOUT_SECS — Request timeout in seconds (default: 30)
• ESPOCRM_TLS_VERIFY — Verify TLS certificates (default: true)
• LOG_LEVEL — Log level: debug, info, warning, none (default: warning)

Example:

export ESPOCRM_URL="https://crm.example.com"
export ESPOCRM_API_KEY="your-api-key"
export ESPOCRM_TIMEOUT_SECS="30"
export ESPOCRM_TLS_VERIFY="true"
export LOG_LEVEL="info"

make run

Forgeo Proxy Configuration (To be implemented)

export FORGEO_URL="https://forgeo.example.com"
export FORGEO_API_TOKEN="your-token"
export FORGEO_TIMEOUT_SECS="30"
export FORGEO_TLS_VERIFY="true"

API Endpoints

UI Server

• GET / → Admin dashboard HTML
• GET /api/connections → List configured connections
• POST /api/connections → Create new connection
• POST /rpc → JSON-RPC proxy (browser → backends)

CLI Commands

# Forgeo commands
hero_collab forgeo list              # List repositories
hero_collab forgeo create <name>     # Create repository
hero_collab forgeo delete <name>     # Delete repository

# Espocrm commands
hero_collab espocrm list             # List contacts
hero_collab espocrm create <name>    # Create contact
hero_collab espocrm delete <name>    # Delete contact

# Health check
hero_collab health                   # Verify services running

Development

Add a new OpenRPC method

1. Implement in the appropriate proxy server (hero_collab_forgeo_proxy or hero_collab_espocrm_proxy)
2. Add OpenRPC spec to the server's schema
3. Regenerate client via /hero_lib_client skill (when client generation is implemented)
4. Add CLI handler in hero_collab/src/main.rs
5. Add UI handler in hero_collab_ui/src/handlers/

Running tests

make test

Next Steps

1. Implement OpenRPC servers - Add business logic to proxy servers
2. Generate client - Use /hero_lib_client skill to generate hero_collab_client
3. Implement Rhai bindings - Enable scripting via Rhai
4. Migrate to Unix sockets - UI should bind to Unix socket, not TCP
5. Add configuration loading - Load connections from toml files
6. Implement connection tests - Verify connectivity to backends

Troubleshooting

Services fail to start

# Check socket directory exists
mkdir -p ~/hero/var/sockets

# Check for port conflicts
lsof -i :8080

Client connection errors

# Verify proxy servers are running
ls ~/hero/var/sockets/

# Check server logs
RUST_LOG=debug hero_collab_ui

License

Apache-2.0