# anshika-singh002/faux-trading-arena architecture

> Architecture diagram of the GitHub repository anshika-singh002/faux-trading-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshika-singh002/faux-trading-arena
- Repository: https://github.com/anshika-singh002/faux-trading-arena

## Overview

Faux Trading is a virtual-money trading simulator with a Next.js client and modular FastAPI backend. The principal workflow is a user exploring simulated market data, placing server-validated trades, and viewing portfolio results; strategies, backtests, AI insights, learning, and rankings are additional product capabilities. Backend source excerpts establish several calls and persistence paths; other domains and frontend pages are represented from README and the source index, so their internal wiring is not asserted.

Main entry points: [`backend/app/main.py`](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/main.py) (API application), [`backend/app/modules/auth/router.py`](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/auth/router.py) (Authentication), [`backend/app/modules/trading/service.py`](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/trading/service.py) (Trade execution), [`backend/app/core/database.py`](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/database.py) (Database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Trading interface"]
  node_webapp["Trading pages"]
  node_authpages["Sign-in pages"]
  node_learning["Learning modules<br/>[page.tsx]"]
end

subgraph group_identity["Identity and accounts"]
  node_auth["Authentication<br/>[router.py]"]
  node_user_service["User service<br/>[service.py]"]
  node_users["User accounts<br/>[user.py]"]
end

subgraph group_markets["Market and trading"]
  node_market["Market data<br/>[router.py]"]
  node_trading_api["Trading API<br/>[router.py]"]
  node_trading_engine["Trade execution<br/>[service.py]"]
  node_orders["Orders<br/>[order.py]"]
  node_positions["Positions<br/>[position.py]"]
  node_portfolio["Portfolio<br/>[router.py]"]
  node_transactions["Trade history<br/>[transaction.py]"]
end

subgraph group_insights["Strategy and insights"]
  node_strategies["Strategy builder<br/>[router.py]"]
  node_backtesting["Backtesting<br/>[router.py]"]
  node_ai_api["AI insights API<br/>[router.py]"]
  node_ai_service["AI service<br/>[service.py]"]
  node_ml["ML predictions<br/>[ml_service.py]"]
  node_leaderboard["Leaderboard<br/>[router.py]"]
  node_notifications["Notifications<br/>[router.py]"]
end

subgraph group_platform["Backend foundation"]
  node_api["API application<br/>[main.py]"]
  node_database[("Database layer<br/>[database.py]")]
  node_security["Token security<br/>[security.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_trader(("Trader"))
node_external_market(("Market provider"))
node_store[("PostgreSQL")]

node_trader -.->|"signs in"| node_authpages
node_authpages -.->|"authenticates"| node_auth
node_trader -.->|"uses"| node_webapp
node_api -->|"mounts"| node_auth
node_api -->|"mounts"| node_market
node_api -->|"mounts"| node_trading_api
node_api -->|"mounts"| node_portfolio
node_api -->|"mounts"| node_strategies
node_api -->|"mounts"| node_backtesting
node_api -->|"mounts"| node_ai_api
node_api -->|"mounts"| node_leaderboard
node_api -->|"mounts"| node_notifications
node_api -->|"mounts"| node_users
node_api -->|"initializes"| node_database
node_auth -->|"calls"| node_user_service
node_auth -->|"uses tokens"| node_security
node_auth -->|"creates user"| node_users
node_security -->|"loads user"| node_user_service
node_trading_api -->|"delegates"| node_trading_engine
node_trading_engine -->|"records order"| node_orders
node_trading_engine -->|"updates position"| node_positions
node_trading_engine -->|"records fill"| node_transactions
node_portfolio -->|"reads"| node_positions
node_portfolio -->|"uses prices"| node_market
node_backtesting -->|"persists results"| node_database
node_ai_api -->|"uses"| node_ai_service
node_ai_service -->|"selects prediction"| node_ml
node_market -.->|"may replace simulation"| node_external_market
node_database -->|"stores records"| node_store
node_database -->|"reads settings"| node_config
node_webapp -.->|"offers learning"| node_learning

click node_webapp "https://github.com/anshika-singh002/faux-trading-arena/tree/main/frontend/src/app/(app)"
click node_authpages "https://github.com/anshika-singh002/faux-trading-arena/tree/main/frontend/src/app/(auth)"
click node_learning "https://github.com/anshika-singh002/faux-trading-arena/blob/main/frontend/src/app/(app)/learn/page.tsx"
click node_auth "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/auth/router.py"
click node_user_service "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/users/service.py"
click node_users "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/user.py"
click node_market "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/market_data/router.py"
click node_trading_api "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/trading/router.py"
click node_trading_engine "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/trading/service.py"
click node_orders "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/order.py"
click node_positions "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/position.py"
click node_portfolio "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/portfolio/router.py"
click node_transactions "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/transaction.py"
click node_strategies "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/strategies/router.py"
click node_backtesting "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/backtesting/router.py"
click node_ai_api "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/router.py"
click node_ai_service "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/service.py"
click node_ml "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/ml_service.py"
click node_leaderboard "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/leaderboard/router.py"
click node_notifications "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/notifications/router.py"
click node_api "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/main.py"
click node_database "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/database.py"
click node_security "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/security.py"
click node_config "https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/config.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_webapp,node_authpages,node_learning toneBlue
class node_auth,node_user_service,node_users,node_store toneAmber
class node_market,node_trading_api,node_trading_engine,node_orders,node_positions,node_portfolio,node_transactions toneMint
class node_strategies,node_backtesting,node_ai_api,node_ai_service,node_ml,node_leaderboard,node_notifications toneRose
class node_api,node_database,node_security,node_config,node_trader,node_external_market toneIndigo
```

## Components

### Trading interface

- [Trading pages](https://github.com/anshika-singh002/faux-trading-arena/tree/main/frontend/src/app/(app)): `frontend/src/app/(app)`
- [Sign-in pages](https://github.com/anshika-singh002/faux-trading-arena/tree/main/frontend/src/app/(auth)): `frontend/src/app/(auth)`
- [Learning modules](https://github.com/anshika-singh002/faux-trading-arena/blob/main/frontend/src/app/(app)/learn/page.tsx): `frontend/src/app/(app)/learn/page.tsx`

### Identity and accounts

- [Authentication](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/auth/router.py): `backend/app/modules/auth/router.py`
- [User service](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/users/service.py): `backend/app/modules/users/service.py`
- [User accounts](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/user.py): `backend/app/models/user.py`

### Market and trading

- [Market data](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/market_data/router.py): `backend/app/modules/market_data/router.py`
- [Trading API](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/trading/router.py): `backend/app/modules/trading/router.py`
- [Trade execution](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/trading/service.py): `backend/app/modules/trading/service.py`
- [Orders](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/order.py): `backend/app/models/order.py`
- [Positions](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/position.py): `backend/app/models/position.py`
- [Portfolio](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/portfolio/router.py): `backend/app/modules/portfolio/router.py`
- [Trade history](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/models/transaction.py): `backend/app/models/transaction.py`

### Strategy and insights

- [Strategy builder](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/strategies/router.py): `backend/app/modules/strategies/router.py`
- [Backtesting](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/backtesting/router.py): `backend/app/modules/backtesting/router.py`
- [AI insights API](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/router.py): `backend/app/modules/ai/router.py`
- [AI service](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/service.py): `backend/app/modules/ai/service.py`
- [ML predictions](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/ai/ml_service.py): `backend/app/modules/ai/ml_service.py`
- [Leaderboard](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/leaderboard/router.py): `backend/app/modules/leaderboard/router.py`
- [Notifications](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/modules/notifications/router.py): `backend/app/modules/notifications/router.py`

### Backend foundation

- [API application](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/main.py): `backend/app/main.py`
- [Database layer](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Token security](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Configuration](https://github.com/anshika-singh002/faux-trading-arena/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Trader**
- **Market provider**
- **PostgreSQL**

## Connections

- Trader → Sign-in pages: signs in (evidence: `README.md`)
- Sign-in pages → Authentication: authenticates (evidence: `README.md`)
- Trader → Trading pages: uses (evidence: `README.md`)
- API application → Authentication: mounts (evidence: `backend/app/main.py`)
- API application → Market data: mounts (evidence: `backend/app/main.py`)
- API application → Trading API: mounts (evidence: `backend/app/main.py`)
- API application → Portfolio: mounts (evidence: `backend/app/main.py`)
- API application → Strategy builder: mounts (evidence: `backend/app/main.py`)
- API application → Backtesting: mounts (evidence: `backend/app/main.py`)
- API application → AI insights API: mounts (evidence: `backend/app/main.py`)
- API application → Leaderboard: mounts (evidence: `backend/app/main.py`)
- API application → Notifications: mounts (evidence: `backend/app/main.py`)
- API application → User accounts: mounts (evidence: `backend/app/main.py`)
- API application → Database layer: initializes (evidence: `backend/app/main.py`)
- Authentication → User service: calls (evidence: `backend/app/modules/auth/router.py`)
- Authentication → Token security: uses tokens (evidence: `backend/app/modules/auth/router.py`)
- Authentication → User accounts: creates user (evidence: `backend/app/modules/auth/router.py`)
- Token security → User service: loads user (evidence: `backend/app/core/security.py`)
- Trading API → Trade execution: delegates (evidence: `backend/app/modules/trading/router.py`)
- Trade execution → Orders: records order (evidence: `backend/app/modules/trading/service.py`)
- Trade execution → Positions: updates position (evidence: `backend/app/modules/trading/service.py`)
- Trade execution → Trade history: records fill (evidence: `backend/app/modules/trading/service.py`)
- Portfolio → Positions: reads (evidence: `backend/app/modules/portfolio/router.py`)
- Portfolio → Market data: uses prices (evidence: `backend/app/modules/portfolio/router.py`)
- Backtesting → Database layer: persists results (evidence: `backend/app/modules/backtesting/router.py`)
- AI insights API → AI service: uses (evidence: `backend/app/modules/ai/router.py`)
- AI service → ML predictions: selects prediction (evidence: `backend/app/modules/ai/service.py`)
- Market data → Market provider: may replace simulation (evidence: `backend/app/modules/market_data/router.py`)
- Database layer → PostgreSQL: stores records (evidence: `backend/app/core/database.py`)
- Database layer → Configuration: reads settings (evidence: `backend/app/core/database.py`)
- Trading pages → Learning modules: offers learning (evidence: `README.md`)
