Frontend Only Package

The Frontend Package is a production-ready Next.js 16+ application with built-in authentication, security hardening, and modern development practices.

Tech Stack

Category	Technology
Framework	Next.js 16.1.1
Language	TypeScript 5
UI Library	React 19.2.3
Styling	Tailwind CSS 3.4
HTTP Client	Axios 1.13
Forms	React Hook Form 7.69 + Zod 4.3
Icons	Lucide React
Utilities	clsx, tailwind-merge, class-variance-authority

Key Features

Authentication & Security

// Example: Protected route with authentication
export default function Dashboard() {
  const { user, isLoading } = useAuth();
  
  if (isLoading) return <LoadingSpinner />;
  if (!user) return <Redirect to="/login" />;
  
  return <DashboardContent user={user} />;
}

Features:

Complete login, registration, password reset flows
Multi-Factor Authentication (MFA) with TOTP
Idle timeout with automatic logout
JWT token management with automatic refresh
Protected routes with auth context

User Management

Profile viewing and editing
Password change with verification
Email change with confirmation
Account deletion with grace period

Security Hardening

Content Security Policy (CSP) with nonces
Security headers (HSTS, X-Frame-Options, etc.)
NGINX reverse proxy with TLS 1.2/1.3
Rate limiting on authentication endpoints
Audit logs for security events

Project Structure

frontend/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── login/              # Login page
│   │   ├── register/           # Registration page
│   │   ├── dashboard/          # Protected dashboard
│   │   ├── security/           # Security settings
│   │   ├── profile/            # User profile
│   │   └── admin/              # Admin panel (optional)
│   ├── components/
│   │   ├── auth/               # Auth components (Login, Register, MFA)
│   │   ├── ui/                 # Reusable UI components
│   │   ├── dashboard/         # Dashboard components
│   │   └── security/           # Security settings components
│   ├── contexts/
│   │   └── AuthContext.tsx     # Authentication state
│   ├── hooks/
│   │   ├── useAuth.ts          # Authentication hook
│   │   └── useIdleTimeout.ts   # Idle timeout management
│   ├── lib/
│   │   ├── api.ts              # Axios client
│   │   ├── utils.ts            # Helper functions
│   │   └── auth.ts             # Auth utilities
│   └── types/                  # TypeScript types
├── public/                     # Static assets
├── nginx/                      # NGINX configuration
├── scripts/                    # Certificate generation scripts
└── docker-compose.yml          # Docker orchestration

Available Pages

Route	Description
`/login`	User login page
`/register`	User registration page
`/dashboard`	Protected user dashboard
`/profile`	User profile management
`/profile/edit`	Edit profile information
`/security`	Security settings
`/security/change-password`	Change password
`/security/mfa`	MFA setup and management
`/security/audit-logs`	View personal audit logs
`/admin`	Admin dashboard (requires admin role)

Quick Start

Installation

# Navigate to frontend directory
cd projects/fss/frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local

# Configure your .env.local with API URL
# NEXT_PUBLIC_API_URL=https://your-backend-api.com

# Start development server
npm run dev

Environment Variables

# API Configuration
NEXT_PUBLIC_API_URL=https://localhost:3443
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Authentication
JWT_TOKEN_NAME=auth_token
JWT_REFRESH_TOKEN_NAME=refresh_token

# Security
NEXT_PUBLIC_CAPTCHA_SITE_KEY=your-site-key

Authentication Flow

Security Best Practices

✅ Use HTTPS in production ✅ Enable CSP headers ✅ Implement rate limiting ✅ Use HTTP-only cookies for tokens ✅ Enable MFA for all users ✅ Log all authentication events ✅ Regularly rotate JWT secrets

Connecting to Backend

API Configuration

// lib/api.ts
import axios from 'axios';

export const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Request interceptor for JWT
api.interceptors.request.use((config) => {
  const token = getToken();
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Response interceptor for token refresh
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      await refreshToken();
      return api.request(error.config);
    }
    return Promise.reject(error);
  }
);

Customization

Theming

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
        },
      },
    },
  },
};

Adding New Pages

# Create new page structure
src/app/
└── new-feature/
    ├── page.tsx          # Main page component
    └── components/       # Page-specific components

AI Components

The frontend includes ready-made AI components and a hook that connect to the backend /ai/* endpoints. No extra setup is required beyond having at least one AI provider key configured in the backend.

Drop-in Chat Page

// src/app/ai-chat/page.tsx
'use client';
import { useEffect, useState } from 'react';
import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
import { AIChatInterface } from '@/components/ai';
import { aiAPI } from '@/lib/api';
import type { AIProviderInfo } from '@/types/ai';

export default function AIChatPage() {
  const [providers, setProviders] = useState<AIProviderInfo[]>([]);

  useEffect(() => {
    aiAPI.getProviders().then(setProviders).catch(console.error);
  }, []);

  return (
    <ProtectedRoute>
      <AIChatInterface
        providers={providers}
        systemPrompt="You are a helpful assistant."
        streaming={true}
        className="h-[600px]"
      />
    </ProtectedRoute>
  );
}

useAIChat Hook

import { useAIChat } from '@/hooks/useAIChat';

const { messages, isStreaming, error, sendMessageStream, sendMessage, clearMessages, stop } =
  useAIChat({ provider: 'openai', model: 'gpt-4o', systemPrompt: 'Be concise.' });

await sendMessageStream('What is the capital of France?');
stop(); // abort mid-stream

Available AI Files

File	Purpose
`src/types/ai.ts`	`AIMessage`, `AIChatOptions`, provider constants
`src/hooks/useAIChat.ts`	Chat state management and streaming
`src/components/ai/AIChatInterface.tsx`	Full drop-in chat UI
`src/components/ai/AIProviderSelector.tsx`	Provider + model dropdowns

Supported Providers & Models

Provider	Models
Anthropic	`claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`
OpenAI	`gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`
Google Gemini	`gemini-2.0-flash`, `gemini-2.5-pro`, `gemini-1.5-flash`
Groq	`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `mixtral-8x7b-32768`

See AI Integrations Guide for complete documentation.

.context Directory

The frontend includes a .context/ folder for AI coding agents:

File	Contents
`OVERVIEW.md`	Tech stack, ports, how to run
`ARCHITECTURE.md`	Routing, auth flow, API client, middleware
`COMPONENTS.md`	Component library, UI patterns
`AI-INTEGRATIONS.md`	AI chat component, hook, provider selector
`CONVENTIONS.md`	Code style, naming, patterns

Next Steps

Authentication Guide - Detailed auth documentation
AI Integrations - AI components and hook usage
User Management - Backend user module
Security Features - Security best practices
Deployment Guide - Production deployment

Tech Stack​

Key Features​

Authentication & Security​

User Management​

Security Hardening​

Project Structure​

Available Pages​

Quick Start​

Installation​

Environment Variables​

Authentication Flow​

Security Best Practices​

Connecting to Backend​

API Configuration​

Customization​

Theming​

Adding New Pages​

AI Components​

Drop-in Chat Page​

useAIChat Hook​

Available AI Files​

Supported Providers & Models​

.context Directory​

Next Steps​