# satunix/luna architecture

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

- Interactive diagram: https://gitdiagram.com/satunix/luna
- Repository: https://github.com/satunix/luna

## Overview

Luna packages safety and governed workflows around the pi coding agent: profiles select capabilities, tool calls are gated, delegated work is bounded, and completion is verified. The repository also includes memory and recovery extensions, a local web console, Android remote control, and an optional autonomous runner. Edges are limited to README-described behavior and relationships visible in the supplied excerpts or source index; unsampled internals are represented without inferred call chains.

Main entry points: [`apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt`](https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt) (Android bridge), [`packages/extensions/src/tool-firewall/index.ts`](https://github.com/satunix/luna/blob/main/packages/extensions/src/tool-firewall/index.ts) (Tool firewall), [`packages/core/lib/profiles.ts`](https://github.com/satunix/luna/blob/main/packages/core/lib/profiles.ts) (Profiles), [`packages/extensions/src/delegation-guard/index.ts`](https://github.com/satunix/luna/blob/main/packages/extensions/src/delegation-guard/index.ts) (Delegation guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Safety and governance"]
  node_profiles["Profiles<br/>[profiles.ts]"]
  node_tool_firewall["Tool firewall<br/>[index.ts]"]
  node_audit[("Firewall audit<br/>[trajectory.ts]")]
  node_delegation["Delegation guard<br/>[index.ts]"]
  node_verify["Verification gate<br/>[index.ts]"]
end

subgraph group_agent_work["Agent workflows"]
  node_memory["Durable memory<br/>[index.ts]"]
  node_recovery["Recovery orchestration<br/>[index.ts]"]
  node_effort["Effort controls<br/>[index.ts]"]
end

subgraph group_experience["User interfaces"]
  node_control_center["Control centre<br/>[index.ts]"]
  node_web_server["Console server<br/>[server.ts]"]
  node_web_routes["Console API<br/>[routes.ts]"]
  node_web_client["Web console client<br/>[app.ts]"]
  node_web_render["Console rendering<br/>[render.ts]"]
end

subgraph group_autonomy["Autonomous runs"]
  node_autonomy_runner["Autonomous runner<br/>[engine.ts]"]
  node_container_boundary["Container boundary<br/>[boundary.ts]"]
end

subgraph group_remote["Remote control"]
  node_android_app["Android remote app<br/>[MainActivity.kt]"]
  node_android_bridge["Android bridge<br/>[Bridge.kt]"]
  node_android_remote["Remote client<br/>[Remote.kt]"]
  node_host_store[("Host store<br/>[HostStore.kt]")]
end

node_pi_user(("Pi user"))

node_pi_user -->|"selects profile"| node_profiles
node_profiles -->|"selects firewall mode"| node_tool_firewall
node_pi_user -->|"approves risky calls"| node_tool_firewall
node_tool_firewall -->|"records decisions"| node_audit
node_pi_user -->|"delegates work"| node_delegation
node_delegation -->|"checks completion"| node_verify
node_pi_user -->|"requests verification"| node_verify
node_pi_user -->|"uses remembered context"| node_memory
node_pi_user -->|"continues bounded work"| node_recovery
node_pi_user -->|"sets effort"| node_effort
node_pi_user -->|"opens controls"| node_control_center
node_pi_user -->|"opens console"| node_web_server
node_web_server -->|"routes API requests"| node_web_routes
node_web_client -->|"renders views"| node_web_render
node_android_app -->|"creates bridge"| node_android_bridge
node_android_bridge -->|"uses remote client"| node_android_remote
node_android_bridge -->|"uses host store"| node_host_store
node_pi_user -->|"starts optional run"| node_autonomy_runner
node_autonomy_runner -->|"runs inside boundary"| node_container_boundary

click node_profiles "https://github.com/satunix/luna/blob/main/packages/core/lib/profiles.ts"
click node_tool_firewall "https://github.com/satunix/luna/blob/main/packages/extensions/src/tool-firewall/index.ts"
click node_audit "https://github.com/satunix/luna/blob/main/packages/extensions/src/tool-firewall/trajectory.ts"
click node_delegation "https://github.com/satunix/luna/blob/main/packages/extensions/src/delegation-guard/index.ts"
click node_verify "https://github.com/satunix/luna/blob/main/packages/extensions/src/verify-gate/index.ts"
click node_memory "https://github.com/satunix/luna/blob/main/packages/extensions/src/memory-vault/index.ts"
click node_recovery "https://github.com/satunix/luna/blob/main/packages/extensions/src/recovery-orchestrator/index.ts"
click node_effort "https://github.com/satunix/luna/blob/main/packages/extensions/src/effort/index.ts"
click node_control_center "https://github.com/satunix/luna/blob/main/packages/extensions/src/control-center/index.ts"
click node_web_server "https://github.com/satunix/luna/blob/main/packages/web-ui/server/server.ts"
click node_web_routes "https://github.com/satunix/luna/blob/main/packages/web-ui/server/routes.ts"
click node_web_client "https://github.com/satunix/luna/blob/main/packages/web-ui/src/public/js/app.ts"
click node_web_render "https://github.com/satunix/luna/blob/main/packages/web-ui/src/public/js/render.ts"
click node_android_app "https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/MainActivity.kt"
click node_android_bridge "https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt"
click node_android_remote "https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/Remote.kt"
click node_host_store "https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/HostStore.kt"
click node_autonomy_runner "https://github.com/satunix/luna/blob/main/packages/autonomy/lib/engine.ts"
click node_container_boundary "https://github.com/satunix/luna/blob/main/packages/autonomy/lib/boundary.ts"

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_profiles,node_tool_firewall,node_audit,node_delegation,node_verify,node_pi_user toneBlue
class node_memory,node_recovery,node_effort toneAmber
class node_control_center,node_web_server,node_web_routes,node_web_client,node_web_render toneMint
class node_autonomy_runner,node_container_boundary toneRose
class node_android_app,node_android_bridge,node_android_remote,node_host_store toneIndigo
```

## Components

### Safety and governance

- [Profiles](https://github.com/satunix/luna/blob/main/packages/core/lib/profiles.ts): `packages/core/lib/profiles.ts`
- [Tool firewall](https://github.com/satunix/luna/blob/main/packages/extensions/src/tool-firewall/index.ts): `packages/extensions/src/tool-firewall/index.ts`
- [Firewall audit](https://github.com/satunix/luna/blob/main/packages/extensions/src/tool-firewall/trajectory.ts): `packages/extensions/src/tool-firewall/trajectory.ts`
- [Delegation guard](https://github.com/satunix/luna/blob/main/packages/extensions/src/delegation-guard/index.ts): `packages/extensions/src/delegation-guard/index.ts`
- [Verification gate](https://github.com/satunix/luna/blob/main/packages/extensions/src/verify-gate/index.ts): `packages/extensions/src/verify-gate/index.ts`

### Agent workflows

- [Durable memory](https://github.com/satunix/luna/blob/main/packages/extensions/src/memory-vault/index.ts): `packages/extensions/src/memory-vault/index.ts`
- [Recovery orchestration](https://github.com/satunix/luna/blob/main/packages/extensions/src/recovery-orchestrator/index.ts): `packages/extensions/src/recovery-orchestrator/index.ts`
- [Effort controls](https://github.com/satunix/luna/blob/main/packages/extensions/src/effort/index.ts): `packages/extensions/src/effort/index.ts`

### User interfaces

- [Control centre](https://github.com/satunix/luna/blob/main/packages/extensions/src/control-center/index.ts): `packages/extensions/src/control-center/index.ts`
- [Console server](https://github.com/satunix/luna/blob/main/packages/web-ui/server/server.ts): `packages/web-ui/server/server.ts`
- [Console API](https://github.com/satunix/luna/blob/main/packages/web-ui/server/routes.ts): `packages/web-ui/server/routes.ts`
- [Web console client](https://github.com/satunix/luna/blob/main/packages/web-ui/src/public/js/app.ts): `packages/web-ui/src/public/js/app.ts`
- [Console rendering](https://github.com/satunix/luna/blob/main/packages/web-ui/src/public/js/render.ts): `packages/web-ui/src/public/js/render.ts`

### Autonomous runs

- [Autonomous runner](https://github.com/satunix/luna/blob/main/packages/autonomy/lib/engine.ts): `packages/autonomy/lib/engine.ts`
- [Container boundary](https://github.com/satunix/luna/blob/main/packages/autonomy/lib/boundary.ts): `packages/autonomy/lib/boundary.ts`

### Remote control

- [Android remote app](https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/MainActivity.kt): `apps/android/app/src/main/java/io/github/satunix/piremote/MainActivity.kt`
- [Android bridge](https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt): `apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt`
- [Remote client](https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/Remote.kt): `apps/android/app/src/main/java/io/github/satunix/piremote/Remote.kt`
- [Host store](https://github.com/satunix/luna/blob/main/apps/android/app/src/main/java/io/github/satunix/piremote/HostStore.kt): `apps/android/app/src/main/java/io/github/satunix/piremote/HostStore.kt`

### Other components

- **Pi user**

## Connections

- Pi user → Profiles: selects profile (evidence: `README.md`)
- Profiles → Tool firewall: selects firewall mode (evidence: `README.md`)
- Pi user → Tool firewall: approves risky calls (evidence: `README.md`)
- Tool firewall → Firewall audit: records decisions (evidence: `README.md`)
- Pi user → Delegation guard: delegates work (evidence: `README.md`)
- Delegation guard → Verification gate: checks completion (evidence: `README.md`)
- Pi user → Verification gate: requests verification (evidence: `README.md`)
- Pi user → Durable memory: uses remembered context (evidence: `README.md`)
- Pi user → Recovery orchestration: continues bounded work (evidence: `README.md`)
- Pi user → Effort controls: sets effort (evidence: `README.md`)
- Pi user → Control centre: opens controls (evidence: `README.md`)
- Pi user → Console server: opens console (evidence: `README.md`)
- Console server → Console API: routes API requests (evidence: `packages/web-ui/server/server.ts`)
- Web console client → Console rendering: renders views (evidence: `packages/web-ui/src/public/js/app.ts`)
- Android remote app → Android bridge: creates bridge (evidence: `apps/android/app/src/main/java/io/github/satunix/piremote/MainActivity.kt`)
- Android bridge → Remote client: uses remote client (evidence: `apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt`)
- Android bridge → Host store: uses host store (evidence: `apps/android/app/src/main/java/io/github/satunix/piremote/Bridge.kt`)
- Pi user → Autonomous runner: starts optional run (evidence: `README.md`)
- Autonomous runner → Container boundary: runs inside boundary (evidence: `README.md`)