# etanhey/golems architecture

> Architecture diagram of the GitHub repository etanhey/golems, 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/etanhey/golems
- Repository: https://github.com/etanhey/golems

## Overview

Golems is a personal-use monorepo combining TypeScript domain packages with reusable AI-agent skill workflows. A typical package workflow starts with a CLI, service, or agent-facing request, then uses domain logic and shared integrations to produce a result: coaching briefings, content, email handling, finance reports, or invoice operations. The README documents the package capabilities; sampled source confirms selected call paths in coaching, content, services, and the CLI. The skill library is a separate major product branch. Several package internals are unsampled, so those branches are shown at package level rather than with speculative calls.

Main entry points: [`packages/content/src/http-service.ts`](https://github.com/etanhey/golems/blob/master/packages/content/src/http-service.ts) (Content HTTP API), [`packages/coach/src/schedule-engine.ts`](https://github.com/etanhey/golems/blob/master/packages/coach/src/schedule-engine.ts) (Coaching & Calendar), [`packages/services/src/briefing.ts`](https://github.com/etanhey/golems/blob/master/packages/services/src/briefing.ts) (Briefing Service), [`packages/shared/src/email/db-client.ts`](https://github.com/etanhey/golems/blob/master/packages/shared/src/email/db-client.ts) (Email Golem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry Points"]
  node_cli["Skills CLI<br/>[index.ts]"]
  node_dashboard["Terminal Dashboard<br/>[Dashboard.tsx]"]
  node_services["Scheduled Services<br/>[cloud-worker.ts]"]
end

subgraph group_domains["Domain Packages"]
  node_coach["Coaching &amp; Calendar<br/>[schedule-engine.ts]"]
  node_briefing["Briefing Service<br/>[briefing.ts]"]
  node_email["Email Golem<br/>[db-client.ts]"]
  node_teller["Finance &amp; Subscriptions<br/>[report.ts]"]
  node_invoice["Invoice MCP<br/>[mcp-server.ts]"]
  node_mock_mcp["Mock MCP Server<br/>[mock-mcp-server.ts]"]
  node_claude["Claude Plugin"]
end

subgraph group_shared["Shared Runtime"]
  node_shared_llm["LLM Providers<br/>[cloud-llm.ts]"]
  node_shared_state[("Supabase &amp; State")]
  node_email_router["Email Routing<br/>[router.ts]"]
end

subgraph group_content["Content Production"]
  node_content_http["Content HTTP API<br/>[http-service.ts]"]
  node_content_pipeline["Pipeline Router<br/>[router.ts]"]
  node_content_images["Image Generation<br/>[index.ts]"]
  node_content_video["Video Rendering<br/>[render-service.ts]"]
  node_content_dataviz["Data Visualizations<br/>[renderer.ts]"]
end

subgraph group_skills["Agent Skills"]
  node_skills_library["Skill Workflows"]
  node_research["Research Workflow<br/>[research.py]"]
  node_research_agent["AutoCursor Agent<br/>[autocursor.py]"]
end

node_developer(("Developer / Agent"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"lists / installs"| node_skills_library
node_developer -.->|"views status"| node_dashboard
node_services -->|"loads briefing"| node_briefing
node_briefing -->|"uses coaching"| node_coach
node_briefing -->|"uses finance"| node_teller
node_coach -->|"requests advice"| node_shared_llm
node_coach -->|"reads statuses"| node_shared_state
node_coach -.->|"syncs calendar"| node_email
node_email -->|"routes messages"| node_email_router
node_email -->|"persists data"| node_shared_state
node_teller -.->|"stores reports"| node_shared_state
node_invoice -.->|"serves MCP tools"| node_developer
node_developer -->|"requests content"| node_content_http
node_content_http -->|"executes plans"| node_content_pipeline
node_content_http -->|"generates images"| node_content_images
node_content_http -->|"renders video"| node_content_video
node_content_http -->|"renders charts"| node_content_dataviz
node_research -->|"invokes agent"| node_research_agent
node_developer -->|"loads workflows"| node_skills_library
node_developer -->|"tests skill behavior"| node_mock_mcp
node_developer -->|"uses persona plugin"| node_claude

click node_cli "https://github.com/etanhey/golems/blob/master/packages/golem-skills/src/index.ts"
click node_dashboard "https://github.com/etanhey/golems/blob/master/packages/golems-tui/src/components/Dashboard.tsx"
click node_services "https://github.com/etanhey/golems/blob/master/packages/services/src/cloud-worker.ts"
click node_coach "https://github.com/etanhey/golems/blob/master/packages/coach/src/schedule-engine.ts"
click node_briefing "https://github.com/etanhey/golems/blob/master/packages/services/src/briefing.ts"
click node_email "https://github.com/etanhey/golems/blob/master/packages/shared/src/email/db-client.ts"
click node_teller "https://github.com/etanhey/golems/blob/master/packages/teller/src/report.ts"
click node_invoice "https://github.com/etanhey/golems/blob/master/packages/green-invoice-mcp/src/mcp-server.ts"
click node_shared_llm "https://github.com/etanhey/golems/blob/master/packages/shared/src/lib/cloud-llm.ts"
click node_shared_state "https://github.com/etanhey/golems/blob/master/packages/shared/src/lib/supabase-factory.ts"
click node_email_router "https://github.com/etanhey/golems/blob/master/packages/shared/src/email/router.ts"
click node_content_http "https://github.com/etanhey/golems/blob/master/packages/content/src/http-service.ts"
click node_content_pipeline "https://github.com/etanhey/golems/blob/master/packages/content/src/pipeline/router.ts"
click node_content_images "https://github.com/etanhey/golems/blob/master/packages/content/src/comfyui/index.ts"
click node_content_video "https://github.com/etanhey/golems/blob/master/packages/content/src/render/render-service.ts"
click node_content_dataviz "https://github.com/etanhey/golems/blob/master/packages/content/src/dataviz/renderer.ts"
click node_skills_library "https://github.com/etanhey/golems/tree/master/skills/golem-powers"
click node_research "https://github.com/etanhey/golems/blob/master/skills/golem-powers/cursor-workflows/research/research.py"
click node_research_agent "https://github.com/etanhey/golems/blob/master/skills/golem-powers/cursor-workflows/lib/autocursor.py"
click node_mock_mcp "https://github.com/etanhey/golems/blob/master/packages/mock-mcp/src/mock-mcp-server.ts"
click node_claude "https://github.com/etanhey/golems/tree/master/packages/claude"

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_dashboard,node_services toneBlue
class node_coach,node_briefing,node_email,node_teller,node_invoice,node_mock_mcp,node_claude toneAmber
class node_shared_llm,node_shared_state,node_email_router toneMint
class node_content_http,node_content_pipeline,node_content_images,node_content_video,node_content_dataviz toneRose
class node_skills_library,node_research,node_research_agent,node_developer toneIndigo
```

## Components

### Entry Points

- [Skills CLI](https://github.com/etanhey/golems/blob/master/packages/golem-skills/src/index.ts): `packages/golem-skills/src/index.ts`
- [Terminal Dashboard](https://github.com/etanhey/golems/blob/master/packages/golems-tui/src/components/Dashboard.tsx): `packages/golems-tui/src/components/Dashboard.tsx`
- [Scheduled Services](https://github.com/etanhey/golems/blob/master/packages/services/src/cloud-worker.ts): `packages/services/src/cloud-worker.ts`

### Domain Packages

- [Coaching & Calendar](https://github.com/etanhey/golems/blob/master/packages/coach/src/schedule-engine.ts): `packages/coach/src/schedule-engine.ts`
- [Briefing Service](https://github.com/etanhey/golems/blob/master/packages/services/src/briefing.ts): `packages/services/src/briefing.ts`
- [Email Golem](https://github.com/etanhey/golems/blob/master/packages/shared/src/email/db-client.ts): `packages/shared/src/email/db-client.ts`
- [Finance & Subscriptions](https://github.com/etanhey/golems/blob/master/packages/teller/src/report.ts): `packages/teller/src/report.ts`
- [Invoice MCP](https://github.com/etanhey/golems/blob/master/packages/green-invoice-mcp/src/mcp-server.ts): `packages/green-invoice-mcp/src/mcp-server.ts`
- [Mock MCP Server](https://github.com/etanhey/golems/blob/master/packages/mock-mcp/src/mock-mcp-server.ts): `packages/mock-mcp/src/mock-mcp-server.ts`
- [Claude Plugin](https://github.com/etanhey/golems/tree/master/packages/claude): `packages/claude`

### Shared Runtime

- [LLM Providers](https://github.com/etanhey/golems/blob/master/packages/shared/src/lib/cloud-llm.ts): `packages/shared/src/lib/cloud-llm.ts`
- [Supabase & State](https://github.com/etanhey/golems/blob/master/packages/shared/src/lib/supabase-factory.ts): `packages/shared/src/lib/supabase-factory.ts`
- [Email Routing](https://github.com/etanhey/golems/blob/master/packages/shared/src/email/router.ts): `packages/shared/src/email/router.ts`

### Content Production

- [Content HTTP API](https://github.com/etanhey/golems/blob/master/packages/content/src/http-service.ts): `packages/content/src/http-service.ts`
- [Pipeline Router](https://github.com/etanhey/golems/blob/master/packages/content/src/pipeline/router.ts): `packages/content/src/pipeline/router.ts`
- [Image Generation](https://github.com/etanhey/golems/blob/master/packages/content/src/comfyui/index.ts): `packages/content/src/comfyui/index.ts`
- [Video Rendering](https://github.com/etanhey/golems/blob/master/packages/content/src/render/render-service.ts): `packages/content/src/render/render-service.ts`
- [Data Visualizations](https://github.com/etanhey/golems/blob/master/packages/content/src/dataviz/renderer.ts): `packages/content/src/dataviz/renderer.ts`

### Agent Skills

- [Skill Workflows](https://github.com/etanhey/golems/tree/master/skills/golem-powers): `skills/golem-powers`
- [Research Workflow](https://github.com/etanhey/golems/blob/master/skills/golem-powers/cursor-workflows/research/research.py): `skills/golem-powers/cursor-workflows/research/research.py`
- [AutoCursor Agent](https://github.com/etanhey/golems/blob/master/skills/golem-powers/cursor-workflows/lib/autocursor.py): `skills/golem-powers/cursor-workflows/lib/autocursor.py`

### Other components

- **Developer / Agent**

## Connections

- Developer / Agent → Skills CLI: runs commands
- Skills CLI → Skill Workflows: lists / installs
- Developer / Agent → Terminal Dashboard: views status
- Scheduled Services → Briefing Service: loads briefing (evidence: `packages/services/src/cloud-worker.ts`)
- Briefing Service → Coaching & Calendar: uses coaching (evidence: `packages/services/src/briefing.ts`)
- Briefing Service → Finance & Subscriptions: uses finance (evidence: `packages/services/src/briefing.ts`)
- Coaching & Calendar → LLM Providers: requests advice
- Coaching & Calendar → Supabase & State: reads statuses
- Coaching & Calendar → Email Golem: syncs calendar
- Email Golem → Email Routing: routes messages (evidence: `packages/shared/src/email/db-client.ts`)
- Email Golem → Supabase & State: persists data (evidence: `packages/shared/src/email/db-client.ts`)
- Finance & Subscriptions → Supabase & State: stores reports
- Invoice MCP → Developer / Agent: serves MCP tools
- Developer / Agent → Content HTTP API: requests content (evidence: `packages/content/src/http-service.ts`)
- Content HTTP API → Pipeline Router: executes plans (evidence: `packages/content/src/http-service.ts`)
- Content HTTP API → Image Generation: generates images (evidence: `packages/content/src/http-service.ts`)
- Content HTTP API → Video Rendering: renders video (evidence: `packages/content/src/http-service.ts`)
- Content HTTP API → Data Visualizations: renders charts (evidence: `packages/content/src/http-service.ts`)
- Research Workflow → AutoCursor Agent: invokes agent (evidence: `skills/golem-powers/cursor-workflows/research/research.py`)
- Developer / Agent → Skill Workflows: loads workflows
- Developer / Agent → Mock MCP Server: tests skill behavior
- Developer / Agent → Claude Plugin: uses persona plugin
