# harrishphotos/sales-forecast-ai architecture

> Architecture diagram of the GitHub repository harrishphotos/sales-forecast-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harrishphotos/sales-forecast-ai
- Repository: https://github.com/harrishphotos/sales-forecast-ai

## Overview

##### Project Type & Purpose
- It’s a microservices-style backend system built with FastAPI.
- Four agents (each in its own Docker container) collaborate to process historical data, generate forecasts, and recommend strategies.
- A shared Python package (`shared_models`) holds common schemas and exceptions.

##### File Structure
- Top-level components:
– `docker-compose.yml` orchestrates the containers over a private Docker network.
– Four directories (each with a Dockerfile & `app.py`):
- `analysis_agent` – historical data processing
- `prediction_agent` – forecast generation
- `recommender_agent` – strategy recommendation
- `orchestration_agent` – pipeline controller, includes `pipeline.py`, `repository.py`, and `ops_module/report_ops.py`
– `shared_models` – common code shared by all agents
- No frontend: everything is backend API services communicating via HTTP.

##### README for Additional Insights
- Confirms the three‐agent pipeline (analysis, prediction, recommender) plus the orchestrator.
- Launch via `docker-compose up --build`.
- Each agent exposes its own FastAPI endpoint inside the Docker network.

##### Don’t Overthink—Be Thorough
– Capture each agent as a separate component.
– Show how they interconnect in the exact sequence defined by the orchestration pipeline.
– Include all architectural elements (Docker Compose, network, shared library, data store, final consumer) for a complete picture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure
    DockerCompose["Docker Compose Orchestration"]:::infra
    click DockerCompose "https://github.com/harrishphotos/sales-forecast-ai/blob/main/docker-compose.yml"

    %% Docker Network Boundary
    subgraph "Docker Network"
        direction TB

        %% Shared Library
        SharedModels["shared_models\n(package)"]:::package
        click SharedModels "https://github.com/harrishphotos/sales-forecast-ai/tree/main/shared_models/"

        %% Agents
        Orchestration["Orchestration Agent\n(pipeline_controller)"]:::agent
        click Orchestration "https://github.com/harrishphotos/sales-forecast-ai/tree/main/orchestration_agent/"

        Analysis["Historical Data Analyzer Agent"]:::agent
        click Analysis "https://github.com/harrishphotos/sales-forecast-ai/tree/main/analysis_agent/"

        Prediction["Forecast Generation Agent"]:::agent
        click Prediction "https://github.com/harrishphotos/sales-forecast-ai/tree/main/prediction_agent/"

        Recommender["Strategy Recommender Agent"]:::agent
        click Recommender "https://github.com/harrishphotos/sales-forecast-ai/tree/main/recommender_agent/"
    end

    %% External Systems
    DB[(Historical Sales DB)]:::database
    Client["Report Consumer (API Client)"]:::external

    %% Data Flow
    DB -->|GET data| Orchestration
    Orchestration -->|POST /analyze| Analysis
    Analysis -->|200 OK| Orchestration
    Orchestration -->|POST /predict| Prediction
    Prediction -->|200 OK| Orchestration
    Orchestration -->|POST /recommend| Recommender
    Recommender -->|200 OK| Orchestration
    Orchestration -->|generate report| Client

    %% Shared Models Dependency
    SharedModels -.-> Orchestration
    SharedModels -.-> Analysis
    SharedModels -.-> Prediction
    SharedModels -.-> Recommender

    %% Styling
    classDef agent fill:#FFE4B5,stroke:#D2691E,stroke-width:1px;
    classDef package fill:#FFFACD,stroke:#BDB76B,stroke-width:1px;
    classDef database fill:#E0FFFF,stroke:#5F9EA0,stroke-width:1px;
    classDef external fill:#F0FFF0,stroke:#228B22,stroke-width:1px;
    classDef infra fill:#F5F5F5,stroke:#A9A9A9,stroke-width:1px;
```
