# tzafon/tzafon-waypoint architecture

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

- Interactive diagram: https://gitdiagram.com/tzafon/tzafon-waypoint
- Repository: https://github.com/tzafon/tzafon-waypoint

## Overview

##### Project Type and Purpose
- This is a distributed, microservice‐based orchestration platform (“Tzafon-WayPoint”) for managing massive fleets of headless Chrome instances with near-zero cold-start latency.
- Core goal: expose a simple Python API (`tzafonwright`) to client applications, hide the complexity of browser lifecycle, scaling, health monitoring, and service discovery.

##### File Structure
- Top‐level folders:
- `.github/` – CI/CD workflows
- `apps/` – All source for Rust services and Python client
- `deployment/` – Kubernetes/Helm/HCL deployment manifests
- Root scripts (`create_release.sh`, `local-build.sh`, `simple_test.py`), and Python project files (`pyproject.toml`)
- Under `apps/`:
- `proto-definition/` – .proto files, TLS certs, build scripts → defines gRPC APIs
- `rust-instance-container/` – Browser Container service (headless Chrome + CDP/Tzafonwright ports)
- `rust-instance-manager/` – Orchestrator (instance registration, discovery, health, metrics)
- `rust-shared/` – Shared Rust crates for metrics, socket gateway, utilities
- `tzafonwright/` – Python client library exposing WebSocket API

##### README for Architectural Insights
- Communication:
- Python client ↔ Proxy (WebSocket on port 1337)
- Proxy ↔ Containers (CDP on 9222)
- All Rust components ↔ Instance Manager (gRPC over TLS)
- Key patterns: service discovery, health checking, TLS‐secured gRPC, dynamic scaling.

a. Main Components
- **Clients / Python Services** (external applications using `tzafonwright`)
- **Ephemeral Browser Proxy** (Rust binary)
- **Instance Manager** (Rust orchestrator)
- **Browser Containers** (Rust “instance-container” services running headless Chrome)
- **Proto‐Definition & TLS Store** (gRPC contracts + certificates)
- **Rust‐Shared Library** (utility crate used by manager & container)
- **Deployment Infrastructure** (Kubernetes, Helm charts, HCL/Terraform files)
b. Relationships & Data Flows
1. **Client → Proxy**
- WebSocket (port 1337) carrying JSON RPC or custom protocol
2. **Proxy ↔ Instance Manager**
- gRPC over TLS for service discovery, health/metrics
3. **Instance Manager ↔ Browser Containers**
- gRPC over TLS for registration, heartbeat, metrics
4. **Proxy → Browser Container**
- CDP proxying (port 9222) and Tzafonwright API forwarding
5. **Containers register** on startup with Instance Manager
c. Architectural Patterns & Principles
- **Microservices**: each component is a standalone binary
- **Service Discovery**: via Instance Manager registry
- **Circuit Breaker / Health Monitoring**: automatic remediation
- **Secure RPC**: all control-plane comms use TLS + mutual auth
- **Shared Libraries**: code reuse via `rust-shared` crate
- **Separation of Concerns**: proxy for client‐facing API, manager for orchestration, containers for actual work
d. Key Technologies
- Rust (tokio, tonic gRPC, Rocket/Tera for status pages)
- Python (asyncio, WebSocket client library)
- gRPC (`.proto` under `proto-definition`)
- TLS mutual‐TLS certificates
- Docker (for images built via `Dockerfile.rust-builder`)
- Kubernetes / Helm / Terraform (in `deployment/`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Client Layer"
        clientApp["Python Client Application"]:::client
        tzafonwrightLib["tzafonwright Library"]:::client
    end

    subgraph "Control Plane"
        proxy["Ephemeral Browser Proxy\n(WebSocket 1337)"]:::control
        manager["Instance Manager\n(gRPC/TLS 50051)"]:::control
    end

    subgraph "Data Plane"
        containers["Browser Containers\n(CDP 9222)"]:::data
    end

    subgraph "Infrastructure & Shared"
        proto["gRPC Proto & TLS Store"]:::aux
        shared["Rust Shared Crate"]:::aux
        deploy["Deployment Infrastructure"]:::aux
    end

    %% Flows
    clientApp -->|"uses"| tzafonwrightLib
    tzafonwrightLib -->|"WebSocket\nport 1337"| proxy
    proxy -->|"gRPC/TLS\nport 50051"| manager
    manager -->|"- - -\nheartbeat\n- - -"| containers
    manager -->|"gRPC/TLS\nregistration/metrics"| containers
    proxy -->|"CDP Proxy\nport 9222"| containers

    %% Protos & Shared usage
    proto --> manager
    proto --> proxy
    proto --> containers
    shared --> manager
    shared --> containers

    %% Deployment
    deploy --> proxy
    deploy --> manager
    deploy --> containers

    %% Click Events
    click tzafonwrightLib "https://github.com/tzafon/tzafon-waypoint/tree/main/apps/tzafonwright"
    click proxy "https://github.com/tzafon/tzafon-waypoint/tree/main/apps/rust-instance-container"
    click containers "https://github.com/tzafon/tzafon-waypoint/blob/main/apps/rust-instance-container/src/browser/chrome.rs"
    click manager "https://github.com/tzafon/tzafon-waypoint/tree/main/apps/rust-instance-manager"
    click proto "https://github.com/tzafon/tzafon-waypoint/tree/main/apps/proto-definition"
    click shared "https://github.com/tzafon/tzafon-waypoint/tree/main/apps/rust-shared"
    click deploy "https://github.com/tzafon/tzafon-waypoint/tree/main/deployment"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef control fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef aux fill:#D3D3D3,stroke:#333,stroke-width:1px
```
