# gnaro-shaft/cenacle architecture

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

- Interactive diagram: https://gitdiagram.com/gnaro-shaft/cenacle
- Repository: https://github.com/gnaro-shaft/cenacle

## Overview

Cénacle is a local-first personal assistant whose Iris agent collects and classifies mail, tracks replies, and prepares drafts; the owner reviews and approves proposals in the web page, and a separate deterministic executor sends only approved replies. The graph also preserves status/Telegram reporting and heartbeat monitoring. Several domain implementations are documented but not excerpted, so those links rely on the README; unsampled details are not inferred.

Main entry points: [`apps/iris/src/main.ts`](https://github.com/gnaro-shaft/cenacle/blob/main/apps/iris/src/main.ts) (Iris scheduler), [`packages/journal/src`](https://github.com/gnaro-shaft/cenacle/tree/main/packages/journal/src) (Journal and mail stores), [`apps/server/src/proposals-service.ts`](https://github.com/gnaro-shaft/cenacle/blob/main/apps/server/src/proposals-service.ts) (Proposal service), [`apps/executor/src/execute.ts`](https://github.com/gnaro-shaft/cenacle/blob/main/apps/executor/src/execute.ts) (Approved-send executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mailwork["Mail workflow"]
  node_iris["Iris scheduler<br/>[main.ts]"]
  node_mailpass["Mail collection and sorting<br/>[pass.ts]"]
  node_brain["Classification and local models"]
  node_followup["Follow-up tracking<br/>[follow-up.ts]"]
  node_drafting["Draft generation<br/>[drafting.ts]"]
  node_maildomain["Mail parsing and safeguards"]
end

subgraph group_approval["Approval and delivery"]
  node_proposals["Proposal service"]
  node_api["Local API<br/>[app.ts]"]
  node_executor["Approved-send executor<br/>[execute.ts]"]
end

subgraph group_state["State and policy"]
  node_journal[("Journal and mail stores")]
  node_policy["Schedule and safety rules"]
  node_status["Agent status projection<br/>[agent-status.ts]"]
end

subgraph group_interfaces["Owner interfaces"]
  node_web["Review page<br/>[Proposals.tsx]"]
  node_telegrambot["Telegram bot<br/>[handler.ts]"]
end

subgraph group_monitoring["Monitoring"]
  node_sentinel["Heartbeat monitor<br/>[watch.ts]"]
  node_sentinelapi["Heartbeat endpoint<br/>[server.ts]"]
end

node_owner(("Owner"))
node_mailbox["Mail server"]
node_telegram["Telegram service"]

node_mailbox -.->|"provides mail"| node_iris
node_iris -->|"runs collection"| node_mailpass
node_mailpass -.->|"classifies remainder"| node_brain
node_mailpass -.->|"parses and checks"| node_maildomain
node_iris -.->|"tracks replies"| node_followup
node_iris -->|"drafts due replies"| node_drafting
node_drafting -->|"uses local models"| node_brain
node_iris -->|"reads and writes"| node_journal
node_iris -.->|"applies schedule"| node_policy
node_drafting -.->|"stores proposals"| node_journal
node_owner -->|"reviews drafts"| node_web
node_web -->|"requests actions"| node_api
node_api -->|"routes proposal actions"| node_proposals
node_proposals -.->|"reads and updates"| node_journal
node_proposals -->|"rechecks reply target"| node_maildomain
node_proposals -.->|"records signed approval"| node_executor
node_executor -->|"claims approved work"| node_journal
node_executor -->|"sends accepted reply"| node_mailbox
node_telegram -->|"delivers updates"| node_telegrambot
node_telegrambot -->|"projects agent status"| node_status
node_telegrambot -->|"reads status and records stop"| node_journal
node_telegrambot -->|"sends replies"| node_telegram
node_iris -.->|"sends heartbeat"| node_sentinelapi
node_executor -.->|"sends heartbeat"| node_sentinelapi
node_sentinelapi -->|"records heartbeat"| node_sentinel
node_sentinel -->|"alerts on silence"| node_telegram

click node_iris "https://github.com/gnaro-shaft/cenacle/blob/main/apps/iris/src/main.ts"
click node_mailpass "https://github.com/gnaro-shaft/cenacle/blob/main/packages/mail/src/pass.ts"
click node_brain "https://github.com/gnaro-shaft/cenacle/tree/main/packages/brain/src"
click node_followup "https://github.com/gnaro-shaft/cenacle/blob/main/packages/core/src/follow-up.ts"
click node_drafting "https://github.com/gnaro-shaft/cenacle/blob/main/apps/iris/src/drafting.ts"
click node_maildomain "https://github.com/gnaro-shaft/cenacle/tree/main/packages/mail/src"
click node_journal "https://github.com/gnaro-shaft/cenacle/tree/main/packages/journal/src"
click node_policy "https://github.com/gnaro-shaft/cenacle/tree/main/packages/core/src"
click node_proposals "https://github.com/gnaro-shaft/cenacle/blob/main/apps/server/src/proposals-service.ts"
click node_api "https://github.com/gnaro-shaft/cenacle/blob/main/apps/server/src/app.ts"
click node_web "https://github.com/gnaro-shaft/cenacle/blob/main/apps/web/src/Proposals.tsx"
click node_executor "https://github.com/gnaro-shaft/cenacle/blob/main/apps/executor/src/execute.ts"
click node_telegrambot "https://github.com/gnaro-shaft/cenacle/blob/main/apps/telegram/src/handler.ts"
click node_status "https://github.com/gnaro-shaft/cenacle/blob/main/packages/core/src/agent-status.ts"
click node_sentinel "https://github.com/gnaro-shaft/cenacle/blob/main/apps/sentinel/src/watch.ts"
click node_sentinelapi "https://github.com/gnaro-shaft/cenacle/blob/main/apps/sentinel/src/server.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_iris,node_mailpass,node_brain,node_followup,node_drafting,node_maildomain toneBlue
class node_proposals,node_api,node_executor toneAmber
class node_journal,node_policy,node_status,node_mailbox toneMint
class node_web,node_telegrambot toneRose
class node_sentinel,node_sentinelapi,node_owner,node_telegram toneIndigo
```

## Components

### Mail workflow

- [Iris scheduler](https://github.com/gnaro-shaft/cenacle/blob/main/apps/iris/src/main.ts): `apps/iris/src/main.ts`
- [Mail collection and sorting](https://github.com/gnaro-shaft/cenacle/blob/main/packages/mail/src/pass.ts): `packages/mail/src/pass.ts`
- [Classification and local models](https://github.com/gnaro-shaft/cenacle/tree/main/packages/brain/src): `packages/brain/src`
- [Follow-up tracking](https://github.com/gnaro-shaft/cenacle/blob/main/packages/core/src/follow-up.ts): `packages/core/src/follow-up.ts`
- [Draft generation](https://github.com/gnaro-shaft/cenacle/blob/main/apps/iris/src/drafting.ts): `apps/iris/src/drafting.ts`
- [Mail parsing and safeguards](https://github.com/gnaro-shaft/cenacle/tree/main/packages/mail/src): `packages/mail/src`

### Approval and delivery

- [Proposal service](https://github.com/gnaro-shaft/cenacle/blob/main/apps/server/src/proposals-service.ts): `apps/server/src/proposals-service.ts`
- [Local API](https://github.com/gnaro-shaft/cenacle/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Approved-send executor](https://github.com/gnaro-shaft/cenacle/blob/main/apps/executor/src/execute.ts): `apps/executor/src/execute.ts`

### State and policy

- [Journal and mail stores](https://github.com/gnaro-shaft/cenacle/tree/main/packages/journal/src): `packages/journal/src`
- [Schedule and safety rules](https://github.com/gnaro-shaft/cenacle/tree/main/packages/core/src): `packages/core/src`
- [Agent status projection](https://github.com/gnaro-shaft/cenacle/blob/main/packages/core/src/agent-status.ts): `packages/core/src/agent-status.ts`

### Owner interfaces

- [Review page](https://github.com/gnaro-shaft/cenacle/blob/main/apps/web/src/Proposals.tsx): `apps/web/src/Proposals.tsx`
- [Telegram bot](https://github.com/gnaro-shaft/cenacle/blob/main/apps/telegram/src/handler.ts): `apps/telegram/src/handler.ts`

### Monitoring

- [Heartbeat monitor](https://github.com/gnaro-shaft/cenacle/blob/main/apps/sentinel/src/watch.ts): `apps/sentinel/src/watch.ts`
- [Heartbeat endpoint](https://github.com/gnaro-shaft/cenacle/blob/main/apps/sentinel/src/server.ts): `apps/sentinel/src/server.ts`

### Other components

- **Owner**
- **Mail server**
- **Telegram service**

## Connections

- Mail server → Iris scheduler: provides mail (evidence: `README.md`)
- Iris scheduler → Mail collection and sorting: runs collection (evidence: `apps/iris/src/main.ts`)
- Mail collection and sorting → Classification and local models: classifies remainder (evidence: `README.md`)
- Mail collection and sorting → Mail parsing and safeguards: parses and checks (evidence: `README.md`)
- Iris scheduler → Follow-up tracking: tracks replies (evidence: `README.md`)
- Iris scheduler → Draft generation: drafts due replies (evidence: `apps/iris/src/main.ts`)
- Draft generation → Classification and local models: uses local models (evidence: `apps/iris/src/drafting.ts`)
- Iris scheduler → Journal and mail stores: reads and writes (evidence: `apps/iris/src/main.ts`)
- Iris scheduler → Schedule and safety rules: applies schedule (evidence: `README.md`)
- Draft generation → Journal and mail stores: stores proposals (evidence: `README.md`)
- Owner → Review page: reviews drafts (evidence: `README.md`)
- Review page → Local API: requests actions (evidence: `apps/web/src/Proposals.tsx`)
- Local API → Proposal service: routes proposal actions (evidence: `apps/server/src/app.ts`)
- Proposal service → Journal and mail stores: reads and updates (evidence: `README.md`)
- Proposal service → Mail parsing and safeguards: rechecks reply target
- Proposal service → Approved-send executor: records signed approval (evidence: `README.md`)
- Approved-send executor → Journal and mail stores: claims approved work
- Approved-send executor → Mail server: sends accepted reply
- Telegram service → Telegram bot: delivers updates
- Telegram bot → Agent status projection: projects agent status (evidence: `apps/telegram/src/handler.ts`)
- Telegram bot → Journal and mail stores: reads status and records stop
- Telegram bot → Telegram service: sends replies
- Iris scheduler → Heartbeat endpoint: sends heartbeat (evidence: `README.md`)
- Approved-send executor → Heartbeat endpoint: sends heartbeat (evidence: `README.md`)
- Heartbeat endpoint → Heartbeat monitor: records heartbeat (evidence: `apps/sentinel/src/server.ts`)
- Heartbeat monitor → Telegram service: alerts on silence
