ChainGuard System Components

Version: 1.0.0
Last Updated: 18-11-2025
Status: Production Ready

Overview
Application Components
Infrastructure Components
Component Communication
Component Status Matrix
Related Documentation

Overview

The ChainGuard system consists of 11 components (7 application components + 4 infrastructure components) working together to provide a comprehensive Web3 security and identity infrastructure. This document provides detailed information about each component, including their purpose, technology stack, key features, and integration points.

Application Components

1. ChainGuard DApp (Frontend) 🌐

Type: Public Marketing & Documentation Website
Technology: Next.js 15, TypeScript, SSR
Port: 3000 (production)
Status: ✅ Production Ready

Purpose: Serves as the public-facing website and documentation hub for the ChainGuard ecosystem, providing product information, compliance documentation, and technical guides.

Key Features:

Homepage & Product Pages (Identity, OAuth, Vault, Mobile App, Guard Token)
Compliance Center (11 jurisdictions with multilingual support)
Documentation Hub (technical architecture and system documentation)
FAQ System (interactive FAQ with chat-like interface)
Geo-Targeting System (multi-region SEO with structured data)
Multi-Language Support (15+ language translations with i18n)
Advanced Search (section-aware search across docs and compliance)

Architecture:

Next.js 15 App Router with mobile-first, SSR-first approach
Server-Side Rendering (SSR) for SEO optimization
Client-Side Rendering (CSR) for interactive features
MDX support for rich content
Type-safe TypeScript implementation

Integration Points:

Links to OAuth Portal for user authentication
References Backend Server APIs (if needed)
SEO/GEO optimization for multi-region presence

Related Documentation:

System Overview - System architecture details
Components Overview - Complete component catalog

2. ChainGuard Backend Server 🔐

Type: Core Authentication & Authorization Service
Technology: Node.js, Express, PostgreSQL, Redis, Socket.IO
Port: 3001
Status: ✅ Production Ready

Purpose: Central authentication and authorization hub providing user authentication, OAuth 2.0 provider capabilities, 2FA coordination, and compliance logging.

Key Services:

Authentication Service (JWT + 2FA)
OAuth 2.0 Provider (authorization code flow)
WebSocket Server (Socket.IO for 2FA coordination)
User Management (profiles, accounts)
Wallet Management (linking, verification)
Vault Coordination (integration with Forwarder Server)
Compliance Logging (ISO 27001, GDPR, OAuth-compliant events)
Session Management (dual-cookie system)

Key Features:

Dual-token authentication (main token + 2FA token)
OAuth 2.0 authorization server
WebSocket-based 2FA coordination
Comprehensive compliance event logging
Wallet-based signature verification
Billing integration (Stripe)

Integration Points:

OAuth Portal (authentication, user data)
Mobile App (2FA WebSocket communication)
Forwarder Server (vault operations)
PostgreSQL (user data, compliance logs)
Redis (sessions, cache, rate limiting)
Stripe API (payment processing)

Related Documentation:

OAuth Flow - OAuth 2.0 authentication flow
Security Framework - Authentication and authorization security

3. OAuth Portal (module.chain-fi.io) 🔒

Type: Private User Workspace
Technology: Next.js 15, TypeScript
Port: Internal deployment
Status: ✅ Production Ready

Purpose: Private user workspace where users authenticate, manage their accounts, approve OAuth applications, and control their ecosystem interactions.

Key Features:

User Dashboard (account overview, statistics)
OAuth Consent Screens (scope approval, application management)
2FA Setup & Verification (wallet-based 2FA configuration)
Wallet & Vault Management (link wallets, manage vaults)
Application Access Control (revoke scopes, manage permissions)
Activity History (compliance-ready logs)
Billing Integration (subscription management, payment)

Key Pages:

/dashboard: User dashboard with overview
/apps: List authorized client apps
/app-access: Fine-grained access toggles per scope
/vaults: Configure fallback addresses, guardians, view vault status
/activity-history: Displays compliance-ready logs

