PetChain Frontend

Overview

PetChain is a decentralized platform on Stellar that securely manages pet medical records. Today, health data is often scattered, lost, or stuck in outdated systems, making it hard to track vaccinations, manage treatments, or respond quickly in emergencies.

By making records tamper-proof and universally accessible, PetChain keeps vets and pet owners aligned no matter where the pet is or who is treating them. Pets get a scannable tag for quick access to key medical details, which can also act as a tracker if the pet goes missing.

This repository hosts the frontend (Next.js) application. A separate backend/ folder contains the NestJS API; the two are independently configured Node applications that are deliberately kept isolated (see Workspace layout).

Features

1. Scannable Pet Tags - Each pet gets a unique QR code and tag linked to its medical history, instantly scannable by vets or emergency responders (/scan/[id]).
2. Pet & Medical Records - Manage profiles, dental records, surgeries, appointments, and lab results with reference ranges.
3. Wallet & Stellar Integration - Create, back up, recover, sign, and send from a wallet on the Stellar network (/wallet), with multi-signature setup and transaction records (/transactions).
4. Clinics & Map - Browse clinic locations with geolocation and an interactive map (/clinics, /clinics/[id]).
5. Analytics & Admin - Route-level dashboards for engagement, pets, API usage, geographic distribution, financials, and compliance (/analytics), plus admin security, SMS, and reporting (/admin/*).
6. Notifications & Smart Alerts - Push and in-app notifications for vaccinations, check-ups, and security alerts (/notifications).
7. Offline Mode & PWA - Installable app with IndexedDB-backed offline caching and background sync (/offline).
8. Privacy & Compliance - GDPR-aligned data handling, zero-knowledge proofs (ZKPs) for sensitive on-chain data, session and two-factor security, and a documented data-classification policy.
9. Localization - Ten language locales (en, ar, de, es, fr, hi, ja, pt, ru, zh).

Browser Support & Feature Detection

PetChain degrades gracefully instead of failing when a browser lacks a capability. Runtime feature detection (src/lib/browserSupport.ts) gates every optional action behind a client-side check, so unsupported APIs are never invoked during SSR and users get clear guidance rather than a broken control.

Supported browser versions

Browser	Supported versions	Notes
Chrome / Edge (Chromium)	Last 2 stable releases	Full capability set
Firefox	Last 2 stable releases	Full capability set
Safari (macOS / iOS)	15.4+	WebCrypto and service workers supported; camera requires HTTPS
Mobile Chrome / Safari	Last 2 stable releases	Camera and file APIs require a secure context

Anything older than the versions above is treated as a degraded environment: the app still loads and read-only flows work, but capability-gated actions are disabled with an inline explanation.

Capability matrix and degraded behavior

Capability	Detection	When unavailable
Camera (getUserMedia)	navigator.mediaDevices?.getUserMedia	QR scanning and photo capture are disabled; users can upload an image file instead. Guidance: "Camera access isn't available in this browser. Upload a photo or enter the code manually."
WebCrypto (crypto.subtle)	window.crypto?.subtle	Client-side signing and ZKP helpers are disabled; the action is routed through the backend or blocked with guidance. Requires a secure context (HTTPS).
Service workers	'serviceWorker' in navigator	Offline caching and background sync are disabled; the app falls back to online-only mode and the /offline view shows a notice.
Wallet providers	window.stellar / injected provider probe	Wallet connect is disabled with guidance to install a supported wallet or use the built-in keypair flow.
File APIs (File, FileReader, Blob)	typeof File !== 'undefined' && typeof FileReader !== 'undefined'	Uploads and exports are disabled with guidance to use a supported browser.

SSR safety

All detection lives in src/lib/browserSupport.ts and is guarded by typeof window === 'undefined' checks. Components consume the results through a client-only hook, so no browser API is touched while rendering on the server. Detection results are cached per session and re-evaluated on the client after hydration.

Testing the matrix

Automated browser tests (Playwright) run the supported matrix (Chromium, Firefox, WebKit) plus one degraded environment that stubs out getUserMedia, crypto.subtle, and navigator.serviceWorker to assert that gated actions are disabled and guidance is shown. Run them with:

npm run test:e2e

Tech Stack

• Framework: Next.js (React + TypeScript)
• Styling: Tailwind CSS
• State / Data: React Context, Next.js API routes, REST client
• Blockchain: @stellar/stellar-sdk (Stellar network)
• Charts: Recharts (analytics, trends)
• Testing: Jest + Testing Library (unit), Playwright (e2e), k6 + Lighthouse (performance)
• Backend: NestJS (in backend/), PostgreSQL, TypeORM

Route Map

The current application exposes the following pages:

Route	Purpose
/	Landing / home
/login, /register, /forgot-password, /reset-password	Authentication
/two-factor, /verify-account, /verify-email	2FA and verification
/pets/[id]	Pet profile and medical records
/appointments, /surgeries, /dental, /lab-results	Care records
/clinics, /clinics/[id]	Clinics directory and location map
/wallet, /transactions	Stellar wallet and transaction history
/analytics	Analytics dashboards
/notifications, /activity-log, /sessions, /preferences	Notifications and account activity
/admin/security, /admin/reports, /admin/sms	Admin tooling
/scan/[id]	QR tag scanning
/offline	Offline reference view
/qrcode, /performance, /search, /profile, /account-settings	Utilities and profile

Server-side API routes under src/pages/api/ handle analytics metrics, blockchain sync, security metrics/alerts, ZKP generation/verification, web-vitals reports, webhooks, and observability.

Architecture & Data Flow

• Client rendering: Pages combine server-rendered data with client-side interactions. Optional, heavy features are loaded lazily (route-level bundle budgets in performance-budgets.json).
• Authentication: AuthContext drives session, login, registration, 2FA, and role-based access; admin-only pages enforce authorization server-side.
• Wallet: useWallet + walletService/StellarService talk to the Stellar network via a stored keypair; signing and multisig flows are isolated.
• Offline: Service worker + IndexedDB (src/lib/offline/indexedDB.ts) cache records, and syncManager.ts replays pending writes when connectivity returns.
• Analytics: Web vitals and product analytics are reported to the API (/api/web-vitals/report), and dashboards read aggregated API metrics.
• Privacy: Sensitive data is handled according to docs/data-classification.md; ZKP endpoints (/api/zkp/*) keep on-chain verification private.

See Architecture in PROJECT_STATUS.md for the current build status and known limitations.

Getting Started

Quick Start

# Clone the repository
git clone https://github.com/DogStark/petChain-Frontend.git
cd petChain-Frontend

# Use the correct Node.js version
nvm use

# Install dependencies (uses package-lock.json for reproducible installs)
npm ci

# Copy environment variables
cp .env.example .env.local

# Ensure the backend API is running on port 3001 (see backend/README.md)

# Start development server
npm run dev

Open http://localhost:3000 in your browser.

Prerequisites & Environment Matrix

Variable	Required	Description
NEXT_PUBLIC_APP_NAME / NEXT_PUBLIC_APP_URL	yes	Application identity
NEXT_PUBLIC_API_URL / NEXT_PUBLIC_API_VERSION	yes	Backend API base URL and version
NEXT_PUBLIC_STELLAR_NETWORK	yes	testnet or mainnet
NEXT_PUBLIC_STELLAR_HORIZON_URL	yes	Stellar Horizon endpoint
NEXT_PUBLIC_GA_ID	no	Google Analytics (product analytics)
NEXT_PUBLIC_SENTRY_DSN	no	Error monitoring

The backend API (in backend/) requires PostgreSQL, Redis, and Docker. See backend/README.md for its own environment and setup.

Verify the Setup

npm run type-check   # TypeScript type checking
npm run test:unit    # Jest unit tests (single discovery convention)
npm run lint         # ESLint
npm run build        # Production build

Workspace Layout

The repository intentionally isolates two independently configured Node applications:

• Frontend (root) - Next.js application. Its package.json, tsconfig*.json, jest.config.js, and scripts operate only on src/, tests/, performance/, and scripts/ files. The root does not compile backend/.
• Backend (backend/) - NestJS API with its own package.json, tsconfig, dependencies, and scripts. Install and run it from within backend/.

Keep frontend tooling changes and backend tooling changes isolated: never add backend dependencies to the root package.json, and never import backend code from the frontend source.

Contributing

Please read SETUP.md, CODE_STYLE.md, and PROJECT_STATUS.md before contributing. For a repeatable supply-chain posture, see the dependency-license policy in docs/license-policy.md and the API data-handling rules in docs/data-classification.md.

Important: Make sure you are working on the correct technology:

• Frontend: Next.js issues (root folder)
• Backend: NestJS issues (backend/ folder)

Documentation

• Setup Guide - Complete development setup instructions
• Code Style Guide - Coding standards and best practices
• Project Status - Current build status and progress
• Data Classification - Field-level classification and privacy rules
• Security Workflow - Security testing, audit, and incident response
• License Policy - Dependency and supply-chain checks
• Workspace Boundaries - Frontend/backend isolation rules
• Push Notifications - Notification architecture
• Reusable Workflows - CI workflow reference
• Testing Guide - How to run and write tests

Related Repositories

• Backend - DogStark/petchain_api
• Smart Contracts - DogStark/PetMedTracka-Contracts
• Mobile App - DogStark/PetMedTracka-MobileApp

Contact & Support

• Project lead: @llins_x
• Report issues via the linked repositories or the GitHub Issues tab.

License

PetChain is licensed under the MIT License.

Handsoff notes

• #1006: [Frontend] Add wallet transaction simulation expiry handling

• #1000: [Frontend] Add account-switch cache isolation across Next.js routes

• #997: [Frontend] Add route-level error boundaries with safe reset scopes