# symphony-professional-services/chat-factory architecture

> Architecture diagram of the GitHub repository symphony-professional-services/chat-factory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/symphony-professional-services/chat-factory
- Repository: https://github.com/symphony-professional-services/chat-factory

## Overview

##### Main Components
- Data Generation Engine – Represented primarily by main.py.
- It uses configuration settings from config.py.
- It reads taxonomy definitions from taxonomy.json.
- It constructs inputs (e.g., advisor, client, topics, categories) and then calls a language model (or placeholder) to generate conversation data.
- Synthetic Data Storage – Represented by the synthetic_data directory.
- Contains subdirectories for each advisor and corresponding JSON files (one per client) where generated conversations are stored.
- Metrics and Analytics Modules – Encompassing metrics.py and display_metrics.py.
- These components analyze conversation logs (log files and metrics_log.csv) to provide insights and visualizations of usage and conversation metrics.
- Utility and Automation Scripts:
- run.sh (or run_and_log.sh) acts as a wrapper to automate the data generation process and logging.
- process_synthetic_data.py is used for further post-processing of the generated data.

##### Out Relationships and Interactions
- The starting point is execution via run.sh or run_and_log.sh. This script triggers the data generation by calling main.py.
- In main.py, the following interactions occur:
- It reads configuration (config.py) and taxonomy (taxonomy.json).
- It uses randomness to select advisors and clients.
- It constructs and logs generated synthetic chat data.
- It persists the output JSON files into synthetic_data (organized by advisor names).
- Separately, the metrics.py (and associated display_metrics.py) module picks up the logged data (metrics_log.csv, synthetic_chat_generator.log, and run_and_log.log) to compute analytics.
- process_synthetic_data.py provides an alternative script path for specialized data processing needs.

##### Architectural Patterns and Design Principles
- Modularity: The project is clearly divided into separate modules for generation, storage, and analytics.
- Separation of Concerns: Configuration, data generation, logging, and processing each have their own dedicated scripts and files.
- Extensibility: With external taxonomy and configuration files (taxonomy.json and config.py), the system is designed to be easily extended to include more advisors, topics, or client profiles.

- From the Synthetic Chat Generator, branch out to:
- A “Configuration & Taxonomy” block (config.py and taxonomy.json) indicating the data used as input.
- Optionally, include a “Logging” component that shows logging of both data generation and metric collection errors/information.
- That configuration and taxonomy files are the “knowledge base” for the synthetic conversation generation process.

##### In Summary
- The input components (config.py, taxonomy.json).
- The central synthetic data generator (main.py) and its control flow from run.sh.
- The storage mechanism for generated data (synthetic_data directory and JSON files) with clear mapping to advisor and client structure.
- The analytics modules (metrics.py, display_metrics.py) that consume logs and metrics for insights.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Execution Layer
    subgraph "Execution Layer"
        EXE["\"run.sh - Execution Script\""]:::script
    end

    %% Synthetic Chat Generation Layer
    subgraph "Synthetic Chat Generation"
        DG["\"main.py - Data Generator\""]:::script
        CONFIG["\"config.py - Configuration\""]:::config
        TAX["\"taxonomy.json - Taxonomy\""]:::config
        DATA_STORE["\"synthetic_data - Chat Storage\""]:::data
        LOGS["\"Logs:\\nsynthetic_chat_generator.log\\nrun_and_log.log\""]:::logging
    end

    %% Metrics & Analytics Layer
    subgraph "Metrics & Analytics"
        METRICS["\"metrics.py - Analytics Engine\""]:::script
        DISPLAY["\"display_metrics.py - Visualization\""]:::script
        PROCESS["\"process_synthetic_data.py - Data Processing\""]:::script
        METRICS_LOG["\"metrics_log.csv - Metrics Log\""]:::logging
    end

    %% Data Flow Connections
    EXE -->|"triggers"| DG
    DG -->|"reads"| CONFIG
    DG -->|"reads"| TAX
    DG -->|"writes JSON"| DATA_STORE
    DG -->|"logs"| LOGS

    DATA_STORE -->|"feeds data"| METRICS
    LOGS -->|"supplies logs"| METRICS
    DATA_STORE -->|"feeds data"| DISPLAY
    LOGS -->|"supplies logs"| DISPLAY
    DATA_STORE -->|"feeds data"| PROCESS

    %% Click Events
    click DG "https://github.com/symphony-professional-services/chat-factory/blob/master/main.py"
    click CONFIG "https://github.com/symphony-professional-services/chat-factory/blob/master/config.py"
    click TAX "https://github.com/symphony-professional-services/chat-factory/blob/master/taxonomy.json"
    click METRICS "https://github.com/symphony-professional-services/chat-factory/blob/master/metrics.py"
    click PROCESS "https://github.com/symphony-professional-services/chat-factory/blob/master/process_synthetic_data.py"
    click EXE "https://github.com/symphony-professional-services/chat-factory/blob/master/run.sh"

    %% Styles
    classDef script fill:#FDF6E3,stroke:#657B83,stroke-width:2px;
    classDef config fill:#EEE8D5,stroke:#586E75,stroke-width:2px;
    classDef data fill:#93a1a1,stroke:#002B36,stroke-width:2px;
    classDef logging fill:#FFEB3B,stroke:#F57F17,stroke-width:2px;
```