Integration Points:

Backend Server (authentication, OAuth, user data)
Forwarder Server (vault operations)
Mobile App (2FA coordination via WebSocket)
Stripe (billing workflows)

Related Documentation:

OAuth Flow - Complete OAuth 2.0 flow documentation
System Overview - System architecture details

4. Forwarder Server (Payment Service) 💳

Type: Blockchain Transaction Relay & Payment Gateway
Technology: Node.js, Express, Ethers.js, Stripe
Port: 3000 (separate instance)
Status: ✅ Production Ready

Purpose: Acts as the guardian (payment server) that enables gasless transactions and secure vault creation by relaying meta-transactions and processing payments.

Key Services:

Vault Creation Service (dual-signature vault creation)
Meta-Transaction Relay (gasless transaction execution)
Stripe Payment Processing (subscription billing, webhooks)
Multi-Chain Support (Base, Arbitrum, Optimism)
Signature Verification (EIP-712 signature validation)
Wallet Validation (ownership verification)

Key Features:

Non-custodial design (never holds user funds)
Guardian-mediated gasless transactions
EIP-712 signature verification
Multi-chain support (Base, Arbitrum, Optimism)
Stripe integration for payments
Deadline enforcement and replay protection

Integration Points:

Backend Server (vault creation requests)
OAuth Portal (vault operations)
Blockchain Networks (smart contract interactions)
Stripe API (payment processing)
Vault Smart Contracts (on-chain operations)

Related Documentation:

Vault System - Guardian workflow and vault operations
System Overview - Payment service integration

5. Blockchain Listener ⚡

Type: Real-Time Blockchain Monitor
Technology: Node.js, Express, Ethers.js, Redis, WebSocket
Port: 3005
Status: ✅ Production Ready

Purpose: Monitors blockchain networks in real-time, tracking transactions, analyzing events, and broadcasting updates to connected clients.

Key Services:

Block Listener Service (multi-chain block monitoring)
Transaction Analyzer (transaction parsing and analysis)
Transaction Decoder (event decoding)
Balance Service (balance tracking)
Balance Checker (balance queries)
Provider Management (multi-chain RPC management)
Registry Service (vault registry monitoring)
WebSocket Broadcasting (real-time updates)

Key Features:

Real-time block monitoring across multiple chains
Transaction event detection and decoding
Balance tracking and updates
WebSocket broadcasting for real-time notifications
Redis caching for performance
Multi-chain support (Base, Arbitrum, Optimism)

Integration Points:

Blockchain Networks (RPC endpoints, WebSocket connections)
Redis (transaction data storage, caching)
Backend Server (real-time transaction updates via WebSocket)
Vault Contracts (transaction monitoring)

Related Documentation:

System Overview - Blockchain monitoring architecture
Components Overview - Component communication patterns

6. ChainGuard Mobile App 📱

Type: Mobile 2FA Authenticator
Technology: React Native, Expo, Socket.IO Client
Platform: iOS & Android
Status: ✅ Production Ready

Purpose: Secure mobile authenticator for wallet-based two-factor authentication, transaction signing, and secure key storage.

Key Features:

QR Code Scanner (2FA session establishment)
Wallet Generator & Manager (secure wallet creation and storage)
Transaction Signer (EIP-712 signature generation)
Secure Storage (Expo Secure Store, device Keychain/Keystore)
Socket.IO Client (WebSocket communication with Backend Server)
Transaction Renderer (human-readable transaction display)

Key Screens:

QR Scanner (scan 2FA session QR codes)
Wallet Management (view and manage wallets)
Transaction Signing (approve transactions with signatures)
Settings (app configuration)

Security:

Private keys stored in device secure storage
Keys never leave the device
Offline-capable signing
Biometric protection (optional)
No network exposure of private keys

Integration Points:

Backend Server (WebSocket for 2FA coordination)
OAuth Portal (QR code generation and display)
Blockchain Networks (signature generation for on-chain verification)

