The Four Layers of Blockchain Application Architecture
Layer 1: Smart Contract Layer
The on-chain logic layer. Design decisions here are permanent — smart contract code cannot be altered after deployment (unless proxy-upgradeable). Every architectural decision at this layer has compounding consequences. Contract interaction graph: before writing code, map every contract in the system and every function call between them. State management strategy: on-chain state is expensive and permanent; store only ownership records, financial positions, governance decisions, and event logs on-chain. Upgrade architecture decision: immutable contracts are simpler and cheaper to audit; proxy-upgradeable contracts allow bug fixes and feature additions but introduce admin key risk.
Layer 2: Indexing Layer
The bridge between on-chain event data and queryable application data. The Graph protocol: deploy a subgraph that defines which contract events to index, how to map event parameters to entity schemas, and how to handle entity relationships. Custom event indexer: for applications with complex query requirements or high data volumes that exceed The Graph's capacity. This layer is commonly underestimated — developers expect to query data directly from their data source, but the blockchain provides extremely limited query capability.
Layer 3: Off-Chain Application Layer
Conventional Web2 backend services that complement the on-chain logic: Authentication service (if using centralized auth alongside wallet auth), Notification service (email, push notifications for on-chain events), Analytics pipeline (off-chain aggregation for dashboard metrics), KYC/AML service (for regulated applications), Admin service (internal tools for operations and compliance teams). The off-chain application layer should never be a point of failure for core user funds operations — those must be on-chain.
Layer 4: Client Layer
Web and mobile front-ends. Wallet integration: WalletConnect 2.0 for cross-wallet compatibility, wagmi hooks for React applications, social login wallets for mainstream users. RPC provider: Alchemy or Infura with fallback provider. State management: React Query for server state, Zustand or Jotai for client state, real-time state from WebSocket subscriptions.
Architecture Anti-Patterns to Avoid
- Storing user PII on-chain: permanent, public, undeletable — conflicts with CCPA and GDPR.
- Single-admin key control of production contracts: use Gnosis Safe multi-sig.
- Direct RPC queries in the front-end for complex data: always use an indexing layer.
- Synchronous front-end blocking on transaction confirmation: use optimistic UI updates with confirmation status tracking.
