impersonator/docs/03-structure.md

Project Structure

This document provides a detailed overview of the project's file structure and organization.

Directory Structure

impersonator/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout with metadata
│   ├── page.tsx                 # Home page component
│   ├── providers.tsx            # Global context providers
│   └── icon.png                # App icon
│
├── components/                   # React components
│   ├── Body/                    # Main body components
│   │   ├── index.tsx           # Main body orchestrator
│   │   ├── TabsSelect.tsx     # Tab navigation
│   │   ├── WalletConnectTab/  # WalletConnect integration
│   │   ├── IFrameConnectTab/  # iFrame integration
│   │   ├── BrowserExtensionTab.tsx
│   │   ├── TransactionRequests.tsx
│   │   ├── AddressInput/       # Address input with ENS
│   │   ├── NetworkInput.tsx    # Network selection
│   │   └── TenderlySettings.tsx
│   │
│   ├── SmartWallet/            # Smart wallet components
│   │   ├── WalletManager.tsx  # Wallet list and selection
│   │   ├── OwnerManagement.tsx # Owner and threshold management
│   │   └── DeployWallet.tsx   # New wallet deployment
│   │
│   ├── TransactionExecution/   # Transaction components
│   │   ├── TransactionBuilder.tsx    # Transaction creation
│   │   ├── TransactionApproval.tsx  # Approval interface
│   │   └── TransactionHistory.tsx   # Transaction list
│   │
│   ├── Balance/                 # Balance components
│   │   ├── WalletBalance.tsx   # Balance display
│   │   └── AddToken.tsx        # Add custom token
│   │
│   ├── layouts/                 # Layout components
│   ├── Navbar.tsx              # Navigation bar
│   ├── Footer.tsx              # Footer component
│   ├── ErrorBoundary.tsx       # Error boundary
│   └── CustomConnectButton.tsx
│
├── contexts/                     # React contexts
│   ├── SafeInjectContext.tsx   # iFrame communication context
│   ├── SmartWalletContext.tsx  # Smart wallet state
│   └── TransactionContext.tsx  # Transaction state
│
├── helpers/                      # Helper functions
│   ├── communicator.ts         # Message communication
│   ├── messageFormatter.ts     # Message formatting
│   ├── utils.ts                # General utilities
│   │
│   ├── smartWallet/            # Smart wallet helpers
│   │   ├── gnosisSafe.ts      # Gnosis Safe integration
│   │   └── erc4337.ts         # ERC-4337 (placeholder)
│   │
│   ├── transaction/            # Transaction helpers
│   │   └── execution.ts       # Transaction execution
│   │
│   └── balance/                # Balance helpers
│       └── index.ts           # Balance fetching
│
├── utils/                       # Utility functions
│   ├── security.ts             # Security utilities
│   ├── encryption.ts           # Encryption utilities
│   ├── monitoring.ts           # Monitoring service
│   └── constants.ts            # Application constants
│
├── __tests__/                   # Test files
│   ├── security.test.ts       # Security utility tests
│   ├── encryption.test.ts     # Encryption tests
│   ├── rateLimiter.test.ts    # Rate limiter tests
│   ├── nonceManager.test.ts   # Nonce manager tests
│   └── integration/           # Integration tests
│       ├── walletManagement.test.ts
│       ├── transactionFlow.test.ts
│       └── multisigApproval.test.ts
│
├── docs/                        # Documentation
│   ├── README.md              # Documentation index
│   ├── 01-overview.md         # Architecture overview
│   ├── 02-setup.md            # Setup guide
│   ├── 03-structure.md        # This file
│   └── ...                    # Other documentation
│
├── public/                      # Static assets
│   └── ...                    # Images, icons, etc.
│
├── style/                       # Styles and themes
│   └── theme.ts               # Chakra UI theme
│
├── types.ts                     # TypeScript type definitions
├── package.json                 # Dependencies and scripts
├── tsconfig.json                # TypeScript configuration
├── next.config.js               # Next.js configuration
├── jest.config.js               # Jest configuration
├── jest.setup.js                # Jest setup
├── vercel.json                  # Vercel deployment config
└── README.md                    # Project README

Key Files Explained

Application Entry Points

app/layout.tsx

Root layout component that wraps all pages. Sets up metadata and global layout structure.

app/page.tsx

Main home page component. Renders the main application interface.

app/providers.tsx

Sets up all global React contexts:

• Chakra UI provider
• Wagmi configuration
• RainbowKit provider
• SafeInject provider
• SmartWallet provider
• Transaction provider
• Error boundary

Core Components

components/Body/index.tsx

Main orchestrator component that:

