# tegarthegreat/palugada architecture

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

- Interactive diagram: https://gitdiagram.com/tegarthegreat/palugada
- Repository: https://github.com/tegarthegreat/palugada

## Overview

PALUGADA is a self-hosted control plane for AI-run companies. The principal workflow is: an owner configures goals and roles, submits work, and receives consequential decisions in an inbox; the platform plans and budgets tasks, runs agents through a controlled runtime and capability broker, then records outcomes for reporting and organizational learning. The console exposes this workflow alongside documented features such as schedules, bundles, skills, memory, audit, and cost controls. Relationships come from README statements and shown imports/calls; unsampled subsystem wiring is not asserted.

Main entry points: [`src/inbox/inbox.ts`](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/inbox/inbox.ts) (Approval inbox), [`src/engine/engine.ts`](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/engine.ts) (Task engine), [`src/engine/tasks.ts`](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/tasks.ts) (Task lifecycle), [`console/src/App.tsx`](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/console/src/App.tsx) (Web console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Owner console"]
  node_console["Web console<br/>[App.tsx]"]
  node_decisions["Decision inbox<br/>[Decisions.tsx]"]
  node_api["Owner API<br/>[api.ts]"]
end

subgraph group_governance["Company governance"]
  node_company["Company structure<br/>[structure.ts]"]
  node_goals["Goals<br/>[goals.ts]"]
  node_settings["Company settings<br/>[store.ts]"]
  node_scheduler["Schedules and triggers<br/>[windows.ts]"]
end

subgraph group_work["Work orchestration"]
  node_worker["Background worker<br/>[worker.ts]"]
  node_engine["Task engine<br/>[engine.ts]"]
  node_tasks["Task lifecycle<br/>[tasks.ts]"]
  node_budget["Spend guard<br/>[spend-guard.ts]"]
  node_inbox["Approval inbox<br/>[inbox.ts]"]
end

subgraph group_execution["Agent execution"]
  node_broker["Capability broker<br/>[broker.ts]"]
  node_runtime["Agent runtime<br/>[cli.ts]"]
  node_models["Model providers<br/>[client.ts]"]
end

subgraph group_oversight["Learning and oversight"]
  node_database[("Tenant database<br/>[tenant.ts]")]
  node_audit[("Event log<br/>[event-log.ts]")]
  node_memory[("Company memory<br/>[store.ts]")]
  node_skills["Skills and evals<br/>[skills.ts]"]
  node_reporting["Reports and alerts<br/>[alerts.ts]"]
  node_bundles["Company bundles<br/>[bundle.ts]"]
end

node_owner(("Owner"))

node_owner -->|"manages company"| node_console
node_console -.->|"calls API"| node_api
node_console -.->|"presents decisions"| node_decisions
node_owner -->|"reviews requests"| node_decisions
node_api -.->|"serves decisions"| node_inbox
node_company -.->|"organizes work"| node_goals
node_owner -->|"sets direction"| node_goals
node_scheduler -.->|"wakes work"| node_worker
node_worker -->|"runs tasks"| node_engine
node_engine -->|"claims and transitions"| node_tasks
node_engine -.->|"invokes capabilities"| node_broker
node_tasks -->|"checks spend"| node_budget
node_broker -->|"requests approval"| node_inbox
node_owner -->|"approves actions"| node_inbox
node_runtime -->|"requests tools"| node_broker
node_runtime -.->|"uses model"| node_models
node_engine -->|"loads tenant context"| node_database
node_tasks -->|"appends events"| node_audit
node_inbox -->|"transitions tasks"| node_tasks
node_inbox -->|"reads and writes"| node_database
node_engine -.->|"builds run context"| node_memory
node_skills -.->|"submits candidates"| node_inbox
node_worker -->|"runs oversight"| node_reporting
node_company -.->|"supports configuration bundles"| node_bundles
node_owner -->|"searches company knowledge"| node_memory
node_owner -.->|"reviews skills"| node_skills
node_owner -->|"sets recurring work"| node_scheduler
node_owner -->|"views costs and status"| node_reporting

click node_console "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/console/src/App.tsx"
click node_decisions "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/console/src/pages/Decisions.tsx"
click node_api "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/owner/api.ts"
click node_company "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/governance/structure.ts"
click node_goals "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/domain/goals.ts"
click node_settings "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/settings/store.ts"
click node_scheduler "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/scheduler/windows.ts"
click node_worker "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/worker.ts"
click node_engine "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/engine.ts"
click node_tasks "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/tasks.ts"
click node_budget "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/governance/spend-guard.ts"
click node_inbox "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/inbox/inbox.ts"
click node_broker "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/broker/broker.ts"
click node_runtime "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/runtime/cli.ts"
click node_models "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/llm/client.ts"
click node_database "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/db/tenant.ts"
click node_audit "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/audit/event-log.ts"
click node_memory "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/memory/store.ts"
click node_skills "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/skills/skills.ts"
click node_reporting "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/reporting/alerts.ts"
click node_bundles "https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/bundles/bundle.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_console,node_decisions,node_api toneBlue
class node_company,node_goals,node_settings,node_scheduler toneAmber
class node_worker,node_engine,node_tasks,node_budget,node_inbox toneMint
class node_broker,node_runtime,node_models toneRose
class node_database,node_audit,node_memory,node_skills,node_reporting,node_bundles,node_owner toneIndigo
```

## Components

### Owner console

- [Web console](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/console/src/App.tsx): `console/src/App.tsx`
- [Decision inbox](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/console/src/pages/Decisions.tsx): `console/src/pages/Decisions.tsx`
- [Owner API](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/owner/api.ts): `src/owner/api.ts`

### Company governance

- [Company structure](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/governance/structure.ts): `src/governance/structure.ts`
- [Goals](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/domain/goals.ts): `src/domain/goals.ts`
- [Company settings](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/settings/store.ts): `src/settings/store.ts`
- [Schedules and triggers](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/scheduler/windows.ts): `src/scheduler/windows.ts`

### Work orchestration

- [Background worker](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/worker.ts): `src/worker.ts`
- [Task engine](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/engine.ts): `src/engine/engine.ts`
- [Task lifecycle](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/engine/tasks.ts): `src/engine/tasks.ts`
- [Spend guard](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/governance/spend-guard.ts): `src/governance/spend-guard.ts`
- [Approval inbox](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/inbox/inbox.ts): `src/inbox/inbox.ts`

### Agent execution

- [Capability broker](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/broker/broker.ts): `src/broker/broker.ts`
- [Agent runtime](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/runtime/cli.ts): `src/runtime/cli.ts`
- [Model providers](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/llm/client.ts): `src/llm/client.ts`

### Learning and oversight

- [Tenant database](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/db/tenant.ts): `src/db/tenant.ts`
- [Event log](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/audit/event-log.ts): `src/audit/event-log.ts`
- [Company memory](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/memory/store.ts): `src/memory/store.ts`
- [Skills and evals](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/skills/skills.ts): `src/skills/skills.ts`
- [Reports and alerts](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/reporting/alerts.ts): `src/reporting/alerts.ts`
- [Company bundles](https://github.com/tegarthegreat/palugada/blob/claude/palugada-orchestrator-prd-w7f657/src/bundles/bundle.ts): `src/bundles/bundle.ts`

### Other components

- **Owner**

## Connections

- Owner → Web console: manages company (evidence: `README.md`)
- Web console → Owner API: calls API
- Web console → Decision inbox: presents decisions (evidence: `console/src/App.tsx`)
- Owner → Decision inbox: reviews requests (evidence: `README.md`)
- Owner API → Approval inbox: serves decisions
- Company structure → Goals: organizes work
- Owner → Goals: sets direction (evidence: `README.md`)
- Schedules and triggers → Background worker: wakes work
- Background worker → Task engine: runs tasks (evidence: `src/worker.ts`)
- Task engine → Task lifecycle: claims and transitions (evidence: `src/engine/engine.ts`)
- Task engine → Capability broker: invokes capabilities (evidence: `src/engine/engine.ts`)
- Task lifecycle → Spend guard: checks spend (evidence: `src/engine/tasks.ts`)
- Capability broker → Approval inbox: requests approval (evidence: `src/broker/broker.ts`)
- Owner → Approval inbox: approves actions (evidence: `README.md`)
- Agent runtime → Capability broker: requests tools (evidence: `README.md`)
- Agent runtime → Model providers: uses model
- Task engine → Tenant database: loads tenant context (evidence: `src/engine/engine.ts`)
- Task lifecycle → Event log: appends events (evidence: `src/engine/tasks.ts`)
- Approval inbox → Task lifecycle: transitions tasks (evidence: `src/inbox/inbox.ts`)
- Approval inbox → Tenant database: reads and writes (evidence: `src/inbox/inbox.ts`)
- Task engine → Company memory: builds run context
- Skills and evals → Approval inbox: submits candidates (evidence: `src/skills/skills.ts`)
- Background worker → Reports and alerts: runs oversight (evidence: `src/worker.ts`)
- Company structure → Company bundles: supports configuration bundles
- Owner → Company memory: searches company knowledge (evidence: `README.md`)
- Owner → Skills and evals: reviews skills
- Owner → Schedules and triggers: sets recurring work (evidence: `README.md`)
- Owner → Reports and alerts: views costs and status (evidence: `README.md`)