Related Documentation:

OAuth Flow - 2FA integration and wallet-based authentication
Security Framework - Mobile app security controls

7. ChainGuard Vault Stack 🔗

Type: Smart Contract Infrastructure (On-Chain)
Technology: Solidity 0.8.23, EIP-712, Deterministic Clones
Deployment: Base Sepolia (84532), Arbitrum Sepolia (421614), Optimism Sepolia (11155420)
Status: ✅ Production Ready

Purpose: On-chain smart contract infrastructure providing non-custodial vault functionality with dual-signature enforcement and guardian-mediated gasless transactions.

Smart Contracts:

7.1 ChainFiVault

User-owned smart wallets
Multi-asset support (ETH, ERC20, ERC721, ERC1155)
Dual-signature enforcement (owner + auth)
Guardian-mediated gasless transactions
Emergency fallback paths

7.2 ChainFiVaultFactory

Deterministic vault deployment
Guardian protection mechanisms
Version management
Clones pattern for gas efficiency

7.3 ChainFiVaultRegistry

Canonical owner ↔ vault mapping
Version tracking
Single-vault-per-user policy
Vault metadata storage

7.4 WhitelistRegistry

Guardian address management
Whitelisted contract addresses
Token metadata storage
Category-based whitelisting

7.5 ChainFiMarketPlace

On-chain NFT marketplace
Guardian-verified listings
ERC721 and ERC1155 support
Emergency unlisting capabilities

Key Features:

Non-custodial design (users control keys)
Dual-signature enforcement
Guardian-mediated gasless transactions
Multi-chain deployment
Deterministic vault addresses
Comprehensive security controls

Integration Points:

Forwarder Server (guardian role, transaction relay)
Blockchain Networks (deployment and operations)
Backend Server (vault coordination)
Blockchain Listener (transaction monitoring)

Related Documentation:

Vault System - Complete vault architecture documentation
Security Framework - Vault security controls

Infrastructure Components

8. PostgreSQL Database 💾

Type: Primary Database
Technology: PostgreSQL 15+
Port: 5432 (5433 in Docker)
Status: ✅ Production Ready

Purpose: Primary relational database storing user data, OAuth clients, compliance events, and file metadata.

Key Data:

User accounts and profiles
OAuth clients and tokens
Compliance event logs (7-year retention)
File metadata
Session data
Wallet linkages
Vault metadata

Key Tables:

users - User accounts
oauth_clients - OAuth client registrations
oauth_tokens - Access and refresh tokens
compliance_events - Compliance event logs
wallets - Linked wallet addresses
sessions - User sessions
files - File metadata

Security:

Encrypted at rest (AES-256)
Access controls and authentication
Backup and recovery procedures
Network segmentation

Integration Points:

Backend Server (primary data access)
OAuth Portal (user data, OAuth operations)
All application components (data storage)

9. Redis Cache 💾

Type: Cache & Session Store
Technology: Redis 7+
Port: 6379
Status: ✅ Production Ready

Purpose: In-memory data store for sessions, caching, rate limiting, and real-time data.

Key Uses:

User sessions (session storage)
Rate limiting (request throttling)
Real-time transaction cache
Pub/Sub messaging (event broadcasting)
Temporary data storage
WebSocket session management

Key Features:

High-performance in-memory storage
Pub/Sub messaging for real-time events
TTL-based expiration
Persistence options
Clustering support

Integration Points:

Backend Server (sessions, rate limiting, cache)
Blockchain Listener (transaction cache, Pub/Sub)
All services (caching, rate limiting)

10. MinIO (S3-Compatible) 💾

Type: Object Storage
Technology: MinIO (S3-compatible)
Ports: 9000 (API), 9001 (Console)
Status: ✅ Production Ready

Purpose: Object storage for encrypted file storage, user-uploaded files, and document storage.

Key Features:

S3-compatible API
Encrypted file storage (AES-256)
Encrypted file names
Version history
Bucket organization
Access controls

