ChainGuard Project Architecture

Version: 2.0.0
Last Updated: 18-11-2025
Status: Production Ready - ISO 27001 Ready

Overview
What ChainGuard Provides
System Architecture
Roles & Responsibilities
Token Responsibilities & Holders
Authentication & OAuth Flow
Vault System
System Boundaries
Security & Compliance
Related Documentation

Overview

Welcome to the ChainGuard Project Architecture documentation. This section provides a comprehensive overview of ChainGuard's system architecture, components, and technical implementation.

ChainGuard provides non-custodial Web3 security and identity infrastructure. We give regulated businesses the tools to bind wallets to verified users, enforce policy, and generate audit trails — but we never hold client assets or control user funds.

Key Characteristics

Non-Custodial by Design: Users maintain full control of their keys and assets at all times
OAuth 2.0 Provider: Complete authorization server for third-party integrations
Wallet-Based 2FA: Hardware-level security with mobile device signatures
Vault System: Non-custodial smart wallets with dual-signature enforcement
Compliance-First: Built-in logging for ISO 27001, GDPR, and regulatory requirements
Multi-Chain Support: Deployed on Base, Arbitrum, and Optimism

What ChainGuard Provides

ChainGuard offers a comprehensive Web3 security and identity platform:

Core Services

Authentication System: Email/password authentication with optional wallet-based 2FA
OAuth 2.0 Provider: Full authorization server for third-party applications ("Login with ChainGuard")
User Portal (module.chain-fi.io): Private workspace where users authenticate, manage accounts, and approve access
Backend API: RESTful API that client servers use to fetch user data within approved scopes
Vault System: Secure, non-custodial asset management with transaction-level 2FA
Mobile 2FA App: Secure mobile authenticator for wallet-based signature verification
Blockchain Listener: Real-time transaction monitoring and analytics
Payment Service: Guardian-mediated gasless transactions and payment processing

Key Features

Identity Verification: Optional KYC integration (Sumsub) for enterprise use cases
Device & Wallet Binding: Cryptographic proof of ownership and device attestation
Audit Trails: Comprehensive logging for compliance requirements (ISO 27001, GDPR)
Multi-Jurisdictional Support: Tailored compliance per region (EU, US, UK, UAE, Singapore, Hong Kong, Japan, Korea)
Gasless Transactions: Guardian-mediated meta-transactions for seamless user experience
Emergency Fallback: Always-accessible withdrawal functions, even in free mode

System Architecture

The ChainGuard system consists of 7 core components (6 off-chain services + 1 on-chain vault stack):

High-Level Architecture Overview

Application Components

ChainGuard DApp (Frontend) - Public marketing and documentation website
ChainGuard Backend Server - Core authentication and authorization service
OAuth Portal (module.chain-fi.io) - Private user workspace
Forwarder Server (Payment Service) - Blockchain transaction relay and payment gateway
Blockchain Listener - Real-time blockchain monitor
ChainGuard Mobile App - Mobile 2FA authenticator
ChainGuard Vault Stack - Smart contract infrastructure (on-chain)

Infrastructure Components

PostgreSQL Database - User data, OAuth clients, compliance events
Redis Cache - Sessions, rate limiting, real-time data
MinIO (S3-Compatible) - Encrypted file storage
Hashicorp Vault - Secret management and encryption keys

For detailed component information, see System Components.

Roles & Responsibilities

ChainGuard Backend (CG-BE)

The ChainGuard Backend Server handles:

Authentication: Email/password login with JWT token management
2FA Verification: WebSocket-based coordination with mobile app for wallet-based signatures
OAuth Authorization: Full OAuth 2.0 authorization server (authorization code flow)
Wallet Management: Wallet linking, verification, and ownership validation
Vault Coordination: Integration with Forwarder Server for on-chain operations
Compliance Logging: ISO 27001, GDPR, and OAuth-compliant event logging
Session Management: Dual-cookie system (main token + 2FA token)
User Management: Profiles, accounts, and access control

