# notmarializ/hsn_agent architecture

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

- Interactive diagram: https://gitdiagram.com/notmarializ/hsn_agent
- Repository: https://github.com/notmarializ/hsn_agent

## Overview

##### Project type and purpose
- Key indicators:
- A “hsn-frontend” directory suggests a client‐side UI.
- “agent” and “services” packages implement backend logic (webhook, fulfillment, data access, suggestion, validation).
- “app.yaml” and “Dockerfile” imply deployment on Google App Engine (or Cloud Run) in a container.
- A Google service‐account credential JSON hints at integration with Dialogflow or other GCP APIs.

##### File structure
Top-level items:
- Dockerfile / app.yaml – containerization and deployment configuration for GCP App Engine.
- main.py – entrypoint for the backend server (likely a Flask/FastAPI or Cloud Function wrapper).
- hsn-frontend/ – static or single‐page app (React/Angular/Vue) serving a UI.
- agent/ – webhook handler, fulfillment logic, and agent orchestration.
- services/ – domain services:
– data_service.py loads “resources/HSN_SAC.xlsx”
– suggester.py implements code‐recommendation logic
– validator.py checks code correctness
- models/ – data models for HSN codes and API response schemas.
- resources/ – source data (Excel file) for HSN codes.

##### README
- README only gives the project name. Conclude that the architectural details live in code and config.

a. Main components:
1. Frontend (hsn-frontend SPA)
2. Backend API (main.py)
3. Agent Layer (agent/webhook_handler.py, agent/fulfillment.py, agent/hsn_agent.py)
4. Domain Services (services/data_service, suggester, validator)
5. Data Store (resources/HSN_SAC.xlsx or an in-memory/disk cache)
6. External Services:
- Google Cloud App Engine / Cloud Run
- Google Dialogflow (if webhook)
b. Relationships & interactions:
- User → Frontend → Backend REST/GraphQL endpoints
- Backend → Agent Layer → Domain Services
- Data Service → Excel file (or transformed JSON)
- Agent Layer ↔ Dialogflow webhook (incoming POSTs, JSON payloads)
c. Architectural patterns & principles:
- Layered architecture (Presentation → API → Agent/Orchestration → Domain Services → Data)
- Separation of concerns: models, services, and fulfillment logic decoupled.
- Containerized deployment for portability.
d. Key technologies & frameworks:
- Python (Flask/FastAPI or Cloud Functions)
- Excel data processing (pandas or openpyxl in data_service)
- Dialogflow fulfillment webhook
- Frontend framework (e.g., React or Angular)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["HSN Frontend SPA"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        subgraph "API Layer"
            API["main.py (API Entry)"]:::backend
        end
        subgraph "Agent Layer"
            WH["Webhook Handler"]:::backend
            FL["Fulfillment Logic"]:::backend
            AG["HSN Agent Orchestration"]:::backend
        end
        subgraph "Domain Services"
            DS["Data Service"]:::backend
            SG["HSN Code Suggester"]:::backend
            VL["HSN Code Validator"]:::backend
        end
        subgraph "Models"
            M1["HSN Code Model"]:::backend
            M2["Response Schemas"]:::backend
        end
        subgraph "Data Store"
            DB["HSN_SAC.xlsx"]:::data
        end
    end

    %% Infrastructure & External Services
    subgraph "Infrastructure"
        DC["Dockerfile"]:::infra
        AY["app.yaml"]:::infra
        CR["Credentials JSON"]:::infra
    end
    GCP["Google App Engine / Cloud Run"]:::external
    DF["Dialogflow"]:::external

    %% Data Flows
    UI -->|"User Action"| API
    API -->|"Invoke Webhook"| WH
    DF -->|"Webhook POST"| WH
    WH -->|"Call Fulfillment"| FL
    FL -->|"Orchestrate"| AG
    AG -->|"Load/Validate/Suggest"| DS
    AG -->|"Load/Validate/Suggest"| SG
    AG -->|"Load/Validate/Suggest"| VL
    DS -->|"Read Excel"| DB
    SG -->|"Use Models"| M1
    VL -->|"Use Models"| M1
    FL -->|"Format Response"| M2

    %% Deployment
    DC -->|"Deploys"| GCP
    AY -->|"Configures"| GCP
    CR -->|"Auth For"| DF
    GCP -->|"Hosts"| API
    GCP -->|"Hosts"| UI

    %% Click Events
    click UI "https://github.com/notmarializ/hsn_agent/tree/main/hsn-frontend/"
    click API "https://github.com/notmarializ/hsn_agent/blob/main/main.py"
    click WH "https://github.com/notmarializ/hsn_agent/blob/main/agent/webhook_handler.py"
    click FL "https://github.com/notmarializ/hsn_agent/blob/main/agent/fulfillment.py"
    click AG "https://github.com/notmarializ/hsn_agent/blob/main/agent/hsn_agent.py"
    click DS "https://github.com/notmarializ/hsn_agent/blob/main/services/data_service.py"
    click SG "https://github.com/notmarializ/hsn_agent/blob/main/services/suggester.py"
    click VL "https://github.com/notmarializ/hsn_agent/blob/main/services/validator.py"
    click M1 "https://github.com/notmarializ/hsn_agent/blob/main/models/hsn_code.py"
    click M2 "https://github.com/notmarializ/hsn_agent/blob/main/models/responses.py"
    click DB "https://github.com/notmarializ/hsn_agent/blob/main/resources/HSN_SAC.xlsx"
    click DC "https://github.com/notmarializ/hsn_agent/tree/main/Dockerfile"
    click AY "https://github.com/notmarializ/hsn_agent/blob/main/app.yaml"
    click CR "https://github.com/notmarializ/hsn_agent/blob/main/agent/credentials/hsn-code-agent-461214-6108fd036969.json"

    %% Styling
    classDef frontend fill:#E3F2FD,stroke:#90CAF9
    classDef backend fill:#E8F5E9,stroke:#A5D6A7
    classDef data fill:#FFF3E0,stroke:#FFB74D
    classDef infra fill:#ECEFF1,stroke:#B0BEC5
    classDef external fill:#F5F5F5,stroke:#BDBDBD
```
