# ahmed-ali-313/super-store-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed-ali-313/super-store-agent
- Repository: https://github.com/ahmed-ali-313/super-store-agent

## Overview

SuperStore AI supports customer product discovery and administrator inventory operations through role-specific chat, alongside account registration and login. Customers can browse categories, search products, check prices, stock, and locations; administrators can inspect inventory, identify low stock, and change or create catalog entries. The frontend sends requests to FastAPI, which delegates chat and account work to routes, agents, and persistence. README capabilities supplement the sampled excerpts; exact internal wiring for unsampled routes and tools is not shown.

Main entry points: [`frontend/src/main.jsx`](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/main.jsx) (React application), [`src/database.py`](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/database.py) (Database sessions), [`frontend/src/api.js`](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/api.js) (API client), [`src/api/main.py`](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["React application<br/>[main.jsx]"]
  node_customer_ui["Customer browsing and chat<br/>[CustomerChat.jsx]"]
  node_category_ui["Category browsing<br/>[CategoryPage.jsx]"]
  node_admin_ui["Admin chat and tools<br/>[AdminChat.jsx]"]
  node_auth_ui["Login and registration<br/>[AuthContext.jsx]"]
  node_voice["Voice input<br/>[VoiceInput.jsx]"]
  node_voice_fix["Voice autocorrect"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_auth_logic["Account and sessions<br/>[auth.py]"]
end

subgraph group_agents["Conversational agents"]
  node_customer_agent["Customer agent<br/>[customer.py]"]
  node_admin_agent["Admin agent<br/>[admin.py]"]
  node_tools["Product operations<br/>[tools.py]"]
end

subgraph group_state["Persistence"]
  node_database_layer["Database sessions<br/>[database.py]"]
  node_models["ORM models<br/>[models.py]"]
end

node_shopper(("Shopper or admin"))
node_llm(("Gemini or OpenAI"))
node_mysql[("MySQL database")]

node_shopper -->|"uses"| node_web
node_web -->|"routes customers"| node_customer_ui
node_web -->|"routes categories"| node_category_ui
node_web -->|"routes admins"| node_admin_ui
node_web -->|"provides auth"| node_auth_ui
node_customer_ui -->|"requests chat"| node_api_client
node_category_ui -->|"requests products"| node_api_client
node_admin_ui -->|"requests admin"| node_api_client
node_auth_ui -->|"requests auth"| node_api_client
node_admin_ui -->|"captures speech"| node_voice
node_voice -->|"corrects transcript"| node_voice_fix
node_fastapi -->|"mounts router"| node_auth_routes
node_fastapi -->|"mounts router"| node_chat_routes
node_fastapi -->|"mounts router"| node_admin_routes
node_auth_routes -->|"registers and logs in"| node_auth_logic
node_auth_routes -->|"gets sessions"| node_auth_logic
node_chat_routes -->|"handles customer chat"| node_customer_agent
node_admin_routes -->|"handles admin chat"| node_admin_agent
node_customer_agent -->|"uses product tools"| node_tools
node_admin_agent -->|"uses inventory tools"| node_tools
node_customer_agent -->|"runs model"| node_llm
node_admin_agent -->|"runs model"| node_llm
node_tools -->|"reads and updates"| node_database_layer
node_auth_logic -->|"reads and writes"| node_database_layer
node_database_layer -->|"maps records"| node_models
node_database_layer -->|"persists data"| node_mysql

click node_web "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/main.jsx"
click node_customer_ui "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/CustomerChat.jsx"
click node_category_ui "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/CategoryPage.jsx"
click node_admin_ui "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/AdminChat.jsx"
click node_auth_ui "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/context/AuthContext.jsx"
click node_voice "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/components/VoiceInput.jsx"
click node_voice_fix "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/utils/voiceAutocorrect.js"
click node_api_client "https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/api.js"
click node_fastapi "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/main.py"
click node_auth_routes "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/auth.py"
click node_chat_routes "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/chat.py"
click node_admin_routes "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/admin.py"
click node_auth_logic "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/auth.py"
click node_customer_agent "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/agents/customer.py"
click node_admin_agent "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/agents/admin.py"
click node_tools "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/tools.py"
click node_database_layer "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/database.py"
click node_models "https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/models.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_web,node_customer_ui,node_category_ui,node_admin_ui,node_auth_ui,node_voice,node_voice_fix,node_api_client toneBlue
class node_fastapi,node_auth_routes,node_chat_routes,node_admin_routes,node_auth_logic,node_mysql toneAmber
class node_customer_agent,node_admin_agent,node_tools toneMint
class node_database_layer,node_models toneRose
class node_shopper,node_llm toneIndigo
```

## Components

### Web application

- [React application](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Customer browsing and chat](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/CustomerChat.jsx): `frontend/src/routes/CustomerChat.jsx`
- [Category browsing](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/CategoryPage.jsx): `frontend/src/routes/CategoryPage.jsx`
- [Admin chat and tools](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/routes/AdminChat.jsx): `frontend/src/routes/AdminChat.jsx`
- [Login and registration](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Voice input](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/components/VoiceInput.jsx): `frontend/src/components/VoiceInput.jsx`
- [Voice autocorrect](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/utils/voiceAutocorrect.js): `frontend/src/utils/voiceAutocorrect.js`
- [API client](https://github.com/ahmed-ali-313/super-store-agent/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and access

- [FastAPI application](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/main.py): `src/api/main.py`
- [Authentication routes](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/auth.py): `src/api/routes/auth.py`
- [Chat routes](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/chat.py): `src/api/routes/chat.py`
- [Admin routes](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/api/routes/admin.py): `src/api/routes/admin.py`
- [Account and sessions](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/auth.py): `src/auth.py`

### Conversational agents

- [Customer agent](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/agents/customer.py): `src/agents/customer.py`
- [Admin agent](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/agents/admin.py): `src/agents/admin.py`
- [Product operations](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/tools.py): `src/tools.py`

### Persistence

- [Database sessions](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/database.py): `src/database.py`
- [ORM models](https://github.com/ahmed-ali-313/super-store-agent/blob/main/src/models.py): `src/models.py`

### Other components

- **Shopper or admin**
- **Gemini or OpenAI**
- **MySQL database**

## Connections

- Shopper or admin → React application: uses
- React application → Customer browsing and chat: routes customers
- React application → Category browsing: routes categories
- React application → Admin chat and tools: routes admins
- React application → Login and registration: provides auth
- Customer browsing and chat → API client: requests chat
- Category browsing → API client: requests products
- Admin chat and tools → API client: requests admin
- Login and registration → API client: requests auth
- Admin chat and tools → Voice input: captures speech
- Voice input → Voice autocorrect: corrects transcript
- FastAPI application → Authentication routes: mounts router
- FastAPI application → Chat routes: mounts router
- FastAPI application → Admin routes: mounts router
- Authentication routes → Account and sessions: registers and logs in
- Authentication routes → Account and sessions: gets sessions
- Chat routes → Customer agent: handles customer chat
- Admin routes → Admin agent: handles admin chat
- Customer agent → Product operations: uses product tools
- Admin agent → Product operations: uses inventory tools
- Customer agent → Gemini or OpenAI: runs model
- Admin agent → Gemini or OpenAI: runs model
- Product operations → Database sessions: reads and updates
- Account and sessions → Database sessions: reads and writes
- Database sessions → ORM models: maps records
- Database sessions → MySQL database: persists data