# albenes/authorship-segovia architecture

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

- Interactive diagram: https://gitdiagram.com/albenes/authorship-segovia
- Repository: https://github.com/albenes/authorship-segovia

## Overview

#### Purpose and entry points
Segovia is a local-first macOS home-agent runtime: CLI, loopback server/cockpit, and optional launchd daemon. It connects to LM Studio on localhost, maintains household data locally, and requires proposals/approval for critical actions. Main composition begins at `src/index.ts`, CLI dispatch at `src/cli.ts`, and server startup at `src/server/index.ts`.

#### Platform and module boundary
The platform defines a pluggable `LifeModule` architecture, central registry, module configuration mapping, enable/disable semantics, and sensitivity classification. Feature modules should expose their module port and be registered centrally rather than coupled directly to interfaces. Core paths: `src/platform/module.ts`, `src/platform/registry.ts`, `src/platform/modules.ts`.

#### Interaction and agent execution
Chat is the primary intent-to-action boundary. It assembles system context, calls configured local models, and invokes a registry of domain tools; tools mediate all operational capabilities instead of allowing arbitrary model execution. Relevant paths: `src/chat.ts`, `src/tools/registry.ts`, `src/tools/run.ts`.

#### Local models and runtime governance
The runtime manages model IDs/configuration, limited resident-model capacity, task budgets, pressure/degraded modes, circuit breaking, recovery, and correlated logging. LM Studio is the material external dependency and is expected on `127.0.0.1`; model identifiers are configuration-controlled. Core paths: `src/runtime/models.ts`, `src/runtime/governor.ts`, `src/provider.ts`.

#### Domain data modules
Modules own their local stores and business rules. Major domains include durable memory with sensitivity-aware retrieval, a double-entry CFO ledger, household/health records, read-only mail, drop-folder inbox processing, and BM25 household knowledge search. Primary paths: `src/memory/module.ts`, `src/life/cfo/ledger.ts`, `src/knowledge/search.ts`. Additional module boundaries are represented by `src/health/module.ts`, `src/household/module.ts`, and `src/mail/module.ts`.

#### Events, proposals, and automation
Sensors/adapters and modules emit events into an event bus. Rules and conditions evaluate them into actions or approval-gated proposals, preserving the product boundary that critical changes are not executed autonomously. Automations and recurring work use this layer rather than direct cross-module mutation. Core paths: `src/events/bus.ts`, `src/events/evaluator.ts`, `src/events/proposals.ts`.

#### External integration and scheduling
macOS adapters provide Calendar, Mail, Reminders, JXA, notifications, and sync-facing interfaces. The rhythm scheduler queues and runs recurring jobs; the daemon wraps this for always-on or login-start operation through launchd. Core paths: `src/adapters/mac/calendar.ts`, `src/rhythm/runner.ts`, `src/daemon/launchd.ts`.

#### Security, persistence, and operations
Sensitive local state is protected through at-rest encryption, macOS Keychain secrets, audit/redaction, execution and workspace guards, quarantine, and integrity checks. SQL.js-backed storage supports local persistence; backup/restore and migrations provide lifecycle continuity. The HTTP server exposes loopback APIs and serves the static cockpit UI. Core paths: `src/security/at-rest.ts`, `src/secrets/keychain.ts`, `src/storage/sqljs-db.ts`; interfaces live in `src/server/http.ts` and `src/cockpit/static/app.js`.

