# nazazx/casevisionb architecture

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

- Interactive diagram: https://gitdiagram.com/nazazx/casevisionb
- Repository: https://github.com/nazazx/casevisionb

## Overview

Nomad Roasters Content Agent turns a plain-language brief and one server-selected promotion snapshot into a validated Instagram caption—or a blocked/clarification result. CLI and Streamlit are the user-facing entry points; the pipeline coordinates planning and finalization, while catalog policy keeps product and commercial facts authoritative. The README documents hybrid retrieval, optional brand knowledge, audit records, and clarification selection. Some source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/nomad_agent/pipeline.py`](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/pipeline.py) (Content pipeline), [`src/nomad_agent/catalog.py`](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/catalog.py) (Snapshot catalog), [`src/nomad_agent/cli.py`](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/cli.py) (CLI), [`src/nomad_agent/llm.py`](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/llm.py) (Caption planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
end

subgraph group_core["Generation workflow"]
  node_pipeline["Content pipeline<br/>[pipeline.py]"]
  node_planner["Caption planner<br/>[llm.py]"]
  node_plan_policy["Plan normalization<br/>[policy.py]"]
  node_renderer["Caption validation<br/>[renderer.py]"]
  node_phrases["Approved phrase catalogue<br/>[phrases.py]"]
end

subgraph group_facts["Product and brand facts"]
  node_catalog["Snapshot catalog<br/>[catalog.py]"]
  node_retrieval["Product matching"]
  node_feed["Promotion feed"]
  node_brand["Brand guidance<br/>[brand_kit.md]"]
  node_brand_retriever["Brand knowledge search<br/>[brand.py]"]
end

subgraph group_support["Results and integrations"]
  node_result["Generation result<br/>[schemas.py]"]
  node_audit[("Run audit log<br/>[audit.py]")]
  node_telemetry["Run telemetry<br/>[telemetry.py]"]
end

node_user(("Content creator"))
node_openai{{"OpenAI API"}}

node_user -->|"submits brief"| node_cli
node_user -->|"submits brief"| node_dashboard
node_cli -->|"starts generation"| node_pipeline
node_dashboard -->|"starts generation"| node_pipeline
node_cli -->|"loads feed snapshot"| node_catalog
node_dashboard -->|"selects feed snapshot"| node_catalog
node_pipeline -->|"requests plan"| node_planner
node_planner -->|"searches products"| node_catalog
node_planner -->|"loads product details"| node_catalog
node_catalog -->|"ranks candidates"| node_retrieval
node_retrieval -.->|"embeds query and products"| node_openai
node_catalog -->|"reads snapshot"| node_feed
node_planner -.->|"searches style references"| node_brand_retriever
node_brand_retriever -.->|"queries vector store"| node_openai
node_pipeline -->|"normalizes plan"| node_plan_policy
node_pipeline -->|"validates and renders"| node_renderer
node_renderer -->|"uses templates"| node_phrases
node_pipeline -->|"constructs result"| node_result
node_pipeline -->|"records run metrics"| node_telemetry
node_cli -->|"appends run"| node_audit
node_cli -->|"loads guidance"| node_brand

click node_cli "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/cli.py"
click node_dashboard "https://github.com/nazazx/casevisionb/blob/main/app.py"
click node_pipeline "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/pipeline.py"
click node_planner "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/llm.py"
click node_plan_policy "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/policy.py"
click node_renderer "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/renderer.py"
click node_phrases "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/phrases.py"
click node_catalog "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/catalog.py"
click node_retrieval "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/product_retrieval.py"
click node_feed "https://github.com/nazazx/casevisionb/blob/main/promotions_feed_week1.json"
click node_brand "https://github.com/nazazx/casevisionb/blob/main/brand_kit.md"
click node_brand_retriever "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/brand.py"
click node_result "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/schemas.py"
click node_audit "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/audit.py"
click node_telemetry "https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/telemetry.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,node_dashboard toneBlue
class node_pipeline,node_planner,node_plan_policy,node_renderer,node_phrases toneAmber
class node_catalog,node_retrieval,node_feed,node_brand,node_brand_retriever,node_openai toneMint
class node_result,node_audit,node_telemetry toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/cli.py): `src/nomad_agent/cli.py`
- [Streamlit dashboard](https://github.com/nazazx/casevisionb/blob/main/app.py): `app.py`

### Generation workflow

- [Content pipeline](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/pipeline.py): `src/nomad_agent/pipeline.py`
- [Caption planner](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/llm.py): `src/nomad_agent/llm.py`
- [Plan normalization](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/policy.py): `src/nomad_agent/policy.py`
- [Caption validation](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/renderer.py): `src/nomad_agent/renderer.py`
- [Approved phrase catalogue](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/phrases.py): `src/nomad_agent/phrases.py`

### Product and brand facts

- [Snapshot catalog](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/catalog.py): `src/nomad_agent/catalog.py`
- [Product matching](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/product_retrieval.py): `src/nomad_agent/product_retrieval.py`
- [Promotion feed](https://github.com/nazazx/casevisionb/blob/main/promotions_feed_week1.json): `promotions_feed_week1.json`
- [Brand guidance](https://github.com/nazazx/casevisionb/blob/main/brand_kit.md): `brand_kit.md`
- [Brand knowledge search](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/brand.py): `src/nomad_agent/brand.py`

### Results and integrations

- [Generation result](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/schemas.py): `src/nomad_agent/schemas.py`
- [Run audit log](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/audit.py): `src/nomad_agent/audit.py`
- [Run telemetry](https://github.com/nazazx/casevisionb/blob/main/src/nomad_agent/telemetry.py): `src/nomad_agent/telemetry.py`

### Other components

- **Content creator**
- **OpenAI API**

## Connections

- Content creator → CLI: submits brief
- Content creator → Streamlit dashboard: submits brief
- CLI → Content pipeline: starts generation
- Streamlit dashboard → Content pipeline: starts generation
- CLI → Snapshot catalog: loads feed snapshot
- Streamlit dashboard → Snapshot catalog: selects feed snapshot
- Content pipeline → Caption planner: requests plan
- Caption planner → Snapshot catalog: searches products
- Caption planner → Snapshot catalog: loads product details
- Snapshot catalog → Product matching: ranks candidates
- Product matching → OpenAI API: embeds query and products
- Snapshot catalog → Promotion feed: reads snapshot
- Caption planner → Brand knowledge search: searches style references
- Brand knowledge search → OpenAI API: queries vector store
- Content pipeline → Plan normalization: normalizes plan
- Content pipeline → Caption validation: validates and renders
- Caption validation → Approved phrase catalogue: uses templates
- Content pipeline → Generation result: constructs result
- Content pipeline → Run telemetry: records run metrics
- CLI → Run audit log: appends run
- CLI → Brand guidance: loads guidance