# Architecture Layout

QuickDapp follows a modern, clean architecture built around the ServerApp dependency injection pattern. This document provides an overview of how all the pieces fit together.

# High-level Architecture

┌─────────────────────────────────────────────────────────────┐
│                     QuickDapp                               │
├─────────────────────────────────────────────────────────────┤
│  Frontend (React + Vite)                                  │
│  ├── React 19 + TypeScript                                │
│  ├── RainbowKit + Wagmi (Web3)                           │
│  ├── GraphQL Client (React Query)                        │
│  └── WebSocket Client                                     │
├─────────────────────────────────────────────────────────────┤
│  Backend (Bun + ElysiaJS)                                 │
│  ├── ElysiaJS Server                                     │
│  ├── GraphQL Yoga API                                    │
│  ├── SIWE Authentication                                 │
│  ├── WebSocket Server                                    │
│  └── Static Asset Serving                                │
├─────────────────────────────────────────────────────────────┤
│  Worker System (Child Processes)                          │
│  ├── Background Job Processing                           │
│  ├── Cron Job Scheduling                                 │
│  ├── Blockchain Monitoring                               │
│  └── IPC Communication                                   │
├─────────────────────────────────────────────────────────────┤
│  Database Layer (DrizzleORM + PostgreSQL)                 │
│  ├── Type-safe SQL Queries                               │
│  ├── Schema Migrations                                   │
│  └── Connection Pooling                                  │
├─────────────────────────────────────────────────────────────┤
│  Blockchain Layer (Viem)                                  │
│  ├── Public Client (Read Operations)                     │
│  ├── Wallet Client (Write Operations)                    │
│  └── Contract Interactions                               │
└─────────────────────────────────────────────────────────────┘

# The ServerApp Pattern

The core architectural innovation in QuickDapp is the ServerApp pattern - a dependency injection system that provides clean access to shared resources across all components.

export type ServerApp = {
  app: Elysia                    // ElysiaJS server instance
  db: PostgresJsDatabase         // DrizzleORM database connection
  rootLogger: Logger             // Root logger instance
  createLogger: typeof createLogger  // Logger factory
  workerManager: WorkerManager   // Background job processing
  socketManager: ISocketManager  // WebSocket manager
  publicClient: PublicClient     // Blockchain read client
  walletClient: WalletClient     // Blockchain write client
  createNotification: Function   // Notification system
}

Benefits of this pattern:

Clean dependencies - No global state or singletons
Easy testing - Mock individual services for unit tests
Type safety - Full TypeScript support across all layers
Consistent access - Same interface for all components

# Directory Structure

src/
├── server/              # Backend server code
│   ├── db/             # Database schema, migrations, and queries
│   ├── graphql/        # GraphQL resolvers and schema
│   ├── auth/           # Authentication (SIWE + JWT)
│   ├── workers/        # Background job system
│   ├── lib/            # Server utilities (logging, etc.)
│   └── ws/             # WebSocket implementation
├── client/             # Frontend React application
│   ├── components/     # React components
│   ├── hooks/          # Custom React hooks
│   ├── lib/            # Client-side utilities
│   └── pages/          # Application pages
├── shared/             # Code shared between client/server
│   ├── config/         # Environment configuration
│   └── graphql/        # GraphQL schema definitions
scripts/                # Build and development scripts
tests/                  # Integration test suite

# Technology Stack

# Runtime & Server

Bun - Primary runtime (Node.js v22+ compatible)
ElysiaJS - High-performance web framework with native WebSocket support
GraphQL Yoga - GraphQL server (no GraphQL subscriptions; use WebSockets for realtime)

# Frontend

React 19 - Latest React with concurrent features
Vite - Lightning-fast build tool and dev server
TypeScript - Full type safety across the stack

# Database & ORM

PostgreSQL - Robust relational database
DrizzleORM - Type-safe, performant SQL toolkit
postgres - High-performance PostgreSQL client

# Authentication & Security

SIWE (Sign-in with Ethereum) - Decentralized authentication
JWT (Jose) - Stateless token authentication
Custom auth directive - GraphQL operation-level security

# Web3 Integration

Viem - Type-safe Ethereum library
Wagmi - React hooks for Ethereum
RainbowKit - Wallet connection UI

# Background Processing

Child process architecture - Isolated worker processes
IPC communication - Inter-process messaging
Database job queue - Persistent job storage with retry logic

# Request Flow

# GraphQL API Request

Frontend sends GraphQL query
ElysiaJS receives request
GraphQL Yoga parses and validates
Auth directive checks JWT token
Resolver function executes
Database query via DrizzleORM
Response returned to client

# WebSocket Connection

Client establishes WebSocket connection
SocketManager handles connection
User authentication via JWT
Real-time message routing
Notifications sent to specific users

# Background Job Processing

Job submitted to database queue
Worker process picks up job
Job handler executes business logic
Results stored and notifications sent
Job marked complete or retry scheduled

# Configuration Management

QuickDapp uses a layered configuration system:

.env                    # Base configuration (committed)
.env.{NODE_ENV}         # Environment-specific overrides
.env.{NODE_ENV}.local   # Environment-specific local overrides
.env.local              # Local developer overrides (gitignored)

Configuration is loaded by the shared bootstrap pattern and provides type-safe access via:

serverConfig - Server-side configuration
clientConfig - Client-side configuration (subset of server config)

# Development Workflow

# Development Mode

Hot reload - Both frontend and backend update automatically
Database migrations - Schema changes applied instantly
Worker monitoring - Background jobs visible in logs
GraphQL playground - Interactive API exploration

# Testing

Integration tests - Full end-to-end testing
Database isolation - Each test gets a clean database
Server lifecycle - Tests manage server startup/shutdown
Mock services - Authentication and external services mocked

# Production Build

Binary compilation - Self-contained executables
Asset bundling - Frontend assets embedded in server
Database migrations - Production-safe schema updates
Docker support - Container-based deployment

# Data Flow

# Authentication Flow

User connects wallet
Frontend requests SIWE message
User signs message with wallet
Backend validates signature
JWT token issued and stored
Token used for subsequent requests

# Database Operations

TypeScript schema defines structure
DrizzleORM generates migrations
Migrations applied to database
Type-safe queries in application code
Connection pooling handles concurrency

# Real-time Updates

Server event occurs (job completion, etc.)
Notification created via ServerApp
SocketManager routes to connected users
Frontend receives WebSocket message
UI updates reactively

This architecture provides a solid foundation for building scalable, maintainable Web3 applications with modern development practices and excellent developer experience.