Technology: Node.js, Express, PostgreSQL, Redis, Socket.IO
Port: 3001

ChainGuard Portal (module.chain-fi.io)

The ChainGuard Portal is the user-facing interface for:

Authentication & Account Management: User login, profile management, settings
OAuth Consent Screens: Scope approval and application authorization
App Permissions Management: Users can review and revoke app permissions
2FA Setup & Verification: Wallet-based 2FA configuration and management
Wallet & Vault Management: Link wallets, manage vaults, view balances
Activity History: Compliance-ready audit trail display
Billing Integration: Subscription management and payment workflows

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

Technology: Next.js 15, TypeScript

ChainGuard 2FA App

The mobile application used for:

Wallet-Based Signature Verification: EIP-712 signature generation
QR Code Scanning: 2FA session establishment via QR codes
Secure Key Storage: Private keys stored in device secure storage (Keychain/Keystore)
Transaction Signing: Per-transaction authorization for vault operations
WebSocket Communication: Secure real-time communication with Backend Server

Technology: React Native, Expo, Socket.IO Client
Platform: iOS & Android

Client Backend (CL-BE)

Owned fully by the third-party client — not part of ChainGuard.

The client backend:

Holds client_id + client_secret (API key + secret)
Uses these credentials to:
- Exchange OAuth authorization codes for tokens
- Refresh access tokens
- Make authenticated calls to ChainGuard Backend
API key usage is tracked by ChainGuard to measure app usage and manage access
Fetches user data via ChainGuard endpoints only within granted scopes
Creates its own session (cookies) for the client's frontend
Never exposes tokens or secrets to frontend

Client Frontend (CL-FE)

Owned fully by the third-party client — not part of ChainGuard.

The client frontend:

Displays "Login with ChainGuard" button
Redirects users to ChainGuard authorization
Receives callback → sends code to CL-BE
Uses CL-BE session cookies for authentication
Never receives or stores OAuth tokens

Token Responsibilities & Holders

Token Type	Holder	Storage	Purpose	Exposure Risk
Main JWT	ChainGuard Portal only	HttpOnly cookie	User session inside module.chain-fi.io	None (server-side only)
2FA JWT	ChainGuard Portal only	HttpOnly cookie	Confirms wallet-based 2FA completion	None (server-side only)
OAuth Access Token	Client Backend only	Server-side storage	Allows client backend to call ChainGuard APIs within approved scopes	None (never sent to frontend)
OAuth Refresh Token	Client Backend only	Server-side storage	Used to renew access tokens	None (never sent to frontend)
client_id + client_secret	Client Backend only	Server-side storage	App identity, token exchanges, and usage tracking	High (must be protected)
Client Session Cookie	Client Backend → Client Frontend	HttpOnly cookie	Authenticates the user inside the client's own application	Minimal (client-controlled)

Key Principles:

Tokens never exposed to frontend environments
Server-to-server exchanges only
HttpOnly cookies prevent XSS attacks
Refresh tokens stored server-side only
No token storage in browser localStorage or sessionStorage

Authentication & OAuth Flow

OAuth 2.0 Flow Diagram

Login Flow (Essential Sequence)

