PropChain Frontend

🏠 Decentralized Real Estate Platform | Modern Web3 frontend for blockchain-powered property transactions

PropChain Frontend is a cutting-edge React/Next.js application that provides a seamless user interface for interacting with tokenized real estate assets on the blockchain. Our platform offers an intuitive way to browse, invest in, and manage property NFTs through a beautiful, responsive web interface.

Built with modern web technologies and Web3 integration, this frontend serves as the user-facing layer for decentralized real estate transactions, enabling users to connect their wallets, explore property listings, and execute smart contract interactions with ease.

🚀 Features

Core Capabilities

• 🏠 Property Discovery: Browse and search tokenized real estate properties with advanced filtering
• 💰 Wallet Integration: Connect MetaMask, WalletConnect, and other Web3 wallets seamlessly
• ⚙️ Optimized Developer Diagnostics: Memoized error test scenarios for faster interactive debugging and smoother rendering
• 🎯 Route-Level Error Handling: Full-page route fallback UI with retry and home navigation using RouteErrorBoundary
• 🔗 Smart Contract Interaction: Execute property purchases, transfers, and management through intuitive UI
• 📊 Real-Time Data: Live property valuations, market trends, and portfolio analytics
• 🔐 Web3 Authentication: Secure wallet-based authentication with multi-network support
• � Responsive Design: Mobile-first design that works perfectly on all devices

Advanced Features

• 🌐 Multi-Chain Support: Switch between Ethereum, Polygon, and BSC networks
• 📈 Portfolio Dashboard: Track your real estate NFT investments and performance
• 🔍 Advanced Search: Filter by location, price range, property type, and ROI metrics
• �️ Security First: Hardware wallet support and transaction verification
• ⚡ Lightning Fast: Optimized performance with Next.js 15 and React 19

👥 Target Audience

This frontend is designed for:

• Real Estate Investors looking to diversify into blockchain property assets
• Crypto Enthusiasts seeking tangible real-world asset investments
• Property Developers wanting to tokenize their real estate projects
• Real Estate Agents adapting to the digital property marketplace
• DeFi Users exploring real estate as an alternative asset class

🛠️ Quick Start

Prerequisites

Ensure you have the following installed:

• Node.js v18+ (LTS recommended)
• npm package manager (this repo pins npm via the packageManager field and only commits package-lock.json — CI runs npm ci)
• Git version control
• Web3 Wallet (MetaMask, Trust Wallet, etc.)

Installation

# 1. Clone the repository
git clone https://github.com/MettaChain/PropChain-FrontEnd.git
cd PropChain-FrontEnd

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# 4. Start development server
npm run dev

The application will be available at http://localhost:3000.

🚀 Development & Deployment

Development Environment

npm run dev          # Start development server with hot reload
npm run lint         # Run ESLint for code quality checks
npm run typecheck    # Run TypeScript type checking

Mocking

For details on local mocking, see the mocking documentation.

Production Build

npm run build         # Build optimized production bundle (runs typecheck first)
npx next start        # Serve the built production bundle
npm run build:analyze # Analyze bundle size (webpack-bundle-analyzer)

Testing Suite

npm test               # Run unit tests (Jest)
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Generate coverage report
npm run test:e2e       # Run end-to-end tests (Playwright)
npm run test:cy:component # Run component tests (Cypress) — also runs in CI

🌐 Network Configuration

Supported Blockchains

• Ethereum (Mainnet, Sepolia Testnet)
• Polygon (Mainnet, Mumbai Testnet)
• Binance Smart Chain (Mainnet, Testnet)
• Local Development (Hardhat Network)

Environment Configuration

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3001

# Blockchain
NEXT_PUBLIC_BLOCKCHAIN_NETWORK=sepolia
NEXT_PUBLIC_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
NEXT_PUBLIC_CHAIN_ID=11155111

# Features
NEXT_PUBLIC_ENABLE_ANALYTICS=true
NEXT_PUBLIC_ENABLE_TESTNET=true

# Third-party Services
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=your_ga_id
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn

📚 Documentation & Resources

Project Documentation

• 🔧 Mocking - Local mocking and development overrides
• 🗄️ Cache API - Caching model and invalidation rules
• 🎣 Hooks Guide - Custom hooks reference
• 🔌 Smart Contract Integration - Contract wiring and ABIs
• ⚡ Lazy Loading - Bundle-splitting and lazy-loading patterns
• 🔒 CSP & Security Headers - Content Security Policy configuration
• 🛡️ Phishing Denylist - Suspicious-domain protections

Repository Structure

PropChain-FrontEnd/
├── 📁 src/
│   ├── 📁 app/             # Next.js 15 App Router pages and layouts
│   ├── 📁 components/      # Reusable React components
│   ├── 📁 hooks/           # Custom React hooks
│   ├── 📁 lib/             # Utility functions and configurations
│   ├── 📁 store/           # State management (Zustand/Redux)
│   ├── 📁 types/           # TypeScript type definitions
│   └── 📁 styles/          # Global styles and Tailwind CSS
├── 📁 public/              # Static assets (images, icons)
├── 📁 docs/                # Project documentation
├── 📁 tests/               # Unit, integration, and E2E tests
├── 📁 .github/             # CI/CD workflows and issue templates
└── 📁 scripts/             # Build and deployment scripts

Contributing

• 🤝 Contributing Guide - How to contribute effectively
• Report Issues: https://github.com/MettaChain/PropChain-FrontEnd/issues

