Kaelocs Next.js Application

A modern Next.js application with TypeScript, Tailwind CSS, dependable CI/CD, and essential libraries for building production-ready web applications.

Features

• ⚡ Next.js 15 with App Router and Turbopack
• 🎨 Tailwind CSS 4 for styling
• 📘 TypeScript for type safety
• 🔐 NextAuth.js with Google OAuth for user authentication
• 🤖 Google Gemini 2.5 Flash AI integration
• 🛡️ Dual Authentication System - User & Admin layers
• 🧪 Vitest with React Testing Library for testing
• 🎯 ESLint and Prettier for code quality
• 🔄 React Query for server state management
• 🎭 Zustand for client state management
• 📝 React Hook Form with Zod validation
• 🌙 next-themes for dark mode support
• 🎨 Lucide React for beautiful icons

Getting Started

Prerequisites

• Node.js 18.19.1 or later
• npm 9.2.0 or later

Installation

1. Install dependencies:

npm install

2. Set up environment variables:

Copy the env.template file to .env.local:

cp env.template .env.local

Then edit .env.local and fill in your credentials:

• Google OAuth: Follow the Google Auth Setup Guide
• Admin Password: Set a secure password for admin access
• Google AI API Key: Get from Google AI Studio

For detailed Google OAuth setup instructions, see GOOGLE_AUTH_SETUP.md

Development

Run the development server:

npm run dev

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

Build

Build the application for production:

npm run build

Start Production Server

npm start

Available Scripts

• npm run dev - Start development server with Turbopack
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting
• npm test - Run tests with Vitest
• npm run test:ui - Run tests with UI
• npm run test:coverage - Run tests with coverage

Authentication System

This application uses a dual authentication system:

1. User Authentication (Google OAuth)

• Purpose: Save user progress and chat history across sessions
• Provider: Google OAuth via NextAuth.js
• Access Level: Anyone with a Google account can sign in
• Features:
  • Persistent user sessions
  • Chat history saved per user
  • Profile management

2. Admin Authentication (Password-based)

• Purpose: Gate access to AI/LLM features
• Method: Password authentication via Zustand store
• Access Level: Only users with admin credentials
• Features:
  • Required to use Gemini AI chat features
  • Independent of user authentication
  • Session-based access control

How it works:

• Users can sign in with Google to save their progress
• To actually use the AI features, they must also authenticate as admin
• Both authentications work independently and serve different purposes

Project Structure

├── app/                      # Next.js app directory
│   ├── api/
│   │   ├── auth/            # NextAuth API routes
│   │   └── chat/            # AI chat API endpoint
│   ├── auth/
│   │   └── signin/          # Custom sign-in page
│   ├── admin/
│   │   └── login/           # Admin login page
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   └── globals.css          # Global styles
├── components/              # React components
│   ├── ui/                  # UI components
│   ├── Chat.tsx             # Main chat component
│   ├── DarkVeil.tsx         # Animated background
│   └── providers.tsx        # App providers
├── lib/                     # Utility functions
│   ├── auth-store.ts        # Admin auth state
│   ├── brave-search.ts      # Web search integration
│   ├── web-fetcher.ts       # Web content fetcher
│   ├── utils.ts             # Helper utilities
│   └── constants.ts         # App constants
├── types/                   # TypeScript types
│   ├── index.ts             # Common types
│   └── next-auth.d.ts       # NextAuth type extensions
├── hooks/                   # Custom React hooks
├── test/                    # Test setup and utilities
└── public/                  # Static files

Technologies

Core

• Next.js - React framework
• React - UI library
• TypeScript - Type safety
• NextAuth.js - Authentication for Next.js

Styling

• Tailwind CSS - Utility-first CSS
• class-variance-authority - Component variants
• clsx - Class names utility
• tailwind-merge - Merge Tailwind classes

State Management & Data Fetching

• Zustand - State management
• React Query - Server state management
• Axios - HTTP client

Forms & Validation

• React Hook Form - Form handling
• Zod - Schema validation

UI & Icons

• Lucide React - Icons
• next-themes - Theme management

Testing

• Vitest - Test runner
• React Testing Library - Component testing

Code Quality

• ESLint - Linting
• Prettier - Code formatting

Security & Maintenance

• ✅ Automated dependency updates powered by Dependabot
• ✅ Continuous CodeQL scanning via GitHub Actions to catch security and quality regressions
• ✅ Security policy describing how to report vulnerabilities

Community & Support

• Read the Code of Conduct to understand our expectations
• Learn how to contribute in CONTRIBUTING.md and get help in SUPPORT.md
• Use the curated GitHub issue and PR templates so we can triage faster

License

MIT