CL-FE: User clicks "Login with ChainGuard"
CL-FE → ChainGuard Portal: Redirect to /oauth/authorize
ChainGuard Portal: User logs in + passes 2FA + approves app
ChainGuard Portal → CL-FE: Redirects back with code and state
CL-FE → CL-BE: Send {code, state} to backend
CL-BE → CG-BE: Exchange code for {access_token, refresh_token}
CL-BE: Stores tokens, creates its own session cookie for the user
CL-FE: Now considered logged in (through CL-BE's session)

Getting User Data

CL-FE → CL-BE: "Give me my profile"
CL-BE → CG-BE: Call /oauth/userinfo with Authorization: Bearer <access_token>
If token expired → refresh using refresh_token
CL-BE → CL-FE: Returns user profile

What Each Side Can Access

Client secret → only CL-BE
Tokens → only CL-BE
User data → only via valid tokens + user-approved scopes
Frontends never see secrets or tokens; they use CL-BE session cookies

Supported Scopes

profile: User name, email, user ID
email: Email address
wallets: Linked wallet addresses
kyc: KYC verification status (if applicable)

For complete OAuth flow documentation, see OAuth Flow.

Vault System

ChainGuard Vault extends the core ChainGuard authentication system to handle on-chain transactions with enhanced security through transaction-specific signatures.

Key Security Features

Transaction-Level 2FA: Each transaction requires a separate signature from the ChainGuard 2FA app, not just initial authentication
On-Chain Signature Verification: Transaction signatures are verified directly on the smart contract level, providing cryptographic proof of authorization
Backend Compromise Protection: Even if ChainGuard's backend is compromised, attackers cannot simulate transactions without physical access to the user's mobile device containing the specific wallet
Portal-Mediated Transactions: All transaction requests flow through the ChainGuard Portal and must originate from authorized applications
Emergency Fallback: Always-accessible withdrawal functions that work even in free mode, allowing users to bypass guardian by paying gas directly

Transaction Flow

App initiates transaction: A listed application requests a transaction through the ChainGuard ecosystem
Portal authorization: Request is routed through module.chain-fi.io for user approval
2FA signature: User signs the transaction using ChainGuard 2FA app on their mobile device
On-chain verification: Smart contract verifies the signature cryptographically
Guardian execution: ChainGuard's Forwarder Server (Guardian) covers gas costs and executes the validated transaction
Logging: Complete audit trail is recorded in ChainGuard systems

Payment & Validation Architecture

Sponsored transactions: Guardian (Forwarder Server) pays for transaction gas fees
Ecosystem validation: Guardian validates that transactions originate from the ChainGuard ecosystem
Application tracking: System logs which application initiated each transaction, when, and by whom
Multi-chain support: Deployed on Base, Arbitrum, and Optimism

Audit & Compliance Features

Comprehensive logging: Connection events, logout events, transaction requests, signatures, and execution results
User activity tracking: Complete audit trail of who performed what action and when
Compliance-ready: Extensive logging supports regulatory auditing requirements and ISO 27001 monitoring controls

For detailed vault architecture, see Vault System.

System Boundaries

Within ChainGuard Scope

ChainGuard Backend (CG-BE)
ChainGuard Portal (module.chain-fi.io)
ChainGuard 2FA App
OAuth authorization and token issuance
API key tracking
User session JWTs
Vault smart contracts
Guardian (Forwarder Server) operations

Outside ChainGuard Scope

Client Backend (CL-BE)
Client Frontend (CL-FE)
Client session management
Client data storage
Client application logic

Clear Separation:

ChainGuard handles authentication + 2FA
Client Backend handles token storage + data fetching
Client Frontend only handles redirects and UI
All sensitive data stays server-side

Security & Compliance

Security Framework

ChainGuard implements a comprehensive security framework aligned with ISO 27001:

Multi-Layer Authentication: Email/password + wallet-based 2FA
OAuth 2.0 Security: Authorization code flow with scope-based access control
Cryptographic Operations: EIP-712 signature verification, JWT tokens, encrypted storage
Network Security: Network segmentation, firewall rules, DDoS protection, WAF
Access Control: RBAC, scope-based permissions, wallet ownership validation
Encryption: AES-256 at rest, TLS 1.3+ in transit

For detailed security information, see Security Framework.

Compliance Features

ISO 27001 Ready: Comprehensive control mapping and audit logging
GDPR Compliant: Data protection by design, user rights, Article 30 records
Multi-Jurisdictional: Support for EU, US, UK, UAE, Singapore, Hong Kong, Japan, Korea
AML/CTF: KYC integration, transaction monitoring, sanctions screening
VAT Compliance: Automated VAT calculation and invoicing
Audit Trails: 7-year retention for compliance requirements

For regulatory compliance information, see Compliance Center.