• Manages connection methods (WalletConnect, iFrame, Extension)
• Handles address resolution
• Manages network selection
• Coordinates transaction creation
• Renders appropriate tabs

components/SmartWallet/WalletManager.tsx

Manages smart wallet list:

• Displays configured wallets
• Allows wallet selection
• Connects to existing wallets
• Opens deployment modal

components/TransactionExecution/TransactionBuilder.tsx

Transaction creation interface:

• Native token transfers
• ERC20 token transfers
• Raw transaction data
• Gas estimation

Context Providers

contexts/SafeInjectContext.tsx

Manages iframe communication:

• Safe App SDK integration
• postMessage handling
• Transaction forwarding
• Safe info retrieval

contexts/SmartWalletContext.tsx

Manages smart wallet state:

• Wallet configuration
• Owner management
• Threshold configuration
• Balance tracking
• Encrypted storage

contexts/TransactionContext.tsx

Manages transaction lifecycle:

• Transaction creation
• Approval workflow
• Execution methods
• Transaction history
• Rate limiting
• Nonce management

Helper Modules

helpers/communicator.ts

Secure message communication:

• Message validation
• Replay protection
• Origin validation
• Message routing

helpers/smartWallet/gnosisSafe.ts

Gnosis Safe integration:

• Safe contract interaction
• Safe SDK usage
• Safe deployment
• Safe info retrieval

helpers/transaction/execution.ts

Transaction execution:

• Direct on-chain execution
• Relayer execution
• Transaction simulation
• Gas estimation

Utility Modules

utils/security.ts

Security utilities:

• Address validation
• Transaction validation
• Rate limiting
• Nonce management
• Input sanitization

utils/encryption.ts

Encryption utilities:

• AES-GCM encryption
• PBKDF2 key derivation
• Secure storage wrapper
• Session key management

utils/monitoring.ts

Monitoring service:

• Centralized logging
• Error tracking
• Security event tracking
• Performance metrics

utils/constants.ts

Application constants:

• Security constants
• Network constants
• Storage keys
• Error messages
• Default values

Type Definitions

types.ts

Central type definitions including:

• SmartWalletConfig - Wallet configuration
• TransactionRequest - Transaction data
• SafeInfo - Safe contract info
• WalletBalance - Balance information
• TransactionStatus - Transaction states
• SDK message types
• Network types

Configuration Files

package.json

• Dependencies
• Scripts
• Project metadata

tsconfig.json

TypeScript configuration:

• Compiler options
• Path aliases
• Type definitions

next.config.js

Next.js configuration:

• Webpack settings
• Environment variables
• Build optimizations

jest.config.js

Jest test configuration:

• Test environment
• Coverage settings
• Module resolution

File Naming Conventions

Components

• PascalCase: WalletManager.tsx
• One component per file
• Descriptive names

Utilities

• camelCase: security.ts
• Descriptive names
• Grouped by functionality

Tests

• Same name as source file: security.test.ts
• Located in __tests__/ directory
• Integration tests in __tests__/integration/

Types

• PascalCase interfaces: SmartWalletConfig
• Enums: TransactionStatus
• Centralized in types.ts

Import Patterns

Absolute Imports

import { useSmartWallet } from "@/contexts/SmartWalletContext";
import { validateAddress } from "@/utils/security";

Relative Imports

import WalletManager from "../SmartWallet/WalletManager";
import { getSafeInfo } from "../../helpers/smartWallet/gnosisSafe";

Code Organization Principles

1. Separation of Concerns

• UI components separate from business logic
• Helpers separate from contexts
• Utilities separate from components

2. Single Responsibility

• Each file has one clear purpose
• Functions do one thing well
• Components are focused

3. Reusability

• Shared utilities in utils/
• Reusable components in components/
• Common helpers in helpers/

4. Type Safety

• All functions typed
• Interfaces for data structures
• Type guards where needed

Adding New Features

Adding a New Component

1. Create file in appropriate components/ subdirectory
2. Export component
3. Add to parent component or page
4. Add tests in __tests__/

Adding a New Helper

1. Create file in appropriate helpers/ subdirectory
2. Export functions
3. Add JSDoc comments
4. Add tests

Adding a New Utility

1. Create file in utils/
2. Export functions/classes
3. Add to constants if needed
4. Add tests

Adding a New Context

1. Create file in contexts/
2. Export provider and hook
3. Add to app/providers.tsx
4. Add tests

Best Practices

1. Keep files focused - One responsibility per file
2. Use TypeScript - Leverage type safety
3. Add JSDoc - Document public APIs
4. Write tests - Test new functionality
5. Follow naming - Use established conventions
6. Group related code - Keep related files together
7. Avoid deep nesting - Keep structure flat
8. Use constants - Extract magic numbers