Main entry points: [`src/platform/registry.ts`](https://github.com/albenes/authorship-segovia/blob/main/src/platform/registry.ts) (Central module registry), [`src/events/bus.ts`](https://github.com/albenes/authorship-segovia/blob/main/src/events/bus.ts) (Event bus), [`src/index.ts`](https://github.com/albenes/authorship-segovia/blob/main/src/index.ts) (Runtime composition), [`src/server/index.ts`](https://github.com/albenes/authorship-segovia/blob/main/src/server/index.ts) (Loopback server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Interfaces"]
  node_composition["Runtime composition<br/>bootstrap<br/>[index.ts]"]
  node_cli["CLI dispatch<br/>command interface<br/>[cli.ts]"]
  node_server["Loopback server<br/>HTTP interface<br/>[index.ts]"]
  node_cockpit["Cockpit UI<br/>static UI<br/>[app.js]"]
end

subgraph group_platform["Platform &amp; Agent"]
  node_module_platform["Module platform<br/>LifeModule contract<br/>[module.ts]"]
  node_module_registry["Central module registry<br/>[registry.ts]"]
  node_chat{{"Chat orchestration<br/>agent boundary<br/>[chat.ts]"}}
  node_tool_registry["Domain tool registry<br/>capability boundary<br/>[registry.ts]"]
  node_tool_runner["Tool execution<br/>tool runtime<br/>[run.ts]"]
end

subgraph group_domains["Local Domains"]
  node_memory[("Durable memory<br/>domain module<br/>[module.ts]")]
  node_ledger[("CFO ledger<br/>domain store<br/>[ledger.ts]")]
  node_household_health["Household &amp; health<br/>domain modules<br/>[module.ts]"]
  node_mail["Read-only mail<br/>domain module<br/>[module.ts]"]
  node_knowledge[("Household knowledge<br/>BM25 search<br/>[search.ts]")]
end

subgraph group_automation["Automation"]
  node_event_bus["Event bus<br/>event backbone<br/>[bus.ts]"]
  node_rule_evaluator["Rules evaluator<br/>automation policy<br/>[evaluator.ts]"]
  node_proposals{{"Approval proposals<br/>human approval gate<br/>[proposals.ts]"}}
  node_scheduler["Rhythm scheduler<br/>recurring job runner<br/>[runner.ts]"]
end

subgraph group_operations["Runtime &amp; Operations"]
  node_models_governor["Model governance<br/>runtime governor<br/>[governor.ts]"]
  node_lm_studio(("LM Studio<br/>local model provider<br/>[provider.ts]"))
  node_macos_adapters["macOS adapters<br/>platform integrations<br/>[calendar.ts]"]
  node_launchd_daemon["launchd daemon<br/>always-on host<br/>[launchd.ts]"]
end

subgraph group_security["Security &amp; Data"]
  node_local_storage[("Encrypted local storage<br/>SQL.js persistence<br/>[sqljs-db.ts]")]
end

node_composition -->|"starts"| node_cli
node_composition -->|"starts"| node_server
node_composition -->|"daemon mode"| node_launchd_daemon
node_server -->|"serves"| node_cockpit
node_server -->|"chat API"| node_chat
node_module_platform -->|"defines modules"| node_module_registry
node_module_registry -->|"registers"| node_memory
node_module_registry -->|"registers"| node_ledger
node_module_registry -->|"registers"| node_household_health
node_module_registry -->|"registers"| node_mail
node_chat -->|"model request"| node_models_governor
node_models_governor -->|"governed inference"| node_lm_studio
node_chat -->|"tool calls"| node_tool_registry
node_tool_registry -->|"resolves"| node_tool_runner
node_tool_runner -->|"uses module ports"| node_module_registry
node_memory -->|"retrieval"| node_knowledge
node_module_registry -->|"emits events"| node_event_bus
node_macos_adapters -->|"sensor events"| node_event_bus
node_event_bus -->|"evaluates"| node_rule_evaluator
node_rule_evaluator -->|"critical changes"| node_proposals
node_scheduler -->|"recurring events"| node_event_bus
node_launchd_daemon -->|"runs"| node_scheduler
node_module_registry -->|"persists local state"| node_local_storage
node_proposals -.->|"approved execution"| node_tool_runner

click node_composition "https://github.com/albenes/authorship-segovia/blob/main/src/index.ts"
click node_cli "https://github.com/albenes/authorship-segovia/blob/main/src/cli.ts"
click node_server "https://github.com/albenes/authorship-segovia/blob/main/src/server/index.ts"
click node_cockpit "https://github.com/albenes/authorship-segovia/blob/main/src/cockpit/static/app.js"
click node_module_platform "https://github.com/albenes/authorship-segovia/blob/main/src/platform/module.ts"
click node_module_registry "https://github.com/albenes/authorship-segovia/blob/main/src/platform/registry.ts"
click node_chat "https://github.com/albenes/authorship-segovia/blob/main/src/chat.ts"
click node_tool_registry "https://github.com/albenes/authorship-segovia/blob/main/src/tools/registry.ts"
click node_tool_runner "https://github.com/albenes/authorship-segovia/blob/main/src/tools/run.ts"
click node_memory "https://github.com/albenes/authorship-segovia/blob/main/src/memory/module.ts"
click node_ledger "https://github.com/albenes/authorship-segovia/blob/main/src/life/cfo/ledger.ts"
click node_household_health "https://github.com/albenes/authorship-segovia/blob/main/src/household/module.ts"
click node_mail "https://github.com/albenes/authorship-segovia/blob/main/src/mail/module.ts"
click node_knowledge "https://github.com/albenes/authorship-segovia/blob/main/src/knowledge/search.ts"
click node_event_bus "https://github.com/albenes/authorship-segovia/blob/main/src/events/bus.ts"
click node_rule_evaluator "https://github.com/albenes/authorship-segovia/blob/main/src/events/evaluator.ts"
click node_proposals "https://github.com/albenes/authorship-segovia/blob/main/src/events/proposals.ts"
click node_scheduler "https://github.com/albenes/authorship-segovia/blob/main/src/rhythm/runner.ts"
click node_models_governor "https://github.com/albenes/authorship-segovia/blob/main/src/runtime/governor.ts"
click node_lm_studio "https://github.com/albenes/authorship-segovia/blob/main/src/provider.ts"
click node_macos_adapters "https://github.com/albenes/authorship-segovia/blob/main/src/adapters/mac/calendar.ts"
click node_launchd_daemon "https://github.com/albenes/authorship-segovia/blob/main/src/daemon/launchd.ts"
click node_local_storage "https://github.com/albenes/authorship-segovia/blob/main/src/storage/sqljs-db.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_composition,node_cli,node_server,node_cockpit toneBlue
class node_module_platform,node_module_registry,node_chat,node_tool_registry,node_tool_runner toneAmber
class node_memory,node_ledger,node_household_health,node_mail,node_knowledge toneMint
class node_event_bus,node_rule_evaluator,node_proposals,node_scheduler toneRose
class node_models_governor,node_lm_studio,node_macos_adapters,node_launchd_daemon toneIndigo
class node_local_storage toneTeal
```

## Components

### Entry & Interfaces

- [Runtime composition](https://github.com/albenes/authorship-segovia/blob/main/src/index.ts): bootstrap · Selects CLI, server, and daemon operation. · `src/index.ts`
- [CLI dispatch](https://github.com/albenes/authorship-segovia/blob/main/src/cli.ts): command interface · `src/cli.ts`
- [Loopback server](https://github.com/albenes/authorship-segovia/blob/main/src/server/index.ts): HTTP interface · Serves local APIs and the cockpit. · `src/server/index.ts`
- [Cockpit UI](https://github.com/albenes/authorship-segovia/blob/main/src/cockpit/static/app.js): static UI · `src/cockpit/static/app.js`

### Platform & Agent

- [Module platform](https://github.com/albenes/authorship-segovia/blob/main/src/platform/module.ts): LifeModule contract · Defines registration, configuration, enablement, and sensitivity semantics. · `src/platform/module.ts`
- [Central module registry](https://github.com/albenes/authorship-segovia/blob/main/src/platform/registry.ts): module registry · `src/platform/registry.ts`
- [Chat orchestration](https://github.com/albenes/authorship-segovia/blob/main/src/chat.ts): agent boundary · Builds context, invokes local models, and requests domain tools. · `src/chat.ts`
- [Domain tool registry](https://github.com/albenes/authorship-segovia/blob/main/src/tools/registry.ts): capability boundary · Mediates operational capabilities exposed to models. · `src/tools/registry.ts`
- [Tool execution](https://github.com/albenes/authorship-segovia/blob/main/src/tools/run.ts): tool runtime · `src/tools/run.ts`

### Local Domains

- [Durable memory](https://github.com/albenes/authorship-segovia/blob/main/src/memory/module.ts): domain module · Provides sensitivity-aware local retrieval. · `src/memory/module.ts`
- [CFO ledger](https://github.com/albenes/authorship-segovia/blob/main/src/life/cfo/ledger.ts): domain store · Owns double-entry household financial records. · `src/life/cfo/ledger.ts`
- [Household & health](https://github.com/albenes/authorship-segovia/blob/main/src/household/module.ts): domain modules · `src/household/module.ts`
- [Read-only mail](https://github.com/albenes/authorship-segovia/blob/main/src/mail/module.ts): domain module · `src/mail/module.ts`
- [Household knowledge](https://github.com/albenes/authorship-segovia/blob/main/src/knowledge/search.ts): BM25 search · `src/knowledge/search.ts`

### Automation

- [Event bus](https://github.com/albenes/authorship-segovia/blob/main/src/events/bus.ts): event backbone · Receives events from modules and adapters. · `src/events/bus.ts`
- [Rules evaluator](https://github.com/albenes/authorship-segovia/blob/main/src/events/evaluator.ts): automation policy · Turns events and conditions into actions or proposals. · `src/events/evaluator.ts`
- [Approval proposals](https://github.com/albenes/authorship-segovia/blob/main/src/events/proposals.ts): human approval gate · Critical changes require approval before execution. · `src/events/proposals.ts`
- [Rhythm scheduler](https://github.com/albenes/authorship-segovia/blob/main/src/rhythm/runner.ts): recurring job runner · `src/rhythm/runner.ts`

### Runtime & Operations

- [Model governance](https://github.com/albenes/authorship-segovia/blob/main/src/runtime/governor.ts): runtime governor · Controls resident capacity, budgets, degradation, circuits, and recovery. · `src/runtime/governor.ts`
- [LM Studio](https://github.com/albenes/authorship-segovia/blob/main/src/provider.ts): local model provider · Local dependency on 127.0.0.1. · `src/provider.ts`
- [macOS adapters](https://github.com/albenes/authorship-segovia/blob/main/src/adapters/mac/calendar.ts): platform integrations · Calendar, Mail, Reminders, JXA, notifications, and sync interfaces. · `src/adapters/mac/calendar.ts`
- [launchd daemon](https://github.com/albenes/authorship-segovia/blob/main/src/daemon/launchd.ts): always-on host · `src/daemon/launchd.ts`

### Security & Data

- [Encrypted local storage](https://github.com/albenes/authorship-segovia/blob/main/src/storage/sqljs-db.ts): SQL.js persistence · Local state with encryption, Keychain secrets, audit, and lifecycle continuity. · `src/storage/sqljs-db.ts`

## Connections

- Runtime composition → CLI dispatch: starts
- Runtime composition → Loopback server: starts
- Runtime composition → launchd daemon: daemon mode
- Loopback server → Cockpit UI: serves
- Loopback server → Chat orchestration: chat API
- Module platform → Central module registry: defines modules
- Central module registry → Durable memory: registers
- Central module registry → CFO ledger: registers
- Central module registry → Household & health: registers
- Central module registry → Read-only mail: registers
- Chat orchestration → Model governance: model request
- Model governance → LM Studio: governed inference
- Chat orchestration → Domain tool registry: tool calls
- Domain tool registry → Tool execution: resolves
- Tool execution → Central module registry: uses module ports
- Durable memory → Household knowledge: retrieval
- Central module registry → Event bus: emits events
- macOS adapters → Event bus: sensor events
- Event bus → Rules evaluator: evaluates
- Rules evaluator → Approval proposals: critical changes
- Rhythm scheduler → Event bus: recurring events
- launchd daemon → Rhythm scheduler: runs
- Central module registry → Encrypted local storage: persists local state
- Approval proposals → Tool execution: approved execution