# rishabjn10/marketmuse architecture

> Architecture diagram of the GitHub repository rishabjn10/marketmuse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rishabjn10/marketmuse
- Repository: https://github.com/rishabjn10/marketmuse

## Overview

##### Project type and purpose
- This is a CLI‑based Python application (“market_muse”) built on the CrewAI framework.
- Its goal is to orchestrate autonomous AI agents (defined in YAML) that collaborate to generate a complete marketing strategy.

##### File structure
- Top level:
- `.gitignore`, `RATIONALE.md`, `README.md`, `pyproject.toml` (Poetry project + entrypoint)
- `src/market_muse/` package:
- `.env.example` – environment‑variable template
- `config/` – two YAML files (`agents.yaml`, `tasks.yaml`) driving agent definitions and task pipelines
- `main.py` – CLI entrypoint that loads env, configs, and kicks off Crew
- `crew.py` – orchestrator module that reads configs, instantiates agents, dispatches tasks
- (Optional) `tools/` – custom tool classes used by agents to interact with AI services or external systems

##### README for additional insights
- Entrypoint command: `poetry run market_muse`
- Instructions to configure `.env` and YAML files to customize agents/tasks
- Emphasis on CrewAI framework as the engine for agent collaboration

a. Main components
1. User/CLI Layer
2. Environment Loader (`.env`) & Configuration Loader (`agents.yaml` + `tasks.yaml`)
3. Core Application Modules (`main.py` + `crew.py`)
4. Agent Instances (dynamically created by CrewAI)
5. Tool Classes (helpers for agents)
6. External AI Service (e.g., OpenAI API)
7. Output/Reporting Layer (console or files)
b. Relationships & interactions
- User invokes CLI →
- main.py:
- Loads `.env` → sets API keys, other vars
- Parses YAML configs → builds agent & task definitions
- crew.py:
- Creates CrewAI engine → reads definitions → spins up Agent objects
- Orchestrates task flow: each Agent calls Tool methods → Tool makes API calls → returns data
- Crew aggregates intermediate results, coordinates handoff between agents
- Final aggregated strategy → printed to console or written to file
c. Architectural patterns & design principles
- Orchestration pattern: centralized engine (crew.py) managing distributed agents
- Configuration‑driven extensibility: YAML files define agents/tasks without code changes
- Plugin‑style tools: new capabilities added by dropping new Tool classes in `tools/`
- Dependency injection: CrewAI framework injects configs & tools into agent instances
d. Key technologies & libraries
- Python 3.x, Poetry (pyproject.toml)
- CrewAI Framework (core orchestration library)
- YAML (agents.yaml, tasks.yaml) for declarative configuration
- External AI API (e.g., OpenAI via HTTP)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Level Metadata
    subgraph "Project Metadata"
        PMC["pyproject.toml"]:::config
        RM["README.md"]:::config
    end

    %% User CLI Layer
    U["User (CLI Invocation)"]

    %% Main Entrypoint
    M["main.py"]:::code
    click M "https://github.com/rishabjn10/marketmuse/blob/master/src/market_muse/main.py"

    %% Environment & Config Loaders
    E[".env.example"]:::config
    click E "https://github.com/rishabjn10/marketmuse/blob/master/src/market_muse/.env.example"
    subgraph "Configuration Directory"
        CD["config/"]:::config
        click CD "https://github.com/rishabjn10/marketmuse/tree/master/src/market_muse/config"
        AC["agents.yaml"]:::config
        click AC "https://github.com/rishabjn10/marketmuse/blob/master/src/market_muse/config/agents.yaml"
        TC["tasks.yaml"]:::config
        click TC "https://github.com/rishabjn10/marketmuse/blob/master/src/market_muse/config/tasks.yaml"
    end

    %% Core Orchestrator
    C["crew.py"]:::code
    click C "https://github.com/rishabjn10/marketmuse/blob/master/src/market_muse/crew.py"

    %% Agents & Tools
    subgraph "Agent Layer"
        A["Agent Instances"]:::code
    end
    subgraph "Extension Tools" style dashed
        T["tools/"]:::ext
    end

    %% External Service
    EX["External AI Service"]:::external

    %% Output Layer
    O["Output (Console/File)"]:::code

    %% Flows
    U -->|"invoke CLI"| M
    M -->|"load env"| E
    M -->|"parse configs"| CD
    M -->|"instantiate orchestrator"| C
    C -->|"create agents"| A
    A -->|"use tools"| T
    T -->|"API request/response"| EX
    EX -->|"return data"| A
    C -->|"aggregate results"| O

    %% Legend
    subgraph Legend
        L1["Rectangle: Code Modules"]:::code
        L2["Cylinder: Config Files/Dirs"]:::config
        L3["Cloud: External Services"]:::external
        L4["Dashed Box: Extension Points"]:::ext
    end

    %% Styling
    classDef code fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef config fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef external fill:#ffe5b4,stroke:#e69500,color:#e69500,stroke-width:1px;
    classDef ext stroke-dasharray: 5 5,fill:#f8f9fa,stroke:#6c757d,color:#6c757d,stroke-width:1px;
```
