Monorepo Structure

Nexgent is organized as a pnpm workspace monorepo with three packages that share code through the nexgent-open-source-trading-engine/shared package.

Package Overview

Package	Description	Main Technologies
`nexgent-open-source-trading-engine/backend`	Trading engine, API server, WebSocket server	Express, Prisma, Redis, BullMQ
`nexgent-open-source-trading-engine/frontend`	Dashboard UI with real-time updates	Next.js 15, React Query, WebSocket
`nexgent-open-source-trading-engine/shared`	Shared types, validators, utilities	TypeScript, Zod

Root Directory Structure

package.json
pnpm-workspace.yaml
docker-compose.yml
railway.json
tsconfig.json

Backend Package (`nexgent-open-source-trading-engine/backend`)

The backend follows a layered architecture inspired by Domain-Driven Design (DDD).

packages/backend/
├── src/
│   ├── api/                    # API Layer
│   │   ├── index.ts            # Route aggregator
│   │   └── v1/                 # Versioned API routes
│   │       ├── agents/         # Agent CRUD + config
│   │       ├── auth/           # Login, register, tokens
│   │       ├── trading-signals/# Signal management
│   │       ├── wallets/        # Wallet assignment
│   │       ├── health/         # Health checks
│   │       └── ...
│   │
│   ├── domain/                 # Domain Layer (Business Logic)
│   │   ├── agents/             # Agent service & repository
│   │   ├── balances/           # Balance tracking & snapshots
│   │   ├── positions/          # Position repository
│   │   ├── prices/             # Price update manager
│   │   ├── signals/            # Signal processor & eligibility
│   │   ├── trading/            # Trading executor, stop loss, DCA
│   │   └── wallets/            # Wallet reset service
│   │
│   ├── infrastructure/         # Infrastructure Layer
│   │   ├── cache/              # Redis services
│   │   ├── database/           # Prisma client & repositories
│   │   ├── external/           # External API integrations
│   │   │   ├── jupiter/        # Jupiter Aggregator
│   │   │   ├── pyth/           # Pyth price feeds
│   │   │   ├── dexscreener/    # DexScreener prices
│   │   │   └── solana/         # Solana Web3.js
│   │   ├── logging/            # Pino logger
│   │   ├── metrics/            # Prometheus metrics
│   │   ├── queue/              # BullMQ workers
│   │   ├── wallets/            # Wallet loader & store
│   │   └── websocket/          # WebSocket server
│   │
│   ├── middleware/             # Express middleware
│   │   ├── auth.ts             # JWT authentication
│   │   ├── api-key-auth.ts     # API key authentication
│   │   ├── rate-limiter.ts     # Rate limiting
│   │   ├── validation.ts       # Request validation
│   │   └── error-handler.ts    # Global error handling
│   │
│   ├── shared/                 # Backend-specific utilities
│   │   ├── constants/          # Redis key patterns
│   │   ├── errors/             # Custom error classes
│   │   └── utils/              # Auth, timeout utilities
│   │
│   ├── config/                 # Configuration
│   │   ├── app.config.ts       # App configuration
│   │   └── redis.config.ts     # Redis configuration
│   │
│   └── index.ts                # Application entry point
│
├── tests/
│   ├── unit/                   # Unit tests
│   └── integration/            # Integration tests
│
└── postman/                    # Postman collection

Key Backend Directories

Directory	Purpose
`api/v1/`	REST endpoints organized by resource
`domain/`	Business logic, services, domain events
`infrastructure/cache/`	Redis caching services (balances, positions, prices)
`infrastructure/external/`	Third-party API integrations
`infrastructure/queue/`	BullMQ job definitions and workers

Frontend Package (`nexgent-open-source-trading-engine/frontend`)

The frontend uses Next.js 15 App Router with a feature-based organization.

packages/frontend/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/             # Auth route group
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (dashboard)/        # Dashboard route group
│   │   │   └── dashboard/
│   │   │       ├── general/
│   │   │       ├── agent-profile/
│   │   │       ├── performance-overview/
│   │   │       ├── trade-signals/
│   │   │       ├── transactions/
│   │   │       └── wallet/
│   │   ├── api/auth/           # NextAuth API route
│   │   ├── layout.tsx          # Root layout
│   │   └── globals.css         # Global styles
│   │
│   ├── features/               # Feature modules
│   │   ├── agents/             # Agent management
│   │   ├── auth/               # Authentication
│   │   ├── dashboard/          # Dashboard widgets
│   │   ├── performance/        # Performance charts
│   │   ├── signals/            # Signal management
│   │   ├── transactions/       # Transaction history
│   │   └── wallet/             # Wallet management
│   │
│   ├── infrastructure/         # Infrastructure concerns
│   │   ├── api/                # API client & services
│   │   ├── auth/               # Auth configuration
│   │   └── websocket/          # WebSocket hook
│   │
│   └── shared/                 # Shared utilities
│       ├── components/         # Reusable components
│       │   ├── ui/             # shadcn/ui components
│       │   ├── layout/         # Layout components
│       │   ├── loading/        # Loading states
│       │   └── error/          # Error boundaries
│       ├── contexts/           # React contexts
│       ├── hooks/              # Custom hooks
│       ├── providers/          # Context providers
│       └── utils/              # Utility functions
│
└── public/                     # Static assets

Key Frontend Directories

Directory	Purpose
`app/(dashboard)/`	Dashboard pages using route groups
`features/`	Self-contained feature modules with components, hooks, types
`infrastructure/api/`	API client, services, React Query hooks
`infrastructure/websocket/`	WebSocket connection management
`shared/components/ui/`	shadcn/ui component library

Shared Package (`nexgent-open-source-trading-engine/shared`)

Contains code shared between frontend and backend.

packages/shared/
├── src/
│   ├── types/                  # TypeScript types
│   │   ├── api/                # API request/response types
│   │   │   ├── agents.ts
│   │   │   ├── auth.ts
│   │   │   ├── trading-signals.ts
│   │   │   └── ...
│   │   ├── trading-config.ts   # Trading configuration types
│   │   └── agent-position.ts   # Position types
│   │
│   ├── validators/             # Zod schemas
│   │   ├── agents.schema.ts
│   │   ├── auth.schema.ts
│   │   └── ...
│   │
│   ├── constants/              # Shared constants
│   │   ├── trading-config-defaults.ts
│   │   └── dca-templates.ts
│   │
│   ├── utils/                  # Shared utilities
│   │   └── stop-loss-calculator.ts
│   │
│   └── index.ts                # Package exports
│
└── package.json

The shared package uses TypeScript path exports. Both frontend and backend import from nexgent-open-source-trading-engine/shared which resolves to the source TypeScript files directly.

Package Dependencies

┌─────────────────┐
│   nexgent-open- │
│   source-trading │
│   -engine/      │
│   frontend      │
└────────┬────────┘
         │ imports
         ▼
┌─────────────────┐
│   nexgent-open- │
│   source-trading │
│   -engine/      │
│   shared        │
└────────┬────────┘
         │ imports
         ▲
┌────────┴────────┐
│   nexgent-open- │
│   source-trading │
│   -engine/      │
│   backend       │
└─────────────────┘

Both frontend and backend depend on shared. The shared package has no dependencies on other workspace packages.

Workspace Configuration

pnpm-workspace.yaml:

packages:
  - 'packages/*'

Root package.json scripts:

Script	Description
`pnpm dev`	Run backend and frontend concurrently
`pnpm build`	Build all packages
`pnpm test`	Run tests across all packages
`pnpm lint`	Lint all packages

Overview Technology Stack