# 24f1000966/nexus-ai-ecommerce-analyst architecture

> Architecture diagram of the GitHub repository 24f1000966/nexus-ai-ecommerce-analyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/24f1000966/nexus-ai-ecommerce-analyst
- Repository: https://github.com/24f1000966/nexus-ai-ecommerce-analyst

## Overview

Nexus AI is a multi-tenant business-analysis platform. Companies register with identity and document details; a Super Admin reviews and approves them, after which company admins manage members and data and approved users query the analyst. The API is the runtime hub: it routes requests to role-specific services and scopes analytics to the caller’s tenant. The analyst combines SQL analytics, policy retrieval, charts, and optional LLM answer-writing. The README also documents admin audit/usage capabilities and a retained Streamlit analyst. Relationships are limited to source references and documented behavior; some unsampled page-to-endpoint details are not expanded.

Main entry points: [`frontend/src/api.js`](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/api.js) (API client), [`backend/main.py`](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/main.py) (API and analytics entry), [`app/agent.py`](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/agent.py) (Agent reasoning), [`backend/routers/auth.py`](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/auth.py) (Registration and login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Routes and shell<br/>[App.jsx]"]
  node_authctx["Session and roles<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_register["Company registration<br/>[RegisterPage.jsx]"]
  node_admin_ui["Company review<br/>[AdminPage.jsx]"]
  node_analyst_ui["Analyst dashboard<br/>[AnalystPage.jsx]"]
  node_team_ui["Team management<br/>[TeamPage.jsx]"]
  node_data_ui["Data workspace<br/>[DataPage.jsx]"]
  node_streamlit["Fallback analyst UI<br/>[streamlit_app.py]"]
end

subgraph group_identity["Identity and review"]
  node_auth_routes["Registration and login<br/>[auth.py]"]
  node_verification["Application checks<br/>[verification.py]"]
  node_security["JWT and access control<br/>[security.py]"]
  node_admin_routes["Review and audit<br/>[admin.py]"]
end

subgraph group_workspace["Company workspace"]
  node_company_routes["Membership service<br/>[company.py]"]
  node_data_routes["Uploads and documents<br/>[data.py]"]
  node_tenant["Tenant selection<br/>[tenant_data.py]"]
end

subgraph group_analysis["Data analyst"]
  node_api["API and analytics entry<br/>[main.py]"]
  node_agent["Agent reasoning<br/>[agent.py]"]
  node_rag["Policy retrieval<br/>[rag.py]"]
  node_charts["Chart generation<br/>[charts.py]"]
  node_llm["LLM provider adapter<br/>[llm_backend.py]"]
end

subgraph group_storage["Persistence"]
  node_analytics_db[("Tenant analytics store<br/>[db.py]")]
  node_platform_db[("Platform records<br/>[models.py]")]
  node_sql_session["Database sessions<br/>[database.py]"]
end

node_visitor(("Company users"))
node_owner(("Platform owner"))

node_visitor -->|"uses"| node_app
node_owner -->|"reviews"| node_app
node_app -->|"provides session"| node_authctx
node_authctx -->|"loads identity"| node_api_client
node_register -->|"submits application"| node_api_client
node_admin_ui -->|"requests review"| node_api_client
node_analyst_ui -->|"asks questions"| node_api_client
node_team_ui -->|"manages members"| node_api_client
node_data_ui -->|"manages data"| node_api_client
node_api_client -->|"calls auth endpoints"| node_auth_routes
node_api_client -->|"calls review endpoints"| node_admin_routes
node_api_client -->|"calls member endpoints"| node_company_routes
node_api_client -->|"calls data endpoints"| node_data_routes
node_auth_routes -->|"checks formats"| node_verification
node_auth_routes -->|"hashes and issues tokens"| node_security
node_admin_routes -->|"uses checks"| node_verification
node_admin_routes -->|"enforces roles"| node_security
node_company_routes -->|"enforces roles"| node_security
node_data_routes -->|"enforces roles"| node_security
node_api -->|"registers router"| node_auth_routes
node_api -->|"registers router"| node_admin_routes
node_api -->|"registers router"| node_company_routes
node_api -->|"registers router"| node_data_routes
node_api -->|"selects caller tenant"| node_tenant
node_api -->|"dispatches questions"| node_agent
node_agent -->|"queries data"| node_analytics_db
node_agent -->|"retrieves context"| node_rag
node_agent -->|"requests answer writing"| node_llm
node_agent -.->|"builds charts"| node_charts
node_tenant -->|"builds tenant data"| node_analytics_db
node_api -->|"logs questions"| node_platform_db
node_api -->|"opens sessions"| node_sql_session
node_sql_session -->|"persists records"| node_platform_db
node_streamlit -->|"uses analyst"| node_agent
node_streamlit -->|"uses charts"| node_charts

click node_app "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/auth/AuthContext.jsx"
click node_api_client "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/api.js"
click node_register "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/RegisterPage.jsx"
click node_admin_ui "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/AdminPage.jsx"
click node_analyst_ui "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/AnalystPage.jsx"
click node_team_ui "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/TeamPage.jsx"
click node_data_ui "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/DataPage.jsx"
click node_auth_routes "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/auth.py"
click node_verification "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/verification.py"
click node_security "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/security.py"
click node_admin_routes "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/admin.py"
click node_company_routes "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/company.py"
click node_data_routes "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/data.py"
click node_tenant "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/tenant_data.py"
click node_api "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/main.py"
click node_agent "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/agent.py"
click node_rag "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/rag.py"
click node_charts "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/charts.py"
click node_llm "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/llm_backend.py"
click node_analytics_db "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/db.py"
click node_platform_db "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/models.py"
click node_sql_session "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/database.py"
click node_streamlit "https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/streamlit_app.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_app,node_authctx,node_api_client,node_register,node_admin_ui,node_analyst_ui,node_team_ui,node_data_ui,node_streamlit,node_visitor toneBlue
class node_auth_routes,node_verification,node_security,node_admin_routes toneAmber
class node_company_routes,node_data_routes,node_tenant toneMint
class node_api,node_agent,node_rag,node_charts,node_llm toneRose
class node_analytics_db,node_platform_db,node_sql_session,node_owner toneIndigo
```

## Components

### Web application

- [Routes and shell](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session and roles](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/auth/AuthContext.jsx): `frontend/src/auth/AuthContext.jsx`
- [API client](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Company registration](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/RegisterPage.jsx): `frontend/src/pages/RegisterPage.jsx`
- [Company review](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/AdminPage.jsx): `frontend/src/pages/AdminPage.jsx`
- [Analyst dashboard](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/AnalystPage.jsx): `frontend/src/pages/AnalystPage.jsx`
- [Team management](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/TeamPage.jsx): `frontend/src/pages/TeamPage.jsx`
- [Data workspace](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/frontend/src/pages/DataPage.jsx): `frontend/src/pages/DataPage.jsx`
- [Fallback analyst UI](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/streamlit_app.py): `streamlit_app.py`

### Identity and review

- [Registration and login](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/auth.py): `backend/routers/auth.py`
- [Application checks](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/verification.py): `backend/verification.py`
- [JWT and access control](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/security.py): `backend/security.py`
- [Review and audit](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/admin.py): `backend/routers/admin.py`

### Company workspace

- [Membership service](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/company.py): `backend/routers/company.py`
- [Uploads and documents](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/routers/data.py): `backend/routers/data.py`
- [Tenant selection](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/tenant_data.py): `backend/tenant_data.py`

### Data analyst

- [API and analytics entry](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/main.py): `backend/main.py`
- [Agent reasoning](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/agent.py): `app/agent.py`
- [Policy retrieval](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/rag.py): `app/rag.py`
- [Chart generation](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/charts.py): `app/charts.py`
- [LLM provider adapter](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/llm_backend.py): `app/llm_backend.py`

### Persistence

- [Tenant analytics store](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/app/db.py): `app/db.py`
- [Platform records](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/models.py): `backend/models.py`
- [Database sessions](https://github.com/24f1000966/nexus-ai-ecommerce-analyst/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Company users**
- **Platform owner**

## Connections

- Company users → Routes and shell: uses
- Platform owner → Routes and shell: reviews
- Routes and shell → Session and roles: provides session (evidence: `frontend/src/App.jsx`)
- Session and roles → API client: loads identity (evidence: `frontend/src/auth/AuthContext.jsx`)
- Company registration → API client: submits application (evidence: `frontend/src/pages/RegisterPage.jsx`)
- Company review → API client: requests review (evidence: `frontend/src/pages/AdminPage.jsx`)
- Analyst dashboard → API client: asks questions (evidence: `frontend/src/pages/AnalystPage.jsx`)
- Team management → API client: manages members (evidence: `frontend/src/pages/TeamPage.jsx`)
- Data workspace → API client: manages data (evidence: `frontend/src/pages/DataPage.jsx`)
- API client → Registration and login: calls auth endpoints (evidence: `frontend/src/api.js`)
- API client → Review and audit: calls review endpoints (evidence: `frontend/src/api.js`)
- API client → Membership service: calls member endpoints (evidence: `frontend/src/api.js`)
- API client → Uploads and documents: calls data endpoints (evidence: `frontend/src/api.js`)
- Registration and login → Application checks: checks formats (evidence: `backend/routers/auth.py`)
- Registration and login → JWT and access control: hashes and issues tokens (evidence: `backend/routers/auth.py`)
- Review and audit → Application checks: uses checks (evidence: `backend/routers/admin.py`)
- Review and audit → JWT and access control: enforces roles (evidence: `backend/routers/admin.py`)
- Membership service → JWT and access control: enforces roles (evidence: `backend/routers/company.py`)
- Uploads and documents → JWT and access control: enforces roles (evidence: `backend/routers/data.py`)
- API and analytics entry → Registration and login: registers router (evidence: `backend/main.py`)
- API and analytics entry → Review and audit: registers router (evidence: `backend/main.py`)
- API and analytics entry → Membership service: registers router (evidence: `backend/main.py`)
- API and analytics entry → Uploads and documents: registers router (evidence: `backend/main.py`)
- API and analytics entry → Tenant selection: selects caller tenant (evidence: `backend/main.py`)
- API and analytics entry → Agent reasoning: dispatches questions (evidence: `backend/main.py`)
- Agent reasoning → Tenant analytics store: queries data (evidence: `app/agent.py`)
- Agent reasoning → Policy retrieval: retrieves context (evidence: `app/agent.py`)
- Agent reasoning → LLM provider adapter: requests answer writing (evidence: `app/agent.py`)
- Agent reasoning → Chart generation: builds charts
- Tenant selection → Tenant analytics store: builds tenant data (evidence: `backend/tenant_data.py`)
- API and analytics entry → Platform records: logs questions (evidence: `backend/main.py`)
- API and analytics entry → Database sessions: opens sessions (evidence: `backend/main.py`)
- Database sessions → Platform records: persists records (evidence: `backend/database.py`)
- Fallback analyst UI → Agent reasoning: uses analyst (evidence: `streamlit_app.py`)
- Fallback analyst UI → Chart generation: uses charts (evidence: `streamlit_app.py`)
