VacciChain Frontend

Next.js 15 + TypeScript + Tailwind CSS frontend for blockchain-based vaccination records on Stellar.

Overview

VacciChain allows healthcare providers to issue soulbound, non-transferable vaccination NFTs to patients via Soroban smart contracts. Third parties (schools, employers, border agencies) can verify status on-chain without accessing personal details.

Features

• Wallet Integration: Freighter wallet support with Stellar network detection
• SEP-10 Authentication: Secure challenge-response authentication with JWT tokens
• Patient Dashboard: View all vaccination records chronologically
• Issuer Dashboard: Multi-step form to mint vaccination records
• Public Verification: Search any wallet to verify vaccination status
• Type-Safe: Full TypeScript with Zod validation
• Dark Medical-Tech Theme: Tailwind CSS with blue/green accents

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• State Management: React Hooks
• Validation: Zod + React Hook Form
• Wallet: Freighter API
• Blockchain: Stellar SDK
• Auth: SEP-10 Web Auth

Prerequisites

• Node.js 20+ (14MB of dependencies)
• npm or yarn
• Freighter wallet browser extension
• Stellar testnet account with XLM

Installation

# Clone and navigate
git clone <repo>
cd vaccichain-web

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your contract ID and backend URL

Environment Variables

# Stellar Network (testnet or mainnet)
NEXT_PUBLIC_STELLAR_NETWORK=testnet

# Soroban RPC Endpoint
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# Deployed VacciChain Contract
NEXT_PUBLIC_CONTRACT_ID=C...

# Backend API Base URL
NEXT_PUBLIC_BACKEND_URL=http://localhost:4000

Development

# Start dev server (http://localhost:3000)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

Project Structure

app/
├── layout.tsx           # Root layout
├── page.tsx             # Landing page
├── dashboard/
│   └── page.tsx         # Patient dashboard
├── issuer/
│   └── page.tsx         # Issuer dashboard
└── verify/
    └── page.tsx         # Public verification page

components/
├── WalletButton.tsx     # Connect/disconnect wallet
├── VaccinationCard.tsx  # Display vaccination record
├── VerificationBadge.tsx # Status badge
└── MintForm.tsx         # Issuer minting form

hooks/
├── useFreighter.ts      # Wallet & SEP-10 auth
└── useVaccination.ts    # API calls & verification

lib/
├── types.ts             # TypeScript interfaces
├── env.ts               # Environment & API routes
├── validation.ts        # Zod schemas
└── stellar-utils.ts     # Stellar helpers

Key Components

useFreighter Hook

Manages Freighter wallet connection and SEP-10 authentication:

• Detects Freighter availability
• Handles SEP-10 challenge-response flow
• Stores JWT in secure cookie
• Provides auth state and connect/disconnect methods

const { auth, connect, disconnect, loading, error } = useFreighter();

useVaccination Hook

Handles all vaccine-related API calls:

• fetchPatientRecords(wallet, jwt) - Get authenticated patient records
• verifyPublic(wallet) - Public verification (no auth)
• mintVaccination(formData, jwt) - Issue new record (issuer only)

const { verificationResult, records, loading, error, verifyPublic, mintVaccination } = useVaccination();

Pages

Landing Page (/)

• Project overview and feature highlights
• Call-to-action buttons based on auth state
• Navigation to dashboard/issuer/verify pages

Patient Dashboard (/dashboard)

• Requires authentication
• Displays all vaccination records in timeline
• Shows vaccine name, date, issuer, and status
• Indicates revoked records

Issuer Dashboard (/issuer)

• Restricted to authenticated issuers
• Multi-step form with validation:
  • Patient wallet address (Zod validated)
  • Vaccine name
  • Date administered
  • Issuer wallet (auto-populated)
• Success/error feedback
• Instructions for issuing records

Verification Page (/verify)

• Public access (no auth required)
• Search by wallet address
• Display vaccination status badge
• Show active/inactive status
• Optional: Display full records if vaccinated

Authentication Flow

1. User connects Freighter wallet
2. Request SEP-10 challenge from backend
3. Sign challenge with Freighter
4. Submit signed challenge to backend
5. Backend verifies & returns JWT + role
6. Store JWT in secure cookie
7. Include JWT in authenticated API calls

Security

• JWT tokens stored in secure, HTTP-only cookies
• SEP-10 challenge-response prevents replay attacks
• Zod validation on all forms
• No hardcoded secrets
• HTTPS only in production
• Freighter handles key management

API Integration

All API calls require a backend running on NEXT_PUBLIC_BACKEND_URL:

• POST /auth/sep10 - Get challenge
• POST /auth/verify - Verify signed challenge
• GET /vaccination/:wallet - Get patient records (auth required)
• POST /vaccination/issue - Mint record (issuer only)
• GET /verify/:wallet - Public verification (no auth)

Testing

Test flows:

1. Connect wallet - Use Freighter testnet account
2. Patient flow - View dashboard after auth
3. Issuer flow - Mint a record to test wallet
4. Verify flow - Search for vaccinated wallet
5. Public verify - Search without authentication

Troubleshooting

Issue	Solution
Freighter not detected	Install Freighter extension, refresh page
Network mismatch	Ensure Freighter is on Testnet
API errors	Check backend is running on NEXT_PUBLIC_BACKEND_URL
Auth fails	Clear cookies, reconnect wallet
Build fails	Ensure Node 20+, run npm install

Deployment

Vercel (Recommended)

# Push to GitHub
git push

# Deploy from Vercel dashboard
# Set environment variables in Vercel settings

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Static Export

# Configure next.config.js for static export
npm run build
# Output in .next/standalone

Contributing

1. Create feature branch
2. Follow TypeScript/Tailwind conventions
3. No any types
4. Test on testnet
5. Submit PR

License

MIT © VacciChain