# xjoc/marsa architecture

> Architecture diagram of the GitHub repository xjoc/marsa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xjoc/marsa
- Repository: https://github.com/xjoc/marsa

## Overview

Marsa is a local PHP/Node development environment operated through a CLI or desktop window. The principal workflow is to install runtimes, register project folders as sites, select versions, and have the background daemon serve those sites over trusted HTTPS with `.test` names. The graph also preserves the documented GUI, tray, shim, diagnostics, service control, setup, and privileged-helper capabilities. Some subsystem internals are unsampled, so their relationships are shown only where the README or excerpts support them.

Main entry points: [`crates/app/src/cli/strings.rs`](https://github.com/xjoc/marsa/blob/main/crates/app/src/cli/strings.rs) (Marsa CLI), [`crates/gui/src/app.rs`](https://github.com/xjoc/marsa/blob/main/crates/gui/src/app.rs) (Marsa window), [`crates/app/src/daemon/server.rs`](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/server.rs) (Daemon server), [`crates/app/src/daemon/sites_sync.rs`](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/sites_sync.rs) (Site synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["Marsa CLI<br/>[strings.rs]"]
  node_shim["Runtime shims<br/>[main.rs]"]
  node_daemon_client["Daemon client<br/>[client.rs]"]
end

subgraph group_runtime["Daemon runtime"]
  node_daemon_server["Daemon server<br/>[server.rs]"]
  node_daemon_state["Daemon state<br/>[state.rs]"]
  node_caddy["Caddy service<br/>[caddy.rs]"]
  node_services["Service control<br/>[services_api.rs]"]
  node_logs["Service logs<br/>[logs.rs]"]
end

subgraph group_domain["Project management"]
  node_site_management["Site management<br/>[sites_api.rs]"]
  node_site_sync["Site synchronization<br/>[sites_sync.rs]"]
  node_version_selection["Version selection<br/>[resolver.rs]"]
  node_runtime_install["Runtime installation<br/>[installer.rs]"]
  node_runtime_management["Runtime management<br/>[runtimes.rs]"]
  node_doctor["Diagnostics<br/>[doctor.rs]"]
  node_site_store["Site configuration<br/>[sites.rs]"]
end

subgraph group_system["System integration"]
  node_dns["&#96;.test&#96; DNS<br/>[dns.rs]"]
  node_setup["System setup<br/>[setup_api.rs]"]
  node_privileged_helper["Privileged helper<br/>[main.rs]"]
end

subgraph group_gui["Desktop experience"]
  node_guiapp["Marsa window<br/>[app.rs]"]
  node_tray["Menu bar tray<br/>[worker.rs]"]
  node_gui_model["UI state model<br/>[model.rs]"]
  node_gui_bridge["UI bridge<br/>[bridge.rs]"]
end

node_developer(("Developer"))
node_browser(("Web browser"))

node_developer -->|"runs commands"| node_cli
node_developer -->|"uses window"| node_guiapp
node_cli -->|"requests operations"| node_daemon_client
node_guiapp -->|"updates state"| node_gui_model
node_guiapp -->|"sends commands"| node_gui_bridge
node_guiapp -.->|"controls daemon"| node_daemon_client
node_tray -.->|"opens panel"| node_guiapp
node_shim -->|"resolves runtime"| node_version_selection
node_version_selection -->|"selects installed version"| node_runtime_management
node_daemon_client -->|"calls HTTP API"| node_daemon_server
node_daemon_server -->|"serves with state"| node_daemon_state
node_daemon_server -->|"starts synchronization"| node_site_sync
node_daemon_server -->|"starts DNS service"| node_dns
node_site_management -.->|"reads site settings"| node_site_store
node_site_sync -.->|"synchronizes site config"| node_caddy
node_site_sync -.->|"refreshes site list"| node_site_management
node_cli -->|"installs runtimes"| node_runtime_install
node_runtime_install -.->|"adds installed versions"| node_runtime_management
node_cli -->|"manages sites"| node_site_management
node_cli -->|"runs setup"| node_setup
node_setup -.->|"requests privileged work"| node_privileged_helper
node_cli -->|"checks environment"| node_doctor
node_cli -->|"controls services"| node_services
node_cli -->|"reads logs"| node_logs
node_caddy -->|"serves HTTPS sites"| node_browser
node_dns -->|"resolves &#96;.test&#96; names"| node_browser

click node_cli "https://github.com/xjoc/marsa/blob/main/crates/app/src/cli/strings.rs"
click node_shim "https://github.com/xjoc/marsa/blob/main/crates/shim/src/main.rs"
click node_guiapp "https://github.com/xjoc/marsa/blob/main/crates/gui/src/app.rs"
click node_tray "https://github.com/xjoc/marsa/blob/main/crates/gui/src/tray/worker.rs"
click node_gui_model "https://github.com/xjoc/marsa/blob/main/crates/gui/src/model.rs"
click node_gui_bridge "https://github.com/xjoc/marsa/blob/main/crates/gui/src/bridge.rs"
click node_daemon_client "https://github.com/xjoc/marsa/blob/main/crates/core/src/client.rs"
click node_daemon_server "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/server.rs"
click node_daemon_state "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/state.rs"
click node_site_management "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/sites_api.rs"
click node_site_sync "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/sites_sync.rs"
click node_version_selection "https://github.com/xjoc/marsa/blob/main/crates/core/src/resolver.rs"
click node_runtime_install "https://github.com/xjoc/marsa/blob/main/crates/core/src/installer.rs"
click node_runtime_management "https://github.com/xjoc/marsa/blob/main/crates/core/src/runtimes.rs"
click node_caddy "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/caddy.rs"
click node_dns "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/dns.rs"
click node_setup "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/setup_api.rs"
click node_privileged_helper "https://github.com/xjoc/marsa/blob/main/crates/helper/src/main.rs"
click node_doctor "https://github.com/xjoc/marsa/blob/main/crates/core/src/doctor.rs"
click node_services "https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/services_api.rs"
click node_logs "https://github.com/xjoc/marsa/blob/main/crates/app/src/cli/logs.rs"
click node_site_store "https://github.com/xjoc/marsa/blob/main/crates/core/src/sites.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shim,node_daemon_client,node_browser toneBlue
class node_daemon_server,node_daemon_state,node_caddy,node_services,node_logs toneAmber
class node_site_management,node_site_sync,node_version_selection,node_runtime_install,node_runtime_management,node_doctor,node_site_store toneMint
class node_dns,node_setup,node_privileged_helper toneRose
class node_guiapp,node_tray,node_gui_model,node_gui_bridge,node_developer toneIndigo
```

## Components

### User interfaces

- [Marsa CLI](https://github.com/xjoc/marsa/blob/main/crates/app/src/cli/strings.rs): `crates/app/src/cli/strings.rs`
- [Runtime shims](https://github.com/xjoc/marsa/blob/main/crates/shim/src/main.rs): `crates/shim/src/main.rs`
- [Daemon client](https://github.com/xjoc/marsa/blob/main/crates/core/src/client.rs): `crates/core/src/client.rs`

### Daemon runtime

- [Daemon server](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/server.rs): `crates/app/src/daemon/server.rs`
- [Daemon state](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/state.rs): `crates/app/src/daemon/state.rs`
- [Caddy service](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/caddy.rs): `crates/app/src/daemon/caddy.rs`
- [Service control](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/services_api.rs): `crates/app/src/daemon/services_api.rs`
- [Service logs](https://github.com/xjoc/marsa/blob/main/crates/app/src/cli/logs.rs): `crates/app/src/cli/logs.rs`

### Project management

- [Site management](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/sites_api.rs): `crates/app/src/daemon/sites_api.rs`
- [Site synchronization](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/sites_sync.rs): `crates/app/src/daemon/sites_sync.rs`
- [Version selection](https://github.com/xjoc/marsa/blob/main/crates/core/src/resolver.rs): `crates/core/src/resolver.rs`
- [Runtime installation](https://github.com/xjoc/marsa/blob/main/crates/core/src/installer.rs): `crates/core/src/installer.rs`
- [Runtime management](https://github.com/xjoc/marsa/blob/main/crates/core/src/runtimes.rs): `crates/core/src/runtimes.rs`
- [Diagnostics](https://github.com/xjoc/marsa/blob/main/crates/core/src/doctor.rs): `crates/core/src/doctor.rs`
- [Site configuration](https://github.com/xjoc/marsa/blob/main/crates/core/src/sites.rs): `crates/core/src/sites.rs`

### System integration

- [`.test` DNS](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/dns.rs): `crates/app/src/daemon/dns.rs`
- [System setup](https://github.com/xjoc/marsa/blob/main/crates/app/src/daemon/setup_api.rs): `crates/app/src/daemon/setup_api.rs`
- [Privileged helper](https://github.com/xjoc/marsa/blob/main/crates/helper/src/main.rs): `crates/helper/src/main.rs`

### Desktop experience

- [Marsa window](https://github.com/xjoc/marsa/blob/main/crates/gui/src/app.rs): `crates/gui/src/app.rs`
- [Menu bar tray](https://github.com/xjoc/marsa/blob/main/crates/gui/src/tray/worker.rs): `crates/gui/src/tray/worker.rs`
- [UI state model](https://github.com/xjoc/marsa/blob/main/crates/gui/src/model.rs): `crates/gui/src/model.rs`
- [UI bridge](https://github.com/xjoc/marsa/blob/main/crates/gui/src/bridge.rs): `crates/gui/src/bridge.rs`

### Other components

- **Developer**
- **Web browser**

## Connections

- Developer → Marsa CLI: runs commands (evidence: `README.md`)
- Developer → Marsa window: uses window (evidence: `README.md`)
- Marsa CLI → Daemon client: requests operations (evidence: `crates/core/src/client.rs`)
- Marsa window → UI state model: updates state (evidence: `crates/gui/src/app.rs`)
- Marsa window → UI bridge: sends commands (evidence: `crates/gui/src/app.rs`)
- Marsa window → Daemon client: controls daemon (evidence: `README.md`)
- Menu bar tray → Marsa window: opens panel (evidence: `README.md`)
- Runtime shims → Version selection: resolves runtime (evidence: `crates/shim/src/main.rs`)
- Version selection → Runtime management: selects installed version (evidence: `README.md`)
- Daemon client → Daemon server: calls HTTP API (evidence: `crates/core/src/client.rs`)
- Daemon server → Daemon state: serves with state (evidence: `crates/app/src/daemon/server.rs`)
- Daemon server → Site synchronization: starts synchronization (evidence: `crates/app/src/daemon/server.rs`)
- Daemon server → `.test` DNS: starts DNS service (evidence: `crates/app/src/daemon/server.rs`)
- Site management → Site configuration: reads site settings
- Site synchronization → Caddy service: synchronizes site config
- Site synchronization → Site management: refreshes site list
- Marsa CLI → Runtime installation: installs runtimes (evidence: `README.md`)
- Runtime installation → Runtime management: adds installed versions
- Marsa CLI → Site management: manages sites (evidence: `README.md`)
- Marsa CLI → System setup: runs setup (evidence: `README.md`)
- System setup → Privileged helper: requests privileged work
- Marsa CLI → Diagnostics: checks environment (evidence: `README.md`)
- Marsa CLI → Service control: controls services (evidence: `README.md`)
- Marsa CLI → Service logs: reads logs (evidence: `README.md`)
- Caddy service → Web browser: serves HTTPS sites (evidence: `README.md`)
- `.test` DNS → Web browser: resolves `.test` names (evidence: `README.md`)
