# amadad/brandos architecture

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

- Interactive diagram: https://gitdiagram.com/amadad/brandos
- Repository: https://github.com/amadad/brandos

## Overview

brandOS is a CLI-first brand operations toolkit. Its documented workflow starts with brand configuration, develops persona and market intelligence, plans campaigns, produces content, evaluates it against quality criteria, publishes approved material, and monitors results for future learning. The graph preserves those major product stages and the autonomous decision loop. Several stage-to-stage links are documented in the README; sampled source confirms selected orchestration and persistence behavior, but not every integration or connection.

Main entry points: [`src/brand_os/cli.py`](https://github.com/amadad/brandos/blob/main/src/brand_os/cli.py) (CLI commands), [`src/brand_os/plan/cli.py`](https://github.com/amadad/brandos/blob/main/src/brand_os/plan/cli.py) (Campaign planning), [`src/brand_os/produce/cli.py`](https://github.com/amadad/brandos/blob/main/src/brand_os/produce/cli.py) (Content production), [`src/brand_os/eval/cli.py`](https://github.com/amadad/brandos/blob/main/src/brand_os/eval/cli.py) (Content evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_brand["Brand foundation"]
  node_brandconfig["Brand configuration<br/>[brands.py]"]
  node_persona["Persona tools<br/>[cli.py]"]
end

subgraph group_insight["Research and planning"]
  node_intel["Competitive intel<br/>[pipeline.py]"]
  node_signals["Signal monitoring<br/>[cli.py]"]
  node_planning["Campaign planning<br/>[cli.py]"]
  node_research["Market research<br/>[research.py]"]
  node_campaignstore["Campaign records<br/>[store.py]"]
end

subgraph group_content["Content lifecycle"]
  node_production["Content production<br/>[cli.py]"]
  node_copygen["Copy generation<br/>[copy.py]"]
  node_imagegen["Image generation<br/>[generate.py]"]
  node_videogen["Video generation<br/>[generate.py]"]
  node_evaluation["Content evaluation<br/>[cli.py]"]
  node_evallearning["Evaluation learnings<br/>[learnings.py]"]
end

subgraph group_operations["Publishing and monitoring"]
  node_publishqueue["Publishing queue<br/>[queue.py]"]
  node_publisher["Platform publishing<br/>[cli.py]"]
  node_monitor["Brand reports<br/>[reports.py]"]
  node_autoloop["Autonomous loop<br/>[loop.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_decision["Decision and policy<br/>[decision.py]"]
  node_llm["LLM interface<br/>[llm.py]"]
  node_datadir["Local data paths<br/>[storage.py]"]
end

node_user(("Operator"))
node_llmservice{{"LLM providers"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"manages brands"| node_brandconfig
node_cli -->|"runs persona"| node_persona
node_cli -->|"runs intel"| node_intel
node_cli -->|"fetches signals"| node_signals
node_cli -->|"plans campaigns"| node_planning
node_cli -->|"generates content"| node_production
node_cli -->|"grades content"| node_evaluation
node_cli -->|"publishes posts"| node_publisher
node_planning -->|"runs research"| node_research
node_planning -->|"saves campaigns"| node_campaignstore
node_production -->|"generates copy"| node_copygen
node_production -->|"generates images"| node_imagegen
node_production -->|"generates video"| node_videogen
node_evaluation -->|"logs evaluations"| node_evallearning
node_publisher -->|"reads and updates"| node_publishqueue
node_autoloop -->|"checks decisions"| node_decision
node_research -->|"requests analysis"| node_llm
node_persona -.->|"generates persona"| node_llm
node_llm -->|"calls provider"| node_llmservice
node_planning -.->|"stores output"| node_datadir
node_intel -->|"loads brand config"| node_brandconfig
node_autoloop -->|"loads brand config"| node_brandconfig
node_cli -->|"runs reports"| node_monitor
node_intel -.->|"informs planning"| node_planning
node_planning -.->|"guides production"| node_production
node_production -.->|"submits content"| node_evaluation
node_evaluation -.->|"approves for queue"| node_publishqueue
node_publisher -.->|"provides outcomes"| node_monitor
node_monitor -.->|"feeds learning"| node_evallearning

click node_cli "https://github.com/amadad/brandos/blob/main/src/brand_os/cli.py"
click node_brandconfig "https://github.com/amadad/brandos/blob/main/src/brand_os/core/brands.py"
click node_persona "https://github.com/amadad/brandos/blob/main/src/brand_os/persona/cli.py"
click node_intel "https://github.com/amadad/brandos/blob/main/src/brand_os/intel/pipeline.py"
click node_signals "https://github.com/amadad/brandos/blob/main/src/brand_os/signals/cli.py"
click node_planning "https://github.com/amadad/brandos/blob/main/src/brand_os/plan/cli.py"
click node_research "https://github.com/amadad/brandos/blob/main/src/brand_os/plan/stages/research.py"
click node_campaignstore "https://github.com/amadad/brandos/blob/main/src/brand_os/plan/store.py"
click node_production "https://github.com/amadad/brandos/blob/main/src/brand_os/produce/cli.py"
click node_copygen "https://github.com/amadad/brandos/blob/main/src/brand_os/produce/copy.py"
click node_imagegen "https://github.com/amadad/brandos/blob/main/src/brand_os/produce/image/generate.py"
click node_videogen "https://github.com/amadad/brandos/blob/main/src/brand_os/produce/video/generate.py"
click node_evaluation "https://github.com/amadad/brandos/blob/main/src/brand_os/eval/cli.py"
click node_evallearning "https://github.com/amadad/brandos/blob/main/src/brand_os/eval/learnings.py"
click node_publishqueue "https://github.com/amadad/brandos/blob/main/src/brand_os/publish/queue.py"
click node_publisher "https://github.com/amadad/brandos/blob/main/src/brand_os/publish/cli.py"
click node_monitor "https://github.com/amadad/brandos/blob/main/src/brand_os/monitor/reports.py"
click node_autoloop "https://github.com/amadad/brandos/blob/main/src/brand_os/loop.py"
click node_decision "https://github.com/amadad/brandos/blob/main/src/brand_os/core/decision.py"
click node_llm "https://github.com/amadad/brandos/blob/main/src/brand_os/core/llm.py"
click node_datadir "https://github.com/amadad/brandos/blob/main/src/brand_os/core/storage.py"

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 toneBlue
class node_brandconfig,node_persona toneAmber
class node_intel,node_signals,node_planning,node_research,node_campaignstore toneMint
class node_production,node_copygen,node_imagegen,node_videogen,node_evaluation,node_evallearning toneRose
class node_publishqueue,node_publisher,node_monitor,node_autoloop,node_user,node_llmservice toneIndigo
class node_decision,node_llm,node_datadir toneTeal
```

## Components

### User entry

- [CLI commands](https://github.com/amadad/brandos/blob/main/src/brand_os/cli.py): `src/brand_os/cli.py`

### Brand foundation

- [Brand configuration](https://github.com/amadad/brandos/blob/main/src/brand_os/core/brands.py): `src/brand_os/core/brands.py`
- [Persona tools](https://github.com/amadad/brandos/blob/main/src/brand_os/persona/cli.py): `src/brand_os/persona/cli.py`

### Research and planning

- [Competitive intel](https://github.com/amadad/brandos/blob/main/src/brand_os/intel/pipeline.py): `src/brand_os/intel/pipeline.py`
- [Signal monitoring](https://github.com/amadad/brandos/blob/main/src/brand_os/signals/cli.py): `src/brand_os/signals/cli.py`
- [Campaign planning](https://github.com/amadad/brandos/blob/main/src/brand_os/plan/cli.py): `src/brand_os/plan/cli.py`
- [Market research](https://github.com/amadad/brandos/blob/main/src/brand_os/plan/stages/research.py): `src/brand_os/plan/stages/research.py`
- [Campaign records](https://github.com/amadad/brandos/blob/main/src/brand_os/plan/store.py): `src/brand_os/plan/store.py`

### Content lifecycle

- [Content production](https://github.com/amadad/brandos/blob/main/src/brand_os/produce/cli.py): `src/brand_os/produce/cli.py`
- [Copy generation](https://github.com/amadad/brandos/blob/main/src/brand_os/produce/copy.py): `src/brand_os/produce/copy.py`
- [Image generation](https://github.com/amadad/brandos/blob/main/src/brand_os/produce/image/generate.py): `src/brand_os/produce/image/generate.py`
- [Video generation](https://github.com/amadad/brandos/blob/main/src/brand_os/produce/video/generate.py): `src/brand_os/produce/video/generate.py`
- [Content evaluation](https://github.com/amadad/brandos/blob/main/src/brand_os/eval/cli.py): `src/brand_os/eval/cli.py`
- [Evaluation learnings](https://github.com/amadad/brandos/blob/main/src/brand_os/eval/learnings.py): `src/brand_os/eval/learnings.py`

### Publishing and monitoring

- [Publishing queue](https://github.com/amadad/brandos/blob/main/src/brand_os/publish/queue.py): `src/brand_os/publish/queue.py`
- [Platform publishing](https://github.com/amadad/brandos/blob/main/src/brand_os/publish/cli.py): `src/brand_os/publish/cli.py`
- [Brand reports](https://github.com/amadad/brandos/blob/main/src/brand_os/monitor/reports.py): `src/brand_os/monitor/reports.py`
- [Autonomous loop](https://github.com/amadad/brandos/blob/main/src/brand_os/loop.py): `src/brand_os/loop.py`

### Shared runtime

- [Decision and policy](https://github.com/amadad/brandos/blob/main/src/brand_os/core/decision.py): `src/brand_os/core/decision.py`
- [LLM interface](https://github.com/amadad/brandos/blob/main/src/brand_os/core/llm.py): `src/brand_os/core/llm.py`
- [Local data paths](https://github.com/amadad/brandos/blob/main/src/brand_os/core/storage.py): `src/brand_os/core/storage.py`

### Other components

- **Operator**
- **LLM providers**

## Connections

- Operator → CLI commands: runs commands
- CLI commands → Brand configuration: manages brands
- CLI commands → Persona tools: runs persona
- CLI commands → Competitive intel: runs intel
- CLI commands → Signal monitoring: fetches signals
- CLI commands → Campaign planning: plans campaigns
- CLI commands → Content production: generates content
- CLI commands → Content evaluation: grades content
- CLI commands → Platform publishing: publishes posts
- Campaign planning → Market research: runs research
- Campaign planning → Campaign records: saves campaigns
- Content production → Copy generation: generates copy
- Content production → Image generation: generates images
- Content production → Video generation: generates video
- Content evaluation → Evaluation learnings: logs evaluations
- Platform publishing → Publishing queue: reads and updates
- Autonomous loop → Decision and policy: checks decisions
- Market research → LLM interface: requests analysis
- Persona tools → LLM interface: generates persona
- LLM interface → LLM providers: calls provider
- Campaign planning → Local data paths: stores output
- Competitive intel → Brand configuration: loads brand config
- Autonomous loop → Brand configuration: loads brand config
- CLI commands → Brand reports: runs reports
- Competitive intel → Campaign planning: informs planning
- Campaign planning → Content production: guides production
- Content production → Content evaluation: submits content
- Content evaluation → Publishing queue: approves for queue
- Platform publishing → Brand reports: provides outcomes
- Brand reports → Evaluation learnings: feeds learning