Storage Structure:

chainfi-dev / chainfi-prod - Main buckets
encrypted/ - Encrypted file storage
public/ - Public file storage (if needed)
temp/ - Temporary file storage

Integration Points:

Backend Server (file upload/download)
OAuth Portal (user file management)
All services requiring file storage

11. Hashicorp Vault 🔐

Type: Key Management
Technology: Hashicorp Vault
Port: 8200
Status: ✅ Production Ready

Purpose: Secret management and encryption key storage for secure credential and key management.

Key Secrets:

JWT secrets (token signing keys)
Database credentials (PostgreSQL connection strings)
Stripe API keys (payment processing)
Blockchain private keys (payment server/guardian wallet)
Encryption keys (file encryption, data encryption)

Secret Paths:

secret/chainfi/jwt - JWT secrets
secret/chainfi/database - Database credentials
secret/chainfi/stripe - Stripe API keys
secret/chainfi/blockchain - Private keys (payment server)
secret/chainfi/encryption - Encryption keys

Key Features:

Encrypted secret storage
Key rotation capabilities
Access controls and audit logging
Secret versioning
Dynamic secret generation

Integration Points:

Backend Server (JWT secrets, database credentials)
Forwarder Server (blockchain private keys)
All services requiring secret access

Component Communication

Component Communication Matrix

Communication Patterns

Synchronous REST API:

Request-Response pattern
User authentication, data retrieval, OAuth token exchange
All services use REST for standard CRUD operations

Asynchronous WebSocket:

Event-driven, bidirectional
2FA session coordination, real-time transaction updates
Backend Server, Mobile App, OAuth Portal, Blockchain Listener

Message Queue (Redis Pub/Sub):

Publish-Subscribe pattern
Real-time event broadcasting, cross-service notifications
Blockchain Listener → Backend Server, Backend Server → Portal

Blockchain RPC:

Request-Response (JSON-RPC)
Smart contract interactions, transaction submission, balance queries
Forwarder Server, Blockchain Listener

Smart Contract Interactions:

Meta-transactions with EIP-712 signatures
Vault creation, asset transfers, marketplace operations
Forwarder Server (Guardian), Vault Contracts

Component Status Matrix

Component	Status	Production Ready	Multi-Chain	Security Level
ChainGuard DApp	✅	Yes	N/A	Public-facing
Backend Server	✅	Yes	N/A	High (Auth)
OAuth Portal	✅	Yes	N/A	High (Private)
Forwarder Server	✅	Yes	Yes (3 chains)	Critical (Guardian)
Blockchain Listener	✅	Yes	Yes (3 chains)	Medium
Mobile App	✅	Yes	N/A	Critical (Keys)
Vault Stack	✅	Yes	Yes (3 chains)	Critical (On-chain)
PostgreSQL	✅	Yes	N/A	High (Data)
Redis	✅	Yes	N/A	Medium (Cache)
MinIO	✅	Yes	N/A	High (Files)
Hashicorp Vault	✅	Yes	N/A	Critical (Secrets)

ChainGuard System Components

Table of Contents

Overview

Application Components

1. ChainGuard DApp (Frontend) 🌐

2. ChainGuard Backend Server 🔐

3. OAuth Portal (module.chain-fi.io) 🔒

4. Forwarder Server (Payment Service) 💳

5. Blockchain Listener ⚡

6. ChainGuard Mobile App 📱

7. ChainGuard Vault Stack 🔗

7.1 ChainFiVault

7.2 ChainFiVaultFactory

7.3 ChainFiVaultRegistry

7.4 WhitelistRegistry

7.5 ChainFiMarketPlace

Infrastructure Components

8. PostgreSQL Database 💾

9. Redis Cache 💾

10. MinIO (S3-Compatible) 💾

11. Hashicorp Vault 🔐

Component Communication

Component Communication Matrix

Communication Patterns

Component Status Matrix

Related Documentation