# Technical Architecture

Shield Yield Vaults is built with a modern, production-ready full-stack architecture.

## System Overview

```
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   React SPA     │◄────►│  Express API    │◄────►│   PostgreSQL    │
│   (Frontend)    │      │   (Backend)     │      │   (Database)    │
└─────────────────┘      └─────────────────┘      └─────────────────┘
         │                        │
         │                        │
         ▼                        ▼
┌─────────────────┐      ┌─────────────────┐
│  Xaman/Xumm SDK │      │   XRP Ledger    │
│  (Wallet Auth)  │      │   (Blockchain)  │
└─────────────────┘      └─────────────────┘
```

## Technology Stack

### Frontend

* **React 18**: Modern React with hooks and concurrent features
* **TypeScript**: Type safety across the entire codebase
* **Vite**: Lightning-fast dev server and optimized production builds
* **Wouter**: Lightweight routing
* **TanStack Query v5**: Server state management with caching
* **Tailwind CSS**: Utility-first styling
* **shadcn/ui**: High-quality component library built on Radix UI

### Backend

* **Express.js**: RESTful API server
* **Node.js**: JavaScript runtime
* **TypeScript**: Full type safety on backend
* **Drizzle ORM**: Type-safe database queries
* **Zod**: Runtime schema validation
* **PostgreSQL (Neon)**: Serverless database

### Blockchain Integration

* **xumm-sdk**: Xaman wallet integration for XRPL
* **xrpl**: XRP Ledger client library
* **@walletconnect/**\*: Multi-wallet support

## Architecture Patterns

### Separation of Concerns

```
/client          - Frontend React application
  /src/pages     - Page components
  /src/components - Reusable UI components
  /src/lib       - Utilities and contexts
  
/server          - Backend Express API
  /routes.ts     - API endpoints
  /storage.ts    - Database interface
  /db.ts         - Database connection
  
/shared          - Shared types and schemas
  /schema.ts     - Database schema and types
```

### Frontend Architecture

**State Management:**

* React Context for wallet state
* TanStack Query for server state
* Local state with useState/useReducer

**Data Flow:**

```
User Action → API Request → TanStack Query → Backend API
                                ↓
                         Cache Update
                                ↓
                        UI Re-render
```

### Backend Architecture

**Request Flow:**

```
HTTP Request → Route Handler → Validation (Zod) 
                                    ↓
                            Storage Interface
                                    ↓
                            Database (Drizzle)
                                    ↓
                            HTTP Response
```

### Database Schema

See [Database Schema](https://github.com/shield-xrpfinance/shieldfinance/blob/main/docs/platform/database.md) for detailed table structures.

**Key Tables:**

* `vaults` - Vault configurations
* `positions` - User positions
* `transactions` - Transaction history
* `vault_metrics_daily` - Historical analytics
* `dashboard_snapshots` - Portfolio history for charts
* `user_notifications` - Notification storage with read status

## Security Architecture

### Authentication

* Wallet-based authentication (no passwords)
* Session management with Express sessions
* PostgreSQL session store

### Transaction Security

* All transactions signed in user's wallet
* No private key storage on server
* Transaction hash verification on blockchain
* Network isolation (mainnet/testnet)

### API Security

* Environment variable validation
* Request body validation with Zod
* CORS configuration
* Rate limiting (production)

## Deployment Architecture

### Development

* Replit development environment
* Hot module reloading
* Development database (PostgreSQL)
* Demo mode for testing without API keys

### Production

* Replit deployment platform
* Automatic TLS/HTTPS
* Production database (separate from dev)
* Environment variable management
* Health checks and monitoring

## Dashboard Enhancements Architecture

### Component Structure

```
client/src/components/dashboard/
├── PortfolioSummaryCard.tsx   # Real-time vault balances
├── PortfolioPerformanceChart.tsx  # Historical charts
├── BoostImpactBanner.tsx      # SHIELD boost visualization
└── NotificationCenter.tsx     # Persistent notifications
```

### Data Flow

```
Wallet Connect → useUserDashboard Hook → Dashboard Summary API
                      ↓
              TanStack Query Cache
                      ↓
              UI Components (30s polling)
```

### Notification System

```
Event Trigger (Deposit/Withdrawal/Stake/Claim)
         ↓
    Storage Layer (createUserNotification)
         ↓
    PostgreSQL (user_notifications table)
         ↓
    useNotifications Hook (10s polling)
         ↓
    NotificationCenter UI
```

### Key Hooks

* **useUserDashboard**: Aggregated portfolio data with health-aware polling
* **usePortfolioHistory**: Historical snapshots with time range state
* **useNotifications**: CRUD operations with unread count tracking

## Performance Optimizations

### Frontend

* Code splitting with React.lazy
* TanStack Query caching
* Optimistic updates
* Debounced search and filters
* Image optimization
* Dashboard polling with stale-while-revalidate

### Backend

* Database connection pooling
* Prepared statements (Drizzle)
* Response caching headers
* Efficient query patterns

### Database

* Indexed columns for fast lookups
* Proper foreign key relationships
* Decimal precision for financial data
* Timestamps for audit trails

## Monitoring & Logging

### Development

* Console logging
* Hot reload notifications
* Error boundaries
* LSP diagnostics

### Production

* Application logs
* Error tracking
* Performance monitoring
* Database query logging

## Learn More

* [Frontend Stack](https://github.com/shield-xrpfinance/shieldfinance/blob/main/docs/platform/frontend.md)
* [Backend Stack](https://github.com/shield-xrpfinance/shieldfinance/blob/main/docs/platform/backend.md)
* [Database Schema](https://github.com/shield-xrpfinance/shieldfinance/blob/main/docs/platform/database.md)
* [Xaman Integration](/platform/xaman-integration.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shyield.finance/platform.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.