The repository does not currently ship a CODE_OF_CONDUCT.md or .github/ISSUE_TEMPLATE/ — these are tracked as follow-up work.

Additional Resources

• 🔌 Backend API - Server-side NestJS application

🛠️ Technology Stack

Frontend Framework

• ⚛️ Framework: Next.js 15 with App Router - Modern React framework
• 🎨 UI Library: React 19 - Latest React with concurrent features
• 🎭 Styling: Tailwind CSS 4 - Utility-first CSS framework
• � Components: Headless UI + custom components - Accessible UI primitives

State Management & Data

• 🔄 State: Zustand - Lightweight state management
• 🌐 Data Fetching: TanStack Query (React Query) - Server state management
• 🔗 Web3: ethers.js + wagmi - Modern Ethereum React hooks
• 📝 Forms: React Hook Form + Zod - Type-safe form handling

Development & Tooling

• � Language: TypeScript 5 - Type-safe JavaScript
• 🧪 Testing: Jest + Testing Library + Playwright - Comprehensive testing
• � Bundling: Next.js built-in webpack - Optimized bundling
• 🔧 Linting: ESLint + Prettier - Code quality and formatting
• 🐳 Containerization: Docker - Consistent development environment

UI/UX & Performance

• 🎨 Design: Tailwind CSS + custom design system - Consistent styling
• � Analytics: Google Analytics + Vercel Analytics - User insights
• � SEO: Next.js SEO optimizations - Search engine friendly
• ⚡ Performance: Next.js optimizations + lazy loading - Fast loading

---

📝 Logging

All application code MUST log through the canonical logger at @/utils/logger:

import { logger } from "@/utils/logger";

logger.debug("…");
logger.info("…");
logger.warn("…");
logger.error("…", errorObject);

Why a single import path?

• One canonical implementation owns redaction, correlation IDs, JSON output, environment-aware levels, and singleton config (configureLogger).
• The legacy @/utils/structuredLogger module is kept as a thin backwards-compat wrapper (re-exports + a domain-specific StructuredLogger class with batching/remote delivery). It is marked @deprecated and an ESLint no-restricted-imports rule blocks new imports outside the wrapper itself. New code MUST NOT import from it.
• Direct console.* calls are blocked by ESLint for everything except src/utils/earlyErrorSuppression.ts, which intentionally operates on the raw global console because it runs before logger is initialised to silence noisy browser-extension errors.

Backwards compatibility

@/utils/structuredLogger re-exports logger, createLogger, LogLevel, etc. from the canonical module so existing call sites continue to work without changes. The wrapper itself (StructuredLogger, logNetworkRequest, logWeb3Activity, logTransaction) is preserved for callers that rely on its batching/remote-send semantics.

---

🔗 Contract ABI codegen

wagmi.config.ts generates typed contract hooks from the ABIs in src/config/abis into src/generated.ts. That file is not committed, so run codegen after installing dependencies (and again whenever an ABI changes):

npm run contracts:generate

---

📊 Build stats plugin

next.config.ts includes a small BuildStatsPlugin that writes a JSON snapshot of webpack output to .next/build-stats.json for local inspection.

To keep production builds lean and quiet, the plugin is gated by two conditions:

Condition	Value
process.env.ANALYZE	MUST be set to 'true'
process.env.NODE_ENV	MUST NOT be production
Server-side build?	Plugin is client-only — skipped on isServer

In other words:

# Quiet (default for `next build` in production)
npm run build

# Opt-in to the JSON build-stats snapshot — local dev only
ANALYZE=true npm run dev    # or: ANALYZE=true next build

Production CI MUST NOT pass ANALYZE=true; if it does the plugin is still disabled by the NODE_ENV === 'production' guard.

---

📦 Bundle size budgets

Budgets for key .next/static/chunks output are defined in .size-limit.json (main bundle, framework bundle, total JS) and enforced by size-limit. Run after a production build:

npm run build
npm run size

CI runs this as part of the build job, so a bundle that grows past a budget fails the build.

---

📄 License

This repository does not currently ship a LICENSE file. The license decision is tracked by the maintainers; until then the project's default copyright reserves apply (see the Contributing Guide).

🤝 Support & Community

Get Help

• 🐛 Report Issues: GitHub Issues
• 📧 Email Support: frontend@propchain.io
• 📖 Documentation: docs.propchain.io

Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Quick contribution steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

⭐ Star this repository if it helped you!

Made with ❤️ by the PropChain Team

🛠️ Local Development Guardrails (Git Hooks)

To maximize code reliability and streamline PR review cycles, this project uses Husky to enforce local quality validation checks prior to remote integration.

Active Git Hook Safeguards

• Pre-Commit Hook: Triggered automatically upon running git commit. Performs light syntax linting on modified files.
• Pre-Push Hook: Triggered automatically when executing git push. This gate forces an application-wide compile verification check (tsc --noEmit) and runs all matching unit tests. If compilation faults are surfaced or unit assertions fail, the push is safely aborted locally, keeping broken code off the remote origin branch.

Bypassing in Emergencies

If you must explicitly push an intermediate draft up to a private backup branch without running validations, you can bypass Husky checks by appending the --no-verify flag:

git push origin feature/my-branch --no-verify

Alternatively, the pre-push hook itself honors a SKIP_PREPUSH=1 env var:

SKIP_PREPUSH=1 git push origin feature/my-branch