# chintan616/arthayukti architecture

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

- Interactive diagram: https://gitdiagram.com/chintan616/arthayukti
- Repository: https://github.com/chintan616/arthayukti

## Overview

1. **Overall shape**
   - ArthaYukti is a three-tier distributed app: a React frontend, a Node.js/Express backend, and a separate Python AI service.
   - The main architectural boundary is between the high-throughput trading/API server and the CPU/LLM-heavy AI microservice.

2. **Frontend client**
   - The `client` folder is a Vite + React single-page app.
   - It uses Redux Toolkit for application state, React Context for auth, Socket.IO client hooks for live updates, and page-level routing for the major product areas.
   - Key UI surfaces map to business domains: dashboard, stocks/market, portfolio, wallet, watchlist, alerts, login/signup, and the AI analyst view.

3. **Client-to-backend interaction**
   - The frontend talks to the Node API through a dedicated Axios layer and to the realtime socket layer through a separate socket client.
   - Authentication is enforced on the client with protected routes and shared auth state, so the SPA acts as a thin presentation layer over server-owned business logic.

4. **Node.js application server**
   - The `server` folder is the core transactional backend, built with Express and MongoDB/Mongoose.
   - Its API is organized by domain controllers and routes: auth, stocks, portfolio, wallet, watchlist, alerts, and chat.
   - This server owns request validation, auth/session handling, trading actions, wallet mutations, and persistence of user-facing application state.

5. **Data model and domain boundaries**
   - MongoDB models separate the main business aggregates: `User`, `Portfolio`, `Transaction`, `WalletTransaction`, `Watchlist`, `Alert`, and `ChatThread`.
   - This separation suggests a domain-oriented design where trading, wallet operations, and conversational AI history are tracked independently but linked through user identity.

6. **Realtime market and event delivery**
   - Socket.IO is used on the Node side to push live market-related updates to connected clients.
   - The server also contains a `stockService`, a `cacheService`, and a `proto/MarketDataFeed.proto`, indicating a dedicated market-data ingestion or normalization path separate from standard REST requests.

7. **External integrations in the Node backend**
   - The Node backend is the integration point for live market data and payment simulation.
   - It connects to Upstox for market prices/feeds, Razorpay test mode for virtual wallet top-ups, Google OAuth for login, and Redis for rate limiting and API-call reduction.
   - Redis is an operational dependency rather than a business datastore; it supports throughput and external API protection.

8. **AI microservice**
   - The `ai-service` directory is a separate Python service, likely FastAPI-based as described in the README, dedicated to AI and forecasting workloads.
   - Its files (`agent.py`, `predict.py`, `report.py`, `main.py`) imply three AI capabilities: conversational analysis, stock-price forecasting, and generated reports/insights.
   - This service is intentionally isolated from the Node server to keep LLM and time-series work off the transactional path.

9. **AI service inputs and outputs**
   - The AI service appears to pull portfolio/context data from MongoDB and combine it with external intelligence sources such as Groq and NewsData.
   - The frontend’s AI analyst page likely calls this service directly for streaming or report generation, rather than going through the Node API for every AI request.
   - The result is a separate request path for AI queries, distinct from trading and account management.

10. **Chat and AI history**
   - The Node backend includes a chat controller and `ChatThread` model, which suggests the conversational layer is persisted server-side.
   - That gives the system a durable AI interaction history while allowing the Python service to stay stateless or lightly stateful.

11. **Operational packaging**
   - `docker-compose.yml` coordinates local execution of the Node API, Python AI service, and Redis.
   - Both backend services also have their own Dockerfiles, which reinforces the microservice boundary and independent deployment model.

12. **Deployment boundary**
   - The README indicates the frontend is deployed separately on Vercel, while the Node API and Python AI API are deployed as separate web services.
   - That means the diagram should show three independently deployable runtime units, with shared persistence in MongoDB and shared infrastructure support from Redis.

