# olimpiu-galea/ethos architecture

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

- Interactive diagram: https://gitdiagram.com/olimpiu-galea/ethos
- Repository: https://github.com/olimpiu-galea/ethos

## Overview

EthOS is a Next.js shift-supervisor application for ethanol plants, with configurable support for other domains. Its principal workflow is to combine plant signals, evaluate playbooks, present alerts in an operational agenda, and guide operator action. The README documents that overall flow; sampled sources confirm agenda synchronization and persistent playbook and alert state. Other product areas are included from the repository tree, but their internal wiring is not assumed where source was not sampled.

Main entry points: [`src/stores/playbook-store.ts`](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/playbook-store.ts) (Playbook State), [`src/app/agenda/page.tsx`](https://github.com/olimpiu-galea/ethos/blob/main/src/app/agenda/page.tsx) (Alert Agenda), [`src/hooks/use-all-signal-tags.ts`](https://github.com/olimpiu-galea/ethos/blob/main/src/hooks/use-all-signal-tags.ts) (Signal Sources), [`src/stores/auth-store.ts`](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/auth-store.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; Setup"]
  node_login["Login &amp; Signup<br/>[page.tsx]"]
  node_auth["Authentication<br/>[auth-store.ts]"]
  node_auth_policy["Roles &amp; Access<br/>[role-access.ts]"]
  node_setup["Company Setup<br/>[page.tsx]"]
  node_settings["Workspace Settings<br/>[settings-store.ts]"]
end

subgraph group_signals["Signals &amp; Evaluation"]
  node_signals["Signal Sources"]
  node_dcs["DCS Timeline<br/>[dcs-timeline.ts]"]
  node_playbook_ui["Playbook Management<br/>[page.tsx]"]
  node_playbooks["Playbook State<br/>[playbook-store.ts]"]
  node_playbook_logic["Playbook Logic<br/>[playbook-utils.ts]"]
  node_mock_alerts["Alert Generation"]
  node_integrations["Integrations<br/>[page.tsx]"]
end

subgraph group_operations["Operator Workflow"]
  node_agenda["Alert Agenda<br/>[page.tsx]"]
  node_alert_state[("Alert History")]
  node_batches["Batch Intelligence"]
  node_reports["Reports<br/>[page.tsx]"]
  node_copilot["Plant Copilot"]
end

subgraph group_domain["Plant Capabilities"]
  node_compliance["Compliance"]
  node_maintenance["Maintenance"]
  node_procurement["Procurement"]
  node_margin["Financial Margin<br/>[margin-desk.tsx]"]
end

subgraph group_platform["Shared State"]
  node_teams["Team Routing<br/>[teams.ts]"]
  node_brand["Brand &amp; UI<br/>[brand.ts]"]
end

node_operator(("Plant operator"))

node_operator -->|"signs in"| node_login
node_login -->|"authenticates"| node_auth
node_auth -->|"syncs company"| node_settings
node_operator -.->|"configures workspace"| node_setup
node_setup -->|"updates settings"| node_settings
node_operator -.->|"connects signals"| node_signals
node_signals -.->|"evaluates signals"| node_playbooks
node_operator -->|"configures playbooks"| node_playbook_ui
node_playbook_ui -->|"updates state"| node_playbooks
node_playbooks -->|"uses playbook logic"| node_playbook_logic
node_playbooks -->|"uses alert records"| node_mock_alerts
node_mock_alerts -->|"syncs alerts"| node_alert_state
node_operator -.->|"reviews alerts"| node_agenda
node_agenda -->|"reads playbooks"| node_playbooks
node_agenda -->|"shows sync status"| node_signals
node_agenda -.->|"reviews alert history"| node_alert_state
node_agenda -.->|"guides action"| node_operator
node_signals -.->|"includes timeline"| node_dcs
node_operator -.->|"manages feeds"| node_integrations
node_operator -.->|"creates reports"| node_reports
node_operator -.->|"reviews batches"| node_batches
node_operator -.->|"consults copilot"| node_copilot
node_operator -.->|"reviews compliance"| node_compliance
node_operator -.->|"manages maintenance"| node_maintenance
node_operator -.->|"manages procurement"| node_procurement
node_operator -.->|"reviews margin"| node_margin
node_auth -->|"checks roles"| node_auth_policy
node_playbooks -->|"uses team routing"| node_teams

click node_login "https://github.com/olimpiu-galea/ethos/blob/main/src/app/login/page.tsx"
click node_auth "https://github.com/olimpiu-galea/ethos/blob/main/src/stores/auth-store.ts"
click node_auth_policy "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/role-access.ts"
click node_setup "https://github.com/olimpiu-galea/ethos/blob/main/src/app/onboarding/page.tsx"
click node_settings "https://github.com/olimpiu-galea/ethos/blob/main/src/stores/settings-store.ts"
click node_signals "https://github.com/olimpiu-galea/ethos/blob/main/src/hooks/use-all-signal-tags.ts"
click node_dcs "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/dcs-timeline.ts"
click node_playbook_ui "https://github.com/olimpiu-galea/ethos/blob/main/src/app/playbooks/page.tsx"
click node_playbooks "https://github.com/olimpiu-galea/ethos/blob/main/src/stores/playbook-store.ts"
click node_playbook_logic "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/playbook-utils.ts"
click node_mock_alerts "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/mock-playbook-alerts.ts"
click node_agenda "https://github.com/olimpiu-galea/ethos/blob/main/src/app/agenda/page.tsx"
click node_alert_state "https://github.com/olimpiu-galea/ethos/blob/main/src/stores/alert-history-store.ts"
click node_batches "https://github.com/olimpiu-galea/ethos/blob/main/src/components/batches/batches-hub-2030.tsx"
click node_reports "https://github.com/olimpiu-galea/ethos/blob/main/src/app/reports/page.tsx"
click node_copilot "https://github.com/olimpiu-galea/ethos/blob/main/src/components/copilot/plant-copilot-demo.tsx"
click node_integrations "https://github.com/olimpiu-galea/ethos/blob/main/src/app/integrations/page.tsx"
click node_compliance "https://github.com/olimpiu-galea/ethos/blob/main/src/components/compliance/plant-compliance-demo.tsx"
click node_maintenance "https://github.com/olimpiu-galea/ethos/blob/main/src/components/maintenance/maintenance-hub.tsx"
click node_procurement "https://github.com/olimpiu-galea/ethos/blob/main/src/components/procurement/procurement-hub.tsx"
click node_margin "https://github.com/olimpiu-galea/ethos/blob/main/src/components/margin/margin-desk.tsx"
click node_teams "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/teams.ts"
click node_brand "https://github.com/olimpiu-galea/ethos/blob/main/src/lib/brand.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_login,node_auth,node_auth_policy,node_setup,node_settings toneBlue
class node_signals,node_dcs,node_playbook_ui,node_playbooks,node_playbook_logic,node_mock_alerts,node_integrations toneAmber
class node_agenda,node_alert_state,node_batches,node_reports,node_copilot toneMint
class node_compliance,node_maintenance,node_procurement,node_margin toneRose
class node_teams,node_brand,node_operator toneIndigo
```

## Components

### Identity & Setup

- [Login & Signup](https://github.com/olimpiu-galea/ethos/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Authentication](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/auth-store.ts): `src/stores/auth-store.ts`
- [Roles & Access](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/role-access.ts): `src/lib/role-access.ts`
- [Company Setup](https://github.com/olimpiu-galea/ethos/blob/main/src/app/onboarding/page.tsx): `src/app/onboarding/page.tsx`
- [Workspace Settings](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/settings-store.ts): `src/stores/settings-store.ts`

### Signals & Evaluation

- [Signal Sources](https://github.com/olimpiu-galea/ethos/blob/main/src/hooks/use-all-signal-tags.ts): `src/hooks/use-all-signal-tags.ts`
- [DCS Timeline](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/dcs-timeline.ts): `src/lib/dcs-timeline.ts`
- [Playbook Management](https://github.com/olimpiu-galea/ethos/blob/main/src/app/playbooks/page.tsx): `src/app/playbooks/page.tsx`
- [Playbook State](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/playbook-store.ts): `src/stores/playbook-store.ts`
- [Playbook Logic](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/playbook-utils.ts): `src/lib/playbook-utils.ts`
- [Alert Generation](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/mock-playbook-alerts.ts): `src/lib/mock-playbook-alerts.ts`
- [Integrations](https://github.com/olimpiu-galea/ethos/blob/main/src/app/integrations/page.tsx): `src/app/integrations/page.tsx`

### Operator Workflow

- [Alert Agenda](https://github.com/olimpiu-galea/ethos/blob/main/src/app/agenda/page.tsx): `src/app/agenda/page.tsx`
- [Alert History](https://github.com/olimpiu-galea/ethos/blob/main/src/stores/alert-history-store.ts): `src/stores/alert-history-store.ts`
- [Batch Intelligence](https://github.com/olimpiu-galea/ethos/blob/main/src/components/batches/batches-hub-2030.tsx): `src/components/batches/batches-hub-2030.tsx`
- [Reports](https://github.com/olimpiu-galea/ethos/blob/main/src/app/reports/page.tsx): `src/app/reports/page.tsx`
- [Plant Copilot](https://github.com/olimpiu-galea/ethos/blob/main/src/components/copilot/plant-copilot-demo.tsx): `src/components/copilot/plant-copilot-demo.tsx`

### Plant Capabilities

- [Compliance](https://github.com/olimpiu-galea/ethos/blob/main/src/components/compliance/plant-compliance-demo.tsx): `src/components/compliance/plant-compliance-demo.tsx`
- [Maintenance](https://github.com/olimpiu-galea/ethos/blob/main/src/components/maintenance/maintenance-hub.tsx): `src/components/maintenance/maintenance-hub.tsx`
- [Procurement](https://github.com/olimpiu-galea/ethos/blob/main/src/components/procurement/procurement-hub.tsx): `src/components/procurement/procurement-hub.tsx`
- [Financial Margin](https://github.com/olimpiu-galea/ethos/blob/main/src/components/margin/margin-desk.tsx): `src/components/margin/margin-desk.tsx`

### Shared State

- [Team Routing](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/teams.ts): `src/lib/teams.ts`
- [Brand & UI](https://github.com/olimpiu-galea/ethos/blob/main/src/lib/brand.ts): `src/lib/brand.ts`

### Other components

- **Plant operator**

## Connections

- Plant operator → Login & Signup: signs in (evidence: `src/app/login/page.tsx`)
- Login & Signup → Authentication: authenticates (evidence: `src/app/login/page.tsx`)
- Authentication → Workspace Settings: syncs company (evidence: `src/stores/auth-store.ts`)
- Plant operator → Company Setup: configures workspace
- Company Setup → Workspace Settings: updates settings (evidence: `src/app/onboarding/page.tsx`)
- Plant operator → Signal Sources: connects signals (evidence: `README.md`)
- Signal Sources → Playbook State: evaluates signals (evidence: `README.md`)
- Plant operator → Playbook Management: configures playbooks (evidence: `src/app/playbooks/page.tsx`)
- Playbook Management → Playbook State: updates state (evidence: `src/app/playbooks/page.tsx`)
- Playbook State → Playbook Logic: uses playbook logic (evidence: `src/stores/playbook-store.ts`)
- Playbook State → Alert Generation: uses alert records (evidence: `src/stores/playbook-store.ts`)
- Alert Generation → Alert History: syncs alerts (evidence: `src/lib/mock-playbook-alerts.ts`)
- Plant operator → Alert Agenda: reviews alerts (evidence: `README.md`)
- Alert Agenda → Playbook State: reads playbooks (evidence: `src/app/agenda/page.tsx`)
- Alert Agenda → Signal Sources: shows sync status (evidence: `src/app/agenda/page.tsx`)
- Alert Agenda → Alert History: reviews alert history (evidence: `src/app/agenda/page.tsx`)
- Alert Agenda → Plant operator: guides action (evidence: `README.md`)
- Signal Sources → DCS Timeline: includes timeline
- Plant operator → Integrations: manages feeds
- Plant operator → Reports: creates reports
- Plant operator → Batch Intelligence: reviews batches
- Plant operator → Plant Copilot: consults copilot
- Plant operator → Compliance: reviews compliance
- Plant operator → Maintenance: manages maintenance
- Plant operator → Procurement: manages procurement
- Plant operator → Financial Margin: reviews margin
- Authentication → Roles & Access: checks roles (evidence: `src/lib/role-access.ts`)
- Playbook State → Team Routing: uses team routing (evidence: `src/stores/playbook-store.ts`)
