System Architecture
Technical overview of ContractMind's infrastructure and design patterns
System Overview
Frontend
Next.js 14 + TypeScript
Backend
FastAPI + FastMCP
Blockchain
Solidity + Somnia
ContractMind follows a modern three-tier architecture with clear separation of concerns:
- Presentation Layer: Next.js frontend with Server Components and Client Components
- Application Layer: FastAPI backend with AI service integration
- Data Layer: PostgreSQL database + Blockchain state
Component Architecture
Frontend Components
Core Components
- • Web3Provider (Reown AppKit)
- • WalletGuard (Auth protection)
- • DashboardHeader (Navigation)
- • AgentCard (Agent display)
Features
- • Server-side rendering
- • Client-side routing
- • Real-time updates
- • Responsive design
Backend Services
Core Services
- • AI Service (Multi-provider)
- • Chat Service (Conversations)
- • Agent Service (CRUD)
- • Analytics Service (Metrics)
Infrastructure
- • FastMCP integration
- • WebSocket support
- • Database models (SQLAlchemy)
- • API routing
Smart Contracts
Core Contracts
- • ContractMindHubV2
- • AgentRegistry
- • HubAwareStaking
- • RegularStaking
Features
- • Hub-Aware Architecture
- • Upgradeable contracts
- • Event emission
- • Access control
Data Flow
1. User Interaction
User interacts with Next.js frontend → connects wallet via Reown AppKit
2. API Request
Frontend sends authenticated request → FastAPI backend validates and processes
3. Service Layer
Backend service layer processes business logic → interacts with AI providers or database
4. Data Storage
Data persisted to PostgreSQL → blockchain state updated via smart contracts
5. Response
Response returned to frontend → UI updated with new data
Hub-Aware Architecture
ContractMind implements a Hub-Aware Architecture pattern for smart contracts, enabling centralized coordination with decentralized execution.
Benefits
- ✓Centralized state management
- ✓Simplified upgrades
- ✓Consistent access control
- ✓Cross-contract coordination
Pattern
- • Hub contract stores global state
- • Spoke contracts register with hub
- • Hub validates all operations
- • Events emitted through hub
Security Architecture
Authentication
- • Wallet-based auth
- • Route protection
- • Session management
API Security
- • CORS configuration
- • Rate limiting
- • Input validation
Smart Contracts
- • Access control
- • Reentrancy guards
- • Upgrade patterns
Technology Stack
Frontend
- • Framework: Next.js 14
- • Language: TypeScript
- • Styling: Tailwind CSS
- • Web3: Wagmi + Viem + Reown AppKit
- • State: React Query
Backend
- • Framework: FastAPI
- • Language: Python 3.11+
- • Database: PostgreSQL
- • ORM: SQLAlchemy
- • AI: OpenAI, Claude, Gemini
Blockchain
- • Language: Solidity ^0.8.0
- • Framework: Foundry
- • Network: Somnia Testnet
- • Libraries: OpenZeppelin
DevOps
- • Containers: Docker
- • Hosting: Vercel, Render, AWS
- • CI/CD: GitHub Actions
- • Monitoring: CloudWatch