13. **Primary data flow**
   - User actions start in the React SPA, go either to the Node API for trading/account operations or to the Python service for AI analysis, and then persist into MongoDB.
   - Live market data arrives from external providers into the backend, then fans out to clients over sockets and updates the relevant stored state.

14. **What to emphasize in an architecture diagram**
   - Show clear separation between presentation, transactional backend, AI backend, and infrastructure dependencies.
   - Highlight MongoDB as the main system of record, Redis as operational cache/rate-limit support, and external services as side integrations rather than core components.

Main entry points: [`client/src/App.jsx`](https://github.com/chintan616/arthayukti/blob/main/client/src/App.jsx) (App shell), [`server/server.js`](https://github.com/chintan616/arthayukti/blob/main/server/server.js) (Express server), [`client/src/api/axios.js`](https://github.com/chintan616/arthayukti/blob/main/client/src/api/axios.js) (API client), [`ai-service/main.py`](https://github.com/chintan616/arthayukti/blob/main/ai-service/main.py) (AI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_client_app["App shell<br/>react entry<br/>[App.jsx]"]
  node_client_main["Main entry<br/>react bootstrap<br/>[main.jsx]"]
  node_client_api["API client<br/>axios layer<br/>[axios.js]"]
  node_client_auth["Auth context<br/>auth state<br/>[AuthContext.jsx]"]
  node_client_store["Redux store<br/>state store<br/>[index.js]"]
  node_client_socket["Socket client<br/>realtime client<br/>[socketClient.js]"]
  node_client_protected["Protected route<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_client_dash["Dashboard<br/>page<br/>[DashboardPage.jsx]"]
  node_client_market["Market<br/>page<br/>[MarketPage.jsx]"]
  node_client_portfolio["Portfolio<br/>page<br/>[PortfolioPage.jsx]"]
  node_client_wallet["Wallet<br/>page<br/>[WalletPage.jsx]"]
  node_client_watchlist["Watchlist<br/>page<br/>[WatchlistPage.jsx]"]
  node_client_ai["AI analyst<br/>page<br/>[AiAnalystPage.jsx]"]
end

subgraph group_server["Node API"]
  node_server_api["Express server<br/>api host<br/>[server.js]"]
  node_server_auth["Auth routes<br/>http routes<br/>[authRoutes.js]"]
  node_server_stock["Stock service<br/>market domain<br/>[stockService.js]"]
  node_server_chat["Chat controller<br/>ai history<br/>[chatController.js]"]
  node_server_socket["Socket hub<br/>realtime server<br/>[index.js]"]
  node_server_cache["Cache service<br/>cache/rate-limit<br/>[cacheService.js]"]
  node_server_db["Database config<br/>db connector<br/>[db.js]"]
end

subgraph group_ai["AI Service"]
  node_ai_main["AI API<br/>python app<br/>[main.py]"]
  node_ai_agent["Agent<br/>llm workflow<br/>[agent.py]"]
  node_ai_predict["Predictor<br/>forecasting<br/>[predict.py]"]
  node_ai_report["Reports<br/>insights generation<br/>[report.py]"]
end

subgraph group_infra["Data and integrations"]
  node_db_mongo[("MongoDB<br/>system of record")]
  node_cache_redis[("Redis<br/>operational cache")]
  node_ext_upstox(("Upstox<br/>market feed"))
  node_ext_razorpay(("Razorpay<br/>payments sandbox"))
  node_ext_google(("Google OAuth<br/>identity provider"))
  node_ext_groq(("Groq / NewsData<br/>ai intel"))
end

node_client_main -->|"boots"| node_client_app
node_client_app -->|"provides"| node_client_auth
node_client_app -->|"provides"| node_client_store
node_client_app -->|"uses"| node_client_protected
node_client_app -->|"routes to"| node_client_dash
node_client_app -->|"routes to"| node_client_market
node_client_app -->|"routes to"| node_client_portfolio
node_client_app -->|"routes to"| node_client_wallet
node_client_app -->|"routes to"| node_client_watchlist
node_client_app -->|"routes to"| node_client_ai
node_client_dash -->|"calls"| node_client_api
node_client_market -->|"calls"| node_client_api
node_client_portfolio -->|"calls"| node_client_api
node_client_wallet -->|"calls"| node_client_api
node_client_watchlist -->|"calls"| node_client_api
node_client_ai -->|"calls"| node_ai_main
node_client_socket -->|"connects"| node_server_socket
node_client_api -->|"requests"| node_server_api
node_server_api -->|"mounts"| node_server_auth
node_server_api -->|"mounts"| node_server_stock
node_server_api -->|"mounts"| node_server_chat
node_server_api -->|"hosts"| node_server_socket
node_server_stock -->|"uses"| node_server_cache
node_server_stock -->|"integrates with"| node_ext_upstox
node_server_api -->|"integrates with"| node_ext_google
node_server_api -->|"integrates with"| node_ext_razorpay
node_server_api -->|"persists to"| node_db_mongo
node_server_chat -->|"persists to"| node_db_mongo
node_server_db -->|"connects"| node_db_mongo
node_server_cache -->|"uses"| node_cache_redis
node_ai_main -->|"orchestrates"| node_ai_agent
node_ai_main -->|"orchestrates"| node_ai_predict
node_ai_main -->|"orchestrates"| node_ai_report
node_ai_agent -->|"reads context"| node_db_mongo
node_ai_predict -->|"reads context"| node_db_mongo
node_ai_report -->|"uses"| node_ext_groq
node_ai_predict -->|"uses"| node_ext_groq

click node_client_app "https://github.com/chintan616/arthayukti/blob/main/client/src/App.jsx"
click node_client_main "https://github.com/chintan616/arthayukti/blob/main/client/src/main.jsx"
click node_client_api "https://github.com/chintan616/arthayukti/blob/main/client/src/api/axios.js"
click node_client_auth "https://github.com/chintan616/arthayukti/blob/main/client/src/context/AuthContext.jsx"
click node_client_store "https://github.com/chintan616/arthayukti/blob/main/client/src/store/index.js"
click node_client_socket "https://github.com/chintan616/arthayukti/blob/main/client/src/sockets/socketClient.js"
click node_client_protected "https://github.com/chintan616/arthayukti/blob/main/client/src/components/ProtectedRoute.jsx"
click node_client_dash "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/DashboardPage.jsx"
click node_client_market "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/MarketPage.jsx"
click node_client_portfolio "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/PortfolioPage.jsx"
click node_client_wallet "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/WalletPage.jsx"
click node_client_watchlist "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/WatchlistPage.jsx"
click node_client_ai "https://github.com/chintan616/arthayukti/blob/main/client/src/pages/AiAnalystPage.jsx"
click node_server_api "https://github.com/chintan616/arthayukti/blob/main/server/server.js"
click node_server_auth "https://github.com/chintan616/arthayukti/blob/main/server/routes/authRoutes.js"
click node_server_stock "https://github.com/chintan616/arthayukti/blob/main/server/services/stockService.js"
click node_server_chat "https://github.com/chintan616/arthayukti/blob/main/server/controllers/chatController.js"
click node_server_socket "https://github.com/chintan616/arthayukti/blob/main/server/sockets/index.js"
click node_server_cache "https://github.com/chintan616/arthayukti/blob/main/server/services/cacheService.js"
click node_server_db "https://github.com/chintan616/arthayukti/blob/main/server/config/db.js"
click node_ai_main "https://github.com/chintan616/arthayukti/blob/main/ai-service/main.py"
click node_ai_agent "https://github.com/chintan616/arthayukti/blob/main/ai-service/agent.py"
click node_ai_predict "https://github.com/chintan616/arthayukti/blob/main/ai-service/predict.py"
click node_ai_report "https://github.com/chintan616/arthayukti/blob/main/ai-service/report.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_client_app,node_client_main,node_client_api,node_client_auth,node_client_store,node_client_socket,node_client_protected,node_client_dash,node_client_market,node_client_portfolio,node_client_wallet,node_client_watchlist,node_client_ai toneBlue
class node_server_api,node_server_auth,node_server_stock,node_server_chat,node_server_socket,node_server_cache,node_server_db toneAmber
class node_ai_main,node_ai_agent,node_ai_predict,node_ai_report toneMint
class node_db_mongo,node_cache_redis,node_ext_upstox,node_ext_razorpay,node_ext_google,node_ext_groq toneRose
```

## Components

### React SPA

Vite + React presentation layer

- [App shell](https://github.com/chintan616/arthayukti/blob/main/client/src/App.jsx): react entry · Bootstraps routing, layouts, and providers · `client/src/App.jsx`
- [Main entry](https://github.com/chintan616/arthayukti/blob/main/client/src/main.jsx): react bootstrap · Mounts the SPA into the browser · `client/src/main.jsx`
- [API client](https://github.com/chintan616/arthayukti/blob/main/client/src/api/axios.js): axios layer · Dedicated HTTP client for backend calls · `client/src/api/axios.js`
- [Auth context](https://github.com/chintan616/arthayukti/blob/main/client/src/context/AuthContext.jsx): auth state · Client-side identity and session state · `client/src/context/AuthContext.jsx`
- [Redux store](https://github.com/chintan616/arthayukti/blob/main/client/src/store/index.js): state store · Global application state container · `client/src/store/index.js`
- [Socket client](https://github.com/chintan616/arthayukti/blob/main/client/src/sockets/socketClient.js): realtime client · Browser connection for live updates · `client/src/sockets/socketClient.js`
- [Protected route](https://github.com/chintan616/arthayukti/blob/main/client/src/components/ProtectedRoute.jsx): route guard · Blocks unauthenticated access to private views · `client/src/components/ProtectedRoute.jsx`
- [Dashboard](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/DashboardPage.jsx): page · Overview landing for logged-in users · `client/src/pages/DashboardPage.jsx`
- [Market](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/MarketPage.jsx): page · Stocks and market browsing surface · `client/src/pages/MarketPage.jsx`
- [Portfolio](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/PortfolioPage.jsx): page · Holdings and performance view · `client/src/pages/PortfolioPage.jsx`
- [Wallet](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/WalletPage.jsx): page · Balance and top-up flows · `client/src/pages/WalletPage.jsx`
- [Watchlist](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/WatchlistPage.jsx): page · Tracked instruments and alerts surface · `client/src/pages/WatchlistPage.jsx`
- [AI analyst](https://github.com/chintan616/arthayukti/blob/main/client/src/pages/AiAnalystPage.jsx): page · User-facing AI analysis and reports · `client/src/pages/AiAnalystPage.jsx`

### Node API

Express transactional backend

- [Express server](https://github.com/chintan616/arthayukti/blob/main/server/server.js): api host · Primary HTTP entrypoint and runtime orchestrator · `server/server.js`
- [Auth routes](https://github.com/chintan616/arthayukti/blob/main/server/routes/authRoutes.js): http routes · Login, signup, and OAuth endpoints · `server/routes/authRoutes.js`
- [Stock service](https://github.com/chintan616/arthayukti/blob/main/server/services/stockService.js): market domain · Market data, trading, and price orchestration · `server/services/stockService.js`
- [Chat controller](https://github.com/chintan616/arthayukti/blob/main/server/controllers/chatController.js): ai history · Persists and serves conversational thread data · `server/controllers/chatController.js`
- [Socket hub](https://github.com/chintan616/arthayukti/blob/main/server/sockets/index.js): realtime server · Broadcasts live market events to clients · `server/sockets/index.js`
- [Cache service](https://github.com/chintan616/arthayukti/blob/main/server/services/cacheService.js): cache/rate-limit · Operational caching and request reduction · `server/services/cacheService.js`
- [Database config](https://github.com/chintan616/arthayukti/blob/main/server/config/db.js): db connector · MongoDB connection bootstrap · `server/config/db.js`

### AI Service

Python service for analysis and forecasting

- [AI API](https://github.com/chintan616/arthayukti/blob/main/ai-service/main.py): python app · Python service entrypoint · `ai-service/main.py`
- [Agent](https://github.com/chintan616/arthayukti/blob/main/ai-service/agent.py): llm workflow · Conversational analysis and orchestration · `ai-service/agent.py`
- [Predictor](https://github.com/chintan616/arthayukti/blob/main/ai-service/predict.py): forecasting · Stock forecasting and time-series inference · `ai-service/predict.py`
- [Reports](https://github.com/chintan616/arthayukti/blob/main/ai-service/report.py): insights generation · Generated summaries and AI reports · `ai-service/report.py`

### Data and integrations

Shared storage, cache, and external providers

- **MongoDB**: system of record · Persistent business state and history
- **Redis**: operational cache · Rate limiting and API-call reduction
- **Upstox**: market feed · External market data and pricing source
- **Razorpay**: payments sandbox · Virtual wallet top-up integration
- **Google OAuth**: identity provider · Third-party sign-in integration
- **Groq / NewsData**: ai intel · External intelligence sources for AI outputs

## Connections

- Main entry → App shell: boots · Browser entry mounts the application shell
- App shell → Auth context: provides · Auth state is shared across the SPA
- App shell → Redux store: provides · Redux store powers global state
- App shell → Protected route: uses · Private routes are wrapped by auth guards
- App shell → Dashboard: routes to · Dashboard is a main authenticated surface
- App shell → Market: routes to · Market browsing surface
- App shell → Portfolio: routes to · Portfolio surface
- App shell → Wallet: routes to · Wallet surface
- App shell → Watchlist: routes to · Watchlist surface
- App shell → AI analyst: routes to · AI analyst surface
- Dashboard → API client: calls · Dashboard fetches backend data
- Market → API client: calls · Market pages use REST APIs
- Portfolio → API client: calls · Portfolio data comes from Node API
- Wallet → API client: calls · Wallet mutations go through the API client
- Watchlist → API client: calls · Watchlist operations use REST APIs
- AI analyst → AI API: calls · AI page can talk directly to the AI service
- Socket client → Socket hub: connects · Browser subscribes to live updates
- API client → Express server: requests · Main HTTP path for application features
- Express server → Auth routes: mounts · Auth endpoints are registered in the server
- Express server → Stock service: mounts · Market and trading logic
- Express server → Chat controller: mounts · Chat and AI-history endpoints
- Express server → Socket hub: hosts · Realtime server is attached to the Node app
- Stock service → Cache service: uses · Protects external market calls and throughput
- Stock service → Upstox: integrates with · Consumes live market data feeds
- Express server → Google OAuth: integrates with · OAuth login provider
- Express server → Razorpay: integrates with · Virtual wallet top-up flow
- Express server → MongoDB: persists to · Primary application state store
- Chat controller → MongoDB: persists to · Conversation history is stored in MongoDB
- Database config → MongoDB: connects · MongoDB connection bootstrap
- Cache service → Redis: uses · Redis backs cache and rate-limiting
- AI API → Agent: orchestrates · Entrypoint routes conversational requests
- AI API → Predictor: orchestrates · Entrypoint exposes forecasting work
- AI API → Reports: orchestrates · Entrypoint exposes report generation
- Agent → MongoDB: reads context · Uses portfolio and chat context
- Predictor → MongoDB: reads context · Consumes stored market and portfolio history
- Reports → Groq / NewsData: uses · Generates insights from external intelligence
- Predictor → Groq / NewsData: uses · Forecasting is informed by external AI/intel sources
