# bretthoffman/luna_architecture architecture

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

- Interactive diagram: https://gitdiagram.com/bretthoffman/luna_architecture
- Repository: https://github.com/bretthoffman/luna_architecture

## Overview

Luna is a personal-assistant application: messages enter through chat transports, the routing spine interprets requests, and deterministic domain tools perform reads or mutations whose results are shaped for a response. The tree also shows proactive conversation, scheduled work, wearable-data integration, and an operator Control Center. The README documents launching the lightweight chat app; sampled source and the SOURCE INDEX support the core routing/tool relationships. Several domain and integration implementations are not excerpted, so their internal links are omitted rather than inferred.

Main entry points: [`luna_core/tools/runner.py`](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/runner.py) (Tool Runner), [`luna_core/router.py`](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/router.py) (Routing Spine), [`luna_core/tools/calendar/pipeline.py`](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/calendar/pipeline.py) (Calendar), [`luna_core/tools/finance/pipeline.py`](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/finance/pipeline.py) (Finance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Messaging"]
  node_chat["Chat Lite<br/>[chat_lite_app.py]"]
  node_sms["SMS Adapter"]
  node_relay["Message Relay<br/>[route.ts]"]
end

subgraph group_spine["Assistant Runtime"]
  node_router["Routing Spine<br/>[router.py]"]
  node_context["Context Builder<br/>[context_builder.py]"]
  node_executor["Tool Execution<br/>[executors.py]"]
  node_selector["Tool Selector<br/>[model_client.py]"]
  node_runner["Tool Runner<br/>[runner.py]"]
  node_shaping["Result Shaping<br/>[result_shaping.py]"]
end

subgraph group_domains["Domain Tools"]
  node_calendar["Calendar<br/>[pipeline.py]"]
  node_finance["Finance<br/>[pipeline.py]"]
  node_fitness["Fitness<br/>[pipeline.py]"]
  node_household["Household<br/>[pipeline.py]"]
  node_reminders["Reminders<br/>[pipeline.py]"]
end

subgraph group_proactive["Proactive Services"]
  node_proactive["Conversation Starter<br/>[controller.py]"]
  node_signals["Body Signals<br/>[engine.py]"]
  node_scheduled["Scheduled Invocations<br/>[controller.py]"]
  node_oura["Oura OAuth"]
end

subgraph group_ops["Operations"]
  node_config["Operator Config<br/>[operator_config.py]"]
  node_control["Control Center<br/>[app.py]"]
end

node_owner(("Owner"))

node_owner -->|"opens chat"| node_chat
node_owner -.->|"sends message"| node_sms
node_chat -.->|"submits message"| node_router
node_sms -.->|"forwards message"| node_router
node_relay -.->|"relays message"| node_router
node_router -->|"builds context"| node_context
node_router -->|"selects tools"| node_selector
node_router -->|"dispatches"| node_executor
node_executor -.->|"invokes tools"| node_runner
node_runner -.->|"dispatches"| node_calendar
node_runner -.->|"dispatches"| node_finance
node_runner -.->|"dispatches"| node_fitness
node_runner -.->|"dispatches"| node_household
node_runner -.->|"dispatches"| node_reminders
node_calendar -->|"calls runner"| node_runner
node_finance -->|"calls runner"| node_runner
node_fitness -->|"calls runner"| node_runner
node_runner -.->|"shapes response"| node_shaping
node_finance -->|"shapes result"| node_shaping
node_calendar -->|"shapes result"| node_shaping
node_signals -->|"feeds signals"| node_proactive
node_config -->|"sets intensity"| node_proactive
node_control -.->|"configures"| node_config
node_oura -->|"reports connection"| node_owner

click node_chat "https://github.com/bretthoffman/luna_architecture/blob/main/luna_control_center/chat_lite_app.py"
click node_sms "https://github.com/bretthoffman/luna_architecture/blob/main/integrations/twilio_sms_adapter.py"
click node_relay "https://github.com/bretthoffman/luna_architecture/blob/main/relay/app/api/message/route.ts"
click node_router "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/router.py"
click node_context "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/context_builder.py"
click node_executor "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/executors.py"
click node_selector "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tool_selector/model_client.py"
click node_runner "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/runner.py"
click node_shaping "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/result_shaping.py"
click node_calendar "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/calendar/pipeline.py"
click node_finance "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/finance/pipeline.py"
click node_fitness "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/fitness/pipeline.py"
click node_household "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/household/pipeline.py"
click node_reminders "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/reminders/pipeline.py"
click node_proactive "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/conversation_starter/controller.py"
click node_signals "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/body_signals/engine.py"
click node_scheduled "https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/scheduled_invocations/controller.py"
click node_oura "https://github.com/bretthoffman/luna_architecture/blob/main/integrations/oura_oauth_routes.py"
click node_config "https://github.com/bretthoffman/luna_architecture/blob/main/config/operator_config.py"
click node_control "https://github.com/bretthoffman/luna_architecture/blob/main/luna_control_center/app.py"

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_chat,node_sms,node_relay toneBlue
class node_router,node_context,node_executor,node_selector,node_runner,node_shaping toneAmber
class node_calendar,node_finance,node_fitness,node_household,node_reminders toneMint
class node_proactive,node_signals,node_scheduled,node_oura toneRose
class node_config,node_control,node_owner toneIndigo
```

## Components

### Messaging

- [Chat Lite](https://github.com/bretthoffman/luna_architecture/blob/main/luna_control_center/chat_lite_app.py): `luna_control_center/chat_lite_app.py`
- [SMS Adapter](https://github.com/bretthoffman/luna_architecture/blob/main/integrations/twilio_sms_adapter.py): `integrations/twilio_sms_adapter.py`
- [Message Relay](https://github.com/bretthoffman/luna_architecture/blob/main/relay/app/api/message/route.ts): `relay/app/api/message/route.ts`

### Assistant Runtime

- [Routing Spine](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/router.py): `luna_core/router.py`
- [Context Builder](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/context_builder.py): `luna_core/context_builder.py`
- [Tool Execution](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/executors.py): `luna_core/executors.py`
- [Tool Selector](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tool_selector/model_client.py): `luna_core/tool_selector/model_client.py`
- [Tool Runner](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/runner.py): `luna_core/tools/runner.py`
- [Result Shaping](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/result_shaping.py): `luna_core/tools/result_shaping.py`

### Domain Tools

- [Calendar](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/calendar/pipeline.py): `luna_core/tools/calendar/pipeline.py`
- [Finance](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/finance/pipeline.py): `luna_core/tools/finance/pipeline.py`
- [Fitness](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/fitness/pipeline.py): `luna_core/tools/fitness/pipeline.py`
- [Household](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/household/pipeline.py): `luna_core/tools/household/pipeline.py`
- [Reminders](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/reminders/pipeline.py): `luna_core/tools/reminders/pipeline.py`

### Proactive Services

- [Conversation Starter](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/conversation_starter/controller.py): `luna_core/conversation_starter/controller.py`
- [Body Signals](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/body_signals/engine.py): `luna_core/body_signals/engine.py`
- [Scheduled Invocations](https://github.com/bretthoffman/luna_architecture/blob/main/luna_core/tools/scheduled_invocations/controller.py): `luna_core/tools/scheduled_invocations/controller.py`
- [Oura OAuth](https://github.com/bretthoffman/luna_architecture/blob/main/integrations/oura_oauth_routes.py): `integrations/oura_oauth_routes.py`

### Operations

- [Operator Config](https://github.com/bretthoffman/luna_architecture/blob/main/config/operator_config.py): `config/operator_config.py`
- [Control Center](https://github.com/bretthoffman/luna_architecture/blob/main/luna_control_center/app.py): `luna_control_center/app.py`

### Other components

- **Owner**

## Connections

- Owner → Chat Lite: opens chat
- Owner → SMS Adapter: sends message
- Chat Lite → Routing Spine: submits message
- SMS Adapter → Routing Spine: forwards message
- Message Relay → Routing Spine: relays message
- Routing Spine → Context Builder: builds context (evidence: `luna_core/router.py`)
- Routing Spine → Tool Selector: selects tools (evidence: `luna_core/router.py`)
- Routing Spine → Tool Execution: dispatches (evidence: `luna_core/router.py`)
- Tool Execution → Tool Runner: invokes tools
- Tool Runner → Calendar: dispatches (evidence: `luna_core/tools/calendar/pipeline.py`)
- Tool Runner → Finance: dispatches (evidence: `luna_core/tools/finance/pipeline.py`)
- Tool Runner → Fitness: dispatches (evidence: `luna_core/tools/fitness/pipeline.py`)
- Tool Runner → Household: dispatches (evidence: `luna_core/tools/household/pipeline.py`)
- Tool Runner → Reminders: dispatches (evidence: `luna_core/tools/reminders/pipeline.py`)
- Calendar → Tool Runner: calls runner (evidence: `luna_core/tools/calendar/pipeline.py`)
- Finance → Tool Runner: calls runner (evidence: `luna_core/tools/finance/pipeline.py`)
- Fitness → Tool Runner: calls runner (evidence: `luna_core/tools/fitness/pipeline.py`)
- Tool Runner → Result Shaping: shapes response
- Finance → Result Shaping: shapes result (evidence: `luna_core/tools/finance/pipeline.py`)
- Calendar → Result Shaping: shapes result (evidence: `luna_core/tools/calendar/pipeline.py`)
- Body Signals → Conversation Starter: feeds signals (evidence: `luna_core/conversation_starter/controller.py`)
- Operator Config → Conversation Starter: sets intensity (evidence: `config/operator_config.py`)
- Control Center → Operator Config: configures
- Oura OAuth → Owner: reports connection (evidence: `integrations/oura_oauth_routes.py`)