Architecture Overview

Nexgent is built as a layered, event-driven architecture optimized for ultra-low latency trading operations. The system processes trading signals, executes trades via the Solana blockchain, and broadcasts real-time updates to connected clients.

Design Principles

Principle	Implementation
Ultra-Low Latency	Sub-500ms signal processing, sub-1ms stop loss evaluation, batched price updates
Write-Through Caching	Redis caches are updated synchronously with database writes for consistency
Event-Driven	Internal EventEmitters decouple components; WebSocket broadcasts state changes
Domain-Driven Design	Business logic isolated in domain layer, infrastructure concerns separated
Fail-Safe Trading	Idempotency keys prevent duplicate trades; atomic DB transactions ensure consistency

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js 15)                        │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────────────┐ │
│  │ Dashboard │  │  Agents   │  │ Positions │  │  Trading Config   │ │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────────┬─────────┘ │
│        └──────────────┴──────────────┴──────────────────┘           │
│                              │                                       │
│                    ┌─────────┴─────────┐                            │
│                    │   React Query +   │                            │
│                    │    WebSocket      │                            │
│                    └─────────┬─────────┘                            │
└──────────────────────────────┼──────────────────────────────────────┘
                               │
               ┌───────────────┼───────────────┐
               │  REST API     │   WebSocket   │
               ▼               ▼               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Backend (Express)                            │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                        API Layer                                │ │
│  │   Auth │ Agents │ Signals │ Wallets │ Positions │ Health       │ │
│  └────────────────────────────┬───────────────────────────────────┘ │
│                               │                                      │
│  ┌────────────────────────────┴───────────────────────────────────┐ │
│  │                       Domain Layer                              │ │
│  │  Signal Processor │ Trading Executor │ Position Service        │ │
│  │  Balance Service  │ Stop Loss Manager │ DCA Manager            │ │
│  └────────────────────────────┬───────────────────────────────────┘ │
│                               │                                      │
│  ┌────────────────────────────┴───────────────────────────────────┐ │
│  │                    Infrastructure Layer                         │ │
│  │  Prisma (PostgreSQL) │ Redis Cache │ BullMQ │ WebSocket Server │ │
│  │  Jupiter API │ Pyth Network │ DexScreener │ Solana Web3.js     │ │
│  └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Layer Responsibilities

API Layer

Handles HTTP requests and WebSocket connections. Validates input using Zod schemas, authenticates requests via JWT or API keys, and delegates to domain services.

Domain Layer

Contains all business logic for trading operations. Services are decoupled via EventEmitters and follow the single responsibility principle.

Infrastructure Layer

Manages external integrations (Jupiter, Pyth, Solana), data persistence (PostgreSQL via Prisma), caching (Redis), and background job processing (BullMQ).

Key Architectural Patterns

Event-Driven Signal Processing

When a trading signal is created, the system emits an event that triggers parallel processing for all eligible agents:

Signal Created → Event Emitted → Agent Eligibility Check → Parallel Trade Execution

Signals are processed in parallel across agents for maximum throughput. Each agent's trade execution is independent and isolated.

Write-Through Caching

All state changes follow a write-through pattern to ensure cache consistency:

Begin database transaction
Write to PostgreSQL
Commit transaction
Update Redis cache
Emit WebSocket event

This ensures the cache is never stale relative to the database.

Real-Time Price Monitoring

The Price Update Manager continuously polls token prices and evaluates trading conditions:

Poll Prices (1.5s) → Update Redis Cache → Evaluate Stop Loss → Evaluate DCA → Broadcast via WebSocket

Communication Patterns

Pattern	Usage
REST API	CRUD operations, authentication, configuration
WebSocket	Real-time position updates, price broadcasts, connection status
EventEmitter	Internal service decoupling (signals, positions, prices)
Job Queue	Async database writes, scheduled snapshots

Security Architecture

JWT Authentication for user sessions with short-lived access tokens
API Key Authentication for programmatic access with scoped permissions
Rate Limiting per endpoint and per user
Account Lockout after failed login attempts
Non-Custodial Wallets loaded from environment variables (private keys never stored in DB)

Error Codes & Handling Monorepo Structure