Overview
iStory is built on a modern, production-ready stack that combines Web3 infrastructure, AI services, and cloud-native technologies. The architecture prioritizes security, scalability, and developer experience.Frontend Stack
Core Framework
Next.js 15.5.9
App Router with React 19 for performant, SEO-friendly experiences
TypeScript 5
Full type safety across the entire application
UI & Styling
Styling Dependencies
Styling Dependencies
- Tailwind CSS 4 - Utility-first CSS with dark/light mode support
- shadcn/ui - Accessible, customizable component library built on Radix UI
- Framer Motion - Production-ready animation library (~45 kB)
- Lucide React - Consistent iconography
- Radix UI - Headless, accessible UI primitives
State Management & Data Fetching
- TanStack Query (v5.90.2) - Server state management and caching
- React Hook Form (v7.63.0) - Performant form validation
- Zod (v3.25.76) - TypeScript-first schema validation
- Dexie (v4.3.0) - IndexedDB wrapper for local vault storage
Web3 & Blockchain
Network Configuration
iStory is deployed on Base Sepolia (Chain ID: 84532), an Ethereum Layer 2 that provides low-cost, fast transactions while maintaining Ethereum’s security guarantees.
Web3 Libraries
- Wagmi (v2.17.5) - React hooks for Ethereum
- Viem (v2.38.0) - TypeScript Ethereum interface
- RainbowKit (v2.2.8) - Wallet connection UI
Smart Contracts
EStoryToken
ERC20 token with 100M supply cap
StoryProtocol
Tips & paywall payment handling
StoryNFT
ERC721 NFTs for story books
Contract Addresses (Base Sepolia)
Contract Addresses (Base Sepolia)
lib/contracts.ts
AccessControl- Role-based permissionsPausable- Emergency stop mechanismReentrancyGuard- Protection against reentrancy attacksSafeERC20- Safe token transfers
Backend & Database
Supabase Infrastructure
| Client | Use Case | Location |
|---|---|---|
| Browser Client | Client components, browser operations | supabaseClient.ts |
| Server Client | API routes, SSR (uses cookies) | supabaseServer.ts |
| Admin Client | Admin operations (bypasses RLS) | supabaseAdmin.ts |
Database
- PostgreSQL via Supabase with Row Level Security
- Real-time subscriptions for notifications
- Supabase Storage for audio files and media
AI Services
Speech & Text Processing
ElevenLabs Scribe
Speech-to-text transcription (25MB file limit)
Google Gemini 2.5 Flash
Text enhancement and story analysis
Chainlink CRE Integration
CRE (Compute Runtime Environment) provides verifiable off-chain compute with on-chain attestation. See CRE Integration for details.
- Workflow SDK:
@chainlink/cre-sdkfor building verifiable AI workflows - Confidential HTTP: Encrypted communication with AI services
- DON Consensus: Multiple nodes validate AI analysis results
Storage & CDN
IPFS (Pinata)
- Story NFT metadata storage
- Book cover images
- Immutable content archiving
Security & Infrastructure
Middleware
- Route-specific rate limiting (in-memory store)
- CORS configuration for mobile app
- Security headers injection
Authentication
Dual Authentication System
Dual Authentication System
1. Wallet Authentication (Web3)
- Server-generated nonces (5-minute expiry)
- HMAC-signed linking tokens
- Custom JWT for wallet-authenticated users
- Google OAuth with redirect whitelist
- Supabase session JWT
- Account linking support
Security Headers
Testing Infrastructure
Vitest
Unit tests with React Testing Library
Playwright
E2E tests across Chrome, Firefox, Safari
- 38 tests for AI analysis endpoint
- 41 tests for StoryInsights component
- E2E navigation tests
- Mock factories for Supabase, Web Crypto API
Development Tools
Smart Contract Development
Code Quality
- ESLint - Code linting with Next.js config
- TypeScript - Strict mode enabled
- Prettier - Code formatting (via IDE integration)
Performance Optimizations
Bundle Size Budget
Target: Keep pages under 500 kB First Load JSCurrent (March 2026):
- Shared chunks: 104 kB
- Landing page: 426 kB
- Record page: 467 kB
- Profile page: 498 kB ✅
Applied Optimizations
Package Import Optimization
Package Import Optimization
next.config.mjs
Dynamic Imports
Dynamic Imports
- Three.js background: Dynamically loaded with
ssr: false - ProvidersDynamic: Web3 providers loaded only when needed
- Capability detection: Skips heavy animations on weak devices
Environment Variables
Deployment
Vercel (Recommended)
Build Verification
What’s Next?
Security Architecture
Learn about authentication, authorization, and security patterns
Database Schema
Explore the PostgreSQL schema and RLS policies
CRE Integration
Understand verifiable AI